# Finance on Onekey

> 5 endpoints for Finance (5 stable, 0 beta), 1 to 2 credits each. Category: Finance & markets. One key, one JSON shape.

Base URL: https://api.onekey.dev
Auth: header `x-api-key: <key>`. Call shape: `GET /v1/{platform}/{endpoint}?{params}`.
Every response is `{success, data, metadata, error}`; check `success` first. Cost is in `metadata.credits_charged`. Free when served from cache (0.2 credit for a cached response over 100 KB). Failed and not-found calls are refunded.
Status: stable = verified against the live source; beta = not yet verified, fields may be missing.

Page: https://onekey.dev/platforms/finance
Reference (Markdown): https://onekey.dev/docs/api/finance.md
All docs: https://onekey.dev/llms.txt

## Canonical fields returned

Unified-schema fields (same names on every platform), with how many of the 5 mapped Finance endpoints return each:

- `market.symbol` (string): 4
- `market.price` (number): 2
- `market.volume` (number): 2
- `author.displayName` (string): 1
- `content.createdAt` (ISO 8601 date): 1
- `content.id` (string): 1
- `content.title` (string): 1
- `content.url` (URL): 1
- `entity.category` (string): 1
- `entity.date` (ISO 8601 date): 1
- `entity.name` (string): 1
- `entity.tags` (list of strings): 1
- `market.ask` (number): 1
- `market.bid` (number): 1
- `market.currency` (string): 1
- `market.exchange` (string): 1
- `market.high` (number): 1
- `market.low` (number): 1
- `market.marketCap` (number): 1
- `market.open` (number): 1
- `market.openInterest` (number): 1
- `media.thumbnailUrl` (URL): 1
- plus 23 platform-specific fields under `ext.`

## Endpoints

### finance.markets

Market movers for the day (biggest gainers, biggest losers or most active stocks).
- Price: 1 credit per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/finance/markets?screen=day_gainers` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `screen` (string, optional, default day_gainers): Which list: day_gainers, day_losers or most_actives
  - `n` (string, optional, default 25): Rows (1-50)
- Fields returned: `market.symbol`, `entity.name`, `entity.category`, `market.exchange`, `market.currency`, `market.price`, `market.volume`, `market.marketCap`, `entity.date`, `ext.change`, `ext.changePercent`
- Reference: https://onekey.dev/docs/api/finance/markets.md

### finance.news

Recent news headlines for a ticker, company or market topic.
- Price: 1 credit per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/finance/news?q=AAPL` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Ticker or company name, e.g. AAPL or "federal reserve"
  - `n` (string, optional, default 10): Headlines to return (1-30)
- Fields returned: `content.id`, `content.title`, `content.url`, `content.createdAt`, `author.displayName`, `media.thumbnailUrl`, `entity.tags`
- Reference: https://onekey.dev/docs/api/finance/news.md

### finance.options

Delayed options chain for a ticker, every listed contract with quotes and Greeks.
- Price: 2 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/finance/options?symbol=AAPL` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `symbol` (string, required): Underlying ticker, e.g. AAPL, or an index with a leading underscore (_SPX)
- Fields returned: `market.symbol`, `market.bid`, `market.ask`, `market.price`, `market.open`, `market.high`, `market.low`, `market.volume`, `market.openInterest`, `ext.lastTradeTime`, `ext.impliedVolatility`, `ext.delta`, `ext.gamma`, `ext.theta`, `ext.vega`, `ext.rho`, `ext.theoreticalPrice`
- Reference: https://onekey.dev/docs/api/finance/options.md

### finance.statements

Annual income statement, balance sheet and cash flow lines for a listed company (one row per metric).
- Price: 2 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/finance/statements?symbol=AAPL` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `symbol` (string, required): Company ticker, e.g. AAPL
- Fields returned: `market.symbol`, `ext.metric`, `ext.totalRevenue`, `ext.grossProfit`, `ext.operatingIncome`, `ext.netIncome`, `ext.basicEps`, `ext.totalAssets`, `ext.totalLiabilities`, `ext.stockholdersEquity`, `ext.operatingCashFlow`, `ext.capitalExpenditure`, `ext.freeCashFlow`, `ext.cashAndEquivalents`
- Reference: https://onekey.dev/docs/api/finance/statements.md

### finance.statements_quarterly

Quarterly income statement, balance sheet and cash flow lines for a listed company, last five quarters (one row per metric).
- Price: 2 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/finance/statements_quarterly?symbol=AAPL` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `symbol` (string, required): Company ticker, e.g. AAPL
- Fields returned: `market.symbol`, `ext.metric`, `ext.totalRevenue`, `ext.grossProfit`, `ext.operatingIncome`, `ext.netIncome`, `ext.basicEps`, `ext.totalAssets`, `ext.totalLiabilities`, `ext.stockholdersEquity`, `ext.operatingCashFlow`, `ext.capitalExpenditure`, `ext.freeCashFlow`, `ext.cashAndEquivalents`
- Reference: https://onekey.dev/docs/api/finance/statements_quarterly.md

## Sample request

```bash
curl "https://api.onekey.dev/v1/finance/markets?screen=day_gainers" \
  -H "x-api-key: YOUR_API_KEY"
```