# stockmarketapi.ai — full endpoint reference

> Complete endpoint reference generated from the live OpenAPI schema, for LLM
> consumption. Shorter overview: https://stockmarketapi.ai/llms.txt · Interactive docs:
> https://stockmarketapi.ai/api/docs · OpenAPI 3.1 JSON: https://stockmarketapi.ai/api/openapi.json

## Authentication

Include an `X-API-Key` header on every request. Keys are free:

```
POST /api/v1/auth/keys
Content-Type: application/json
{"email": "you@example.com"}
```

Tiers: Free, Pro ($19/mo), Pro Plus ($49/mo) — https://stockmarketapi.ai/pricing

## Agentic payments (x402)

`POST /payments/agent-subscribe` — gasless EIP-712 USDC on Base; an agent gets
a paid API key in two HTTP calls. Machine-readable pricing catalog:
`GET /api/v1/agentic/routes`.

## Endpoints

### Authentication

- **POST** `/api/v1/auth/keys` — Create Api Key
- **DELETE** `/api/v1/auth/keys` — Revoke Api Key
- **GET** `/api/v1/auth/keys/me` — Get Current Key Info
- **POST** `/api/v1/auth/keys/rotate` — Rotate Api Key

### Billing

- **GET** `/api/v1/billing/cancel` — Payment Cancel
- **POST** `/api/v1/billing/cancel` — Cancel Subscription
- **POST** `/api/v1/billing/checkout/crypto` — Create Crypto Checkout
- **POST** `/api/v1/billing/checkout/stripe` — Create Stripe Checkout
- **GET** `/api/v1/billing/checkout/stripe/start` — Start Stripe Checkout
  - params: `plan` (query, required, string)
- **POST** `/api/v1/billing/portal` — Billing Portal
- **GET** `/api/v1/billing/subscription` — Get Subscription
- **GET** `/api/v1/billing/success` — Payment Success
  - params: `session_id` (query, string)
- **POST** `/api/v1/billing/webhooks/coinbase` — Coinbase Webhook
- **POST** `/api/v1/billing/webhooks/stripe` — Stripe Webhook

### Payments

- **POST** `/payments/agent-subscribe` — Agent Subscribe (x402 Gasless Payment)
- **GET** `/payments/invoices` — List Invoices
- **GET** `/payments/invoices/{number}` — Get Invoice
  - params: `number` (path, required, string); `format` (query, string)
- **GET** `/payments/plans` — Get Plans
- **POST** `/payments/subscribe` — Subscribe
- **GET** `/payments/subscription` — Get Subscription

### Wallet Auth

- **POST** `/wallet/challenge` — Create Challenge
- **GET** `/wallet/session` — Get Session
- **POST** `/wallet/verify` — Verify Signature

### Wallet Payments

- **GET** `/wallet/config` — Wallet Config
- **POST** `/wallet/create-solana-tx` — Create Solana Tx
- **GET** `/wallet/invoices` — List Invoices
- **GET** `/wallet/invoices/{number}` — Download Invoice
  - params: `number` (path, required, string)
- **GET** `/wallet/solana-blockhash` — Solana Blockhash
- **GET** `/wallet/solana-confirm/{signature}` — Solana Confirm
  - params: `signature` (path, required, string)
- **POST** `/wallet/upgrade` — Upgrade Plan

### calendar

- **GET** `/api/v1/calendar` — Get Calendar
  - params: `year` (query, integer); `month` (query); `exchange` (query); `ticker` (query); `status` (query); `filing_type` (query); `page` (query, integer); `page_size` (query, integer)

### commodities

- **GET** `/api/v1/commodities/catalog` — Get Commodity Catalog
- **GET** `/api/v1/commodities/quotes` — Get Commodity Quotes
  - params: `symbols` (query, required, string); `currency` (query, string)
- **GET** `/api/v1/commodities/{symbol}/prices` — Get Commodity Prices
  - params: `symbol` (path, required, string); `range` (query, string); `interval` (query, string); `currency` (query, string); `source` (query)

### companies

- **GET** `/api/v1/companies` — List Companies
  - params: `page` (query, integer); `page_size` (query, integer); `sector` (query); `exchange` (query); `security_type` (query)
- **GET** `/api/v1/companies/bulk` — Bulk Get Companies
  - params: `tickers` (query, required, string)
- **GET** `/api/v1/companies/coverage` — Get Coverage
  - params: `exchange` (query); `security_type` (query)
- **GET** `/api/v1/companies/metrics/bulk` — Bulk Get Metrics
  - params: `tickers` (query); `symbols` (query)
- **GET** `/api/v1/companies/quotes` — Get Quotes
  - params: `symbols` (query, required, string)
- **GET** `/api/v1/companies/search` — Search Companies
  - params: `q` (query, required, string); `page` (query, integer); `page_size` (query, integer)
