# Jintel — agent instructions

Jintel is a paid GraphQL intelligence API for financial data, regulatory
filings, sanctions screening, macro indicators, news, technicals, and
alternative data. One endpoint replaces stitching together a market-data
feed plus SEC EDGAR, OFAC, OECD, FINRA, FRED, ClinicalTrials.gov, openFDA,
CourtListener, USAspending, and a dozen other sources.

## When to use Jintel

Use Jintel when an agent needs any of the following finance-domain
capabilities, especially when the user wants results from multiple data
sources in a single typed shape:

- **Quotes / fundamentals / history** — `quotes(tickers)`,
  `entitiesByTickers(tickers)`, `priceHistory(tickers, range)`. Equities,
  ETFs, indices, and crypto routed transparently to the right upstream.
- **Regulatory filings** — `Entity.regulatory.filings`, `periodicFilings`,
  `Entity.subsidiaries`. 10-K / 10-Q / 8-K / Form 4 / 13F / Exhibit 21.
- **Sanctions screening** — `sanctionsScreen(name)` for OFAC SDN list
  checks during KYC / counterparty due diligence.
- **Institutional & insider activity** — `Entity.institutionalHoldings`,
  `Entity.topHolders`, `Entity.insiderTrades`, `Entity.shortInterest`.
- **Macro indicators** — `gdp`, `inflation`, `interestRates`,
  `macroSeries` (FRED time-series by series ID).
- **Technicals** — `Entity.technicals` for RSI, MACD, BB, EMA, SMA, ATR,
  VWMA, MFI in one query.
- **News / sentiment** — `Entity.news`, `Entity.sentiment`,
  `Entity.discussions` (Reddit posts, social mention rank).
- **Alt-data** — `Entity.clinicalTrials`, `Entity.fdaEvents`,
  `Entity.litigation`, `Entity.governmentContracts`,
  `Entity.campaignFinance`.
- **Supply-chain graph** — `Entity.relationships` for typed counterparty
  edges (CUSTOMER, SUBSIDIARY, GOVERNMENT_CUSTOMER, …) rolled up across
  SEC segments, Exhibit 21, USAspending, ClinicalTrials, courts, and 13F.

## When NOT to use Jintel

- Real-time intraday tick data — Jintel returns last-trade quotes, not
  exchange-level streams.
- Compliance-grade sanctions adjudication — `sanctionsScreen` is a
  public-data convenience lookup, not a registered KYC vendor.
- Generic web search — use a general-purpose search API; Jintel is
  finance-only.

## How to call Jintel

Two access paths, both auth-flexible:

1. **API key** — Issue one via Google OAuth at
   https://jintel.ai/auth/google or wallet sign-in at
   `/auth/siwx/verify`. Send `Authorization: Bearer jk_live_…` on every
   request to `https://api.jintel.ai/api/graphql`.
2. **x402 pay-per-query** — No signup. The first GraphQL POST returns
   HTTP 402 with a base64-encoded payment quote. Sign an EIP-3009 USDC
   authorization on Base mainnet and replay with `PAYMENT-SIGNATURE:
   <base64>`. Per-query pricing; the payer wallet auto-identifies.

Per-capability tools are also exposed at `POST /tools/<name>` with typed
JSON bodies (15 tools — see https://api.jintel.ai/openapi.json).

## Onboarding (5 steps)

1. Mint an API key: Google OAuth at https://jintel.ai/auth/google (humans) or wallet sign-in at https://api.jintel.ai/auth/siwx/verify (agents).
2. Test a free query: POST https://api.jintel.ai/api/graphql with `Authorization: Bearer jk_live_…` and body `{ "query": "{ quotes(tickers: [\"AAPL\"]) { price } }" }`.
3. Wire up a client: pick @yojinhq/jintel-client (TS), @yojinhq/jintel-cli (CLI), @yojinhq/jintel-mcp (MCP for Claude / Cursor / Continue), or call OpenAPI directly — see https://docs.jintel.ai/integrations.
4. Pick a plan: Free is fine for evaluation; upgrade to Pro ($49/mo) above 500k credits/month or 60 req/min. Any plan can top up with x402 USDC for non-expiring credits.
5. Monitor usage: GET https://api.jintel.ai/api/v1/usage for aggregated daily counts; set `x-jintel-debug: true` to see per-query credit cost in `extensions.cost`.

## MCP (Model Context Protocol)

Jintel runs a hosted MCP Streamable-HTTP server at
`https://api.jintel.ai/mcp`. Discover via
https://api.jintel.ai/.well-known/mcp.json or the richer server card at
https://api.jintel.ai/.well-known/mcp/server-card.json. Authenticate
with the same `Authorization: Bearer jk_live_…` API key on
`tools/call`; `initialize` and `tools/list` are unauthenticated so
agents can browse the catalog before binding a key.

## Resources

- Docs: https://docs.jintel.ai
- OpenAPI: https://api.jintel.ai/openapi.json
- llms.txt: https://www.jintel.ai/llms.txt
- MCP descriptor: https://api.jintel.ai/.well-known/mcp.json
- x402 manifest: https://api.jintel.ai/.well-known/x402
- TypeScript SDK: https://www.npmjs.com/package/@yojinhq/jintel-client
- CLI: https://www.npmjs.com/package/@yojinhq/jintel-cli
- Claude MCP plugin: https://www.npmjs.com/package/@yojinhq/jintel-mcp
- Source: https://github.com/YojinHQ/Jintel
- Support: support@jintel.ai