- **GET** `/api/v1/companies/{ticker}` — Get Company
  - params: `ticker` (path, required, string); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/analyst` — Get Company Analyst Consensus
  - params: `ticker` (path, required, string); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/completeness` — Get Company Completeness
  - params: `ticker` (path, required, string); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/data-issues` — Get Company Data Issues
  - params: `ticker` (path, required, string); `status` (query); `issue_type` (query); `limit` (query, integer); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/filings` — Get Company Filings
  - params: `ticker` (path, required, string); `form_type` (query); `source` (query); `limit` (query, integer); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/filings/{accession_number}/download` — Download Filing
  - params: `ticker` (path, required, string); `accession_number` (path, required, string); `format` (query, string); `exchange` (query); `X-API-Key` (header)
- **GET** `/api/v1/companies/{ticker}/financials` — Get Company Financials
  - params: `ticker` (path, required, string); `period_type` (query); `period` (query); `cash_flow` (query); `quarters_only` (query, boolean); `limit` (query, integer); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/holdings` — Get Etf Holdings
  - params: `ticker` (path, required, string); `limit` (query, integer); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/logo` — Company Logo
  - params: `ticker` (path, required, string); `theme` (query); `format` (query); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/metrics` — Get Company Metrics
  - params: `ticker` (path, required, string); `period_end` (query); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/metrics/history` — Get Company Metrics History
  - params: `ticker` (path, required, string); `periods` (query, integer); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/metrics/summary` — Get Company Metrics Summary
  - params: `ticker` (path, required, string); `period` (query); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/news` — Get Company News
  - params: `ticker` (path, required, string); `limit` (query, integer); `offset` (query, integer); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/prices` — Get Company Prices
  - params: `ticker` (path, required, string); `range` (query, string); `interval` (query, string); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/sector-stats` — Get Company Sector Stats
  - params: `ticker` (path, required, string); `exchange` (query)
- **GET** `/api/v1/companies/{ticker}/technicals` — Get Company Technicals
  - params: `ticker` (path, required, string); `exchange` (query)

### completion

- **POST** `/api/v1/companies/{ticker}/complete` — Request Completion
  - params: `ticker` (path, required, string); `force` (query, boolean)
- **GET** `/api/v1/companies/{ticker}/completion` — Get Latest Completion
  - params: `ticker` (path, required, string)
- **GET** `/api/v1/companies/{ticker}/completion/{request_id}` — Get Completion
  - params: `ticker` (path, required, string); `request_id` (path, required, string)

### data quality

- **GET** `/api/v1/data-issues` — List Data Issues
  - params: `status` (query); `issue_type` (query); `severity` (query); `ticker` (query); `since` (query); `until` (query); `page` (query, integer); `page_size` (query, integer)

### formulas

- **GET** `/api/v1/formulas` — List Formulas
  - params: `category` (query)
- **GET** `/api/v1/formulas/categories` — List Categories
- **GET** `/api/v1/formulas/{name}` — Get Formula By Name
  - params: `name` (path, required, string)

### fx

- **GET** `/api/v1/fx/rates` — Get Fx Rate
  - params: `pair` (query, string)
- **GET** `/api/v1/fx/rates/history` — Get Fx Rate History
  - params: `pair` (query, string); `range` (query, string)

### health

- **GET** `/api/v1/health` — Health Check
- **GET** `/api/v1/ready` — Readiness Check

### indices

- **GET** `/api/v1/indices` — List Indices
- **GET** `/api/v1/indices/catalog` — Get Index Catalog
- **GET** `/api/v1/indices/quotes` — Get Index Quotes
  - params: `symbols` (query, required, string)
- **GET** `/api/v1/indices/{index_name}` — Get Index Members
  - params: `index_name` (path, required, string); `sector` (query)
- **GET** `/api/v1/indices/{symbol}/prices` — Get Index Prices
  - params: `symbol` (path, required, string); `range` (query, string); `interval` (query, string)

### jobs

- **GET** `/api/v1/jobs` — List Jobs
  - params: `job_name` (query); `status` (query); `page` (query, integer); `page_size` (query, integer)
- **GET** `/api/v1/jobs/{job_id}` — Get Job
  - params: `job_id` (path, required, integer)

### news

- **GET** `/api/v1/news` — Get Bulk News
  - params: `tickers` (query, string); `symbols` (query, string); `limit` (query, integer)
- **GET** `/api/v1/news/brand-image/{source}/{category}` — Brand Image
  - params: `source` (path, required, string); `category` (path, required, string)
- **GET** `/api/v1/news/feed` — Get Market Feed
  - params: `sector` (query, string); `sort` (query, string); `limit` (query, integer)
- **GET** `/api/v1/news/market` — Get Market News
  - params: `limit` (query, integer)
- **GET** `/api/v1/news/source-icon/{domain}` — Source Icon
  - params: `domain` (path, required, string)

### other

- **GET** `/api` — Api Info
- **GET** `/api/v1/agentic/routes` — Agentic Routes
- **GET** `/calendar/data` — Calendar Data Json
  - params: `year` (query); `month` (query); `exchange` (query); `status` (query); `filing_type` (query); `ticker` (query); `page` (query, integer); `page_size` (query, integer)

### pricing

- **GET** `/api/v1/pricing` — Agent pricing: subscription, pass and per-request USDC prices

### sectors

- **GET** `/api/v1/sectors` — List Sectors
- **GET** `/api/v1/sectors/trending` — Get Trending Themes
- **GET** `/api/v1/sectors/{sector}/stats` — Get Sector Stats
  - params: `sector` (path, required, string)

### stats

- **GET** `/api/v1/stats/top-companies` — Top companies by market cap (live, cached 10 min)
  - params: `limit` (query, integer)