> For the complete documentation index, see [llms.txt](https://docs.koinju.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.koinju.io/data/market-list.md).
# Market list
## SQL API
Our ClickHouse SQL interface provides direct access to normalized market metadata through three optimized views: `market_spot`, `market_future`, and `market_option`. These tables enable sophisticated filtering and joins impossible via REST, empowering complex analytics workflows.
***
### `api.market_spot`
*Spot markets (e.g., BTC-USD, BTC-USDT)*
| Column | Type | Description |
| -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `exchange` | String | Venue id — mostly clean spot names (e.g. `binance`, `coinbase`); run `SELECT DISTINCT exchange` for the full set |
| `market_symbol` | String | Universal symbol, format `BASE-QUOTE` (e.g. `BTC-USDT` on Binance, `BTC-USD` on Coinbase) |
| `base_asset` | String | Base asset, universal symbol (e.g. `BTC`) |
| `quote_asset` | String | Quote asset, universal symbol (e.g. `USDT`, `USD`) |
| `exchange_specific_symbol` | String | Raw exchange websocket ticker (e.g. `BTCUSDT`) |
**Use Case Example**\
Find all spot markets with USDT quote pairs on Binance or Kraken:
```sql
SELECT exchange, market_symbol, base_asset, quote_asset
FROM api.market_spot
WHERE quote_asset = 'USDT'
AND exchange IN ('binance', 'kraken')
```
List all exchanges:
```sql
SELECT distinct exchange FROM api.market_spot
```
***
### `api.market_future`
*Futures contracts (e.g., BTC-USD-PERP-INV inverse, BTC-USDT-PERP linear)*
| Column | Type | Description |
| -------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exchange` | String | Clean venue id, e.g. `binance`, `deribit`, `okx` (no product suffix on this view) |
| `market_symbol` | String | Universal symbol: `BASE-QUOTE-PERP` (linear perp), `BASE-QUOTE-PERP-INV` (inverse perp), `BASE-QUOTE-YYYY-MM-DD[-INV]` (dated). E.g. `BTC-USDT-PERP` |
| `underlying_asset` | String | Underlying asset (e.g. `BTC`) |
| `quote_asset` | String | Quote asset (e.g. `USDT`, `USD`) |
| `settling_asset` | String | Asset PnL settles in; equals the underlying ⟹ INVERSE contract |
| `denomination_asset` | String | Margin / collateral asset |
| `expiration` | DateTime64(9) | Contract expiry (null for perpetuals) |
| `contract_size` | Decimal(38,18) | Size per contract (e.g. 0.001) |
| `contract_type` | String | `LINEAR` (quote-settled) or `INVERSE` (coin-settled) |
| `future_type` | String | `PERPETUAL` or `EXPIRING` |
| `exchange_specific_symbol` | String | Raw exchange websocket ticker (e.g. `BTCUSDT_PERP`) |
**Use Case Example**\
List perpetual BTC futures with linear pricing:
```sql
SELECT
exchange,
market_symbol,
underlying_asset,
contract_size
FROM api.market_future
WHERE underlying_asset = 'BTC'
AND future_type = 'PERPETUAL'
AND contract_type = 'LINEAR'
```
***
### `api.market_option`
*Options contracts (e.g., BTC-USDT-2026-05-09-75000-C)*
| Column | Type | Description |
| -------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `exchange` | String | Clean venue id, e.g. `deribit`, `okx`, `bybit` |
| `market_symbol` | String | Universal symbol, format `BASE-QUOTE-YYYY-MM-DD-STRIKE-{C\|P}` (e.g. `BTC-USDT-2026-05-09-75000-C`, `BTC-BTC-...` on Deribit) |
| `underlying_asset` | String | Underlying asset (e.g. `BTC`) |
| `quote_asset` | String | Quote asset (e.g. `USDT`, `USDC`, `USD`, `BTC`) |
| `settling_asset` | String | Asset PnL settles in |
| `expiration` | DateTime64(9) | Option expiry timestamp |
| `strike` | Decimal(38,18) | Strike price (e.g. 75000) |
| `contract_size` | Decimal(38,18) | Size per contract (e.g. 0.1) |
| `contract_type` | String | `LINEAR` or `INVERSE` |
| `option_type` | String | `CALL` or `PUT` |
| `exchange_specific_symbol` | String | Raw exchange ticker (e.g. `BTC-30JUN23-30000-C`) |
**Use Case Example**\
Find BTC call options expiring in the current quarter:
```sql
SELECT *
FROM api.market_option
WHERE underlying_asset = 'BTC'
AND option_type = 'CALL'
AND toYear(expiration) = toYear(now())
AND toQuarter(expiration) = toQuarter(now())
ORDER BY expiration, strike
LIMIT 100
```
`toQuarter` and `toYear` are ClickHouse date-time functions — see the [`toQuarter`](https://clickhouse.com/docs/sql-reference/functions/date-time-functions#toquarter) and [`toYear`](https://clickhouse.com/docs/sql-reference/functions/date-time-functions#toyear) reference.
## REST API
## Get Spot Markets
> This endpoint allows you to obtain the full list of spot markets
```json
{"openapi":"3.1.1","info":{"title":"Koinju Market Data API","version":"1.0.0"},"servers":[{"url":"https://api.koinju.io","description":"Koinju API Server"}],"security":[],"paths":{"/market/spot":{"get":{"summary":"Get Spot Markets","description":"This endpoint allows you to obtain the full list of spot markets","tags":["market_data"],"responses":{"200":{"description":"All spot markets","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MarketSpot"}}}}}}}}},"components":{"schemas":{"MarketSpot":{"type":"object","properties":{"exchange":{"type":"string","description":"The name of the exchange"},"market_symbol":{"type":"string","description":"Universal name of market"},"base_asset":{"type":"string","description":"Universal name of the base asset"},"quote_asset":{"type":"string","description":"Universal name of the quote asset"},"exchange_specific_symbol":{"type":"string","description":"Name of the market on the exchange (as referenced by the exchange API)"}}}}}}
```
## Get Future Markets
> Returns expirable future and perpetual swaps.
```json
{"openapi":"3.1.1","info":{"title":"Koinju Market Data API","version":"1.0.0"},"servers":[{"url":"https://api.koinju.io","description":"Koinju API Server"}],"security":[],"paths":{"/market/future":{"get":{"summary":"Get Future Markets","description":"Returns expirable future and perpetual swaps.","tags":["market_data"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MarketFuture"}}}}}}}}},"components":{"schemas":{"MarketFuture":{"type":"object","properties":{"exchange":{"type":"string","description":"The name of the exchange"},"market_symbol":{"type":"string","description":"Universal name of market"},"underlying_asset":{"type":"string","description":"Universal name of the underlying asset"},"quote_asset":{"type":"string","description":"Universal name of the quote asset"},"settling_asset":{"type":"string","description":"Universal name of the asset the future is settled in"},"denomination_asset":{"type":"string","description":"Universal name of the asset the future is denominated in"},"expiration":{"type":"string","format":"date-time","description":"UTC time of the contract expiration. Null for perpetual contracts except binance.\nNot-null for perpetual contracts that were delivered on delisting or not expired binance contracts.\n"},"contract_size":{"type":"number","format":"decimal","description":"Contract size in denomination_asset"},"contract_type":{"type":"string","enum":["LINEAR","INVERSE"],"description":"Type of contract (LINEAR or INVERSE)"},"future_type":{"type":"string","enum":["PERPETUAL","EXPIRING"],"description":"Type of future (PERPETUAL or EXPIRING)"}}}}}}
```
## GET /market/option/active
> Get active Option Markets
```json
{"openapi":"3.1.1","info":{"title":"Koinju Market Data API","version":"1.0.0"},"servers":[{"url":"https://api.koinju.io","description":"Koinju API Server"}],"security":[],"paths":{"/market/option/active":{"get":{"summary":"Get active Option Markets","tags":["market_data"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MarketOption"}}}}}}}}},"components":{"schemas":{"MarketOption":{"type":"object","properties":{"exchange":{"type":"string","description":"The name of the exchange"},"market_symbol":{"type":"string","description":"Universal name of market"},"expiration":{"type":"string","format":"date-time","description":"UTC time of the option expiration"},"underlying_asset":{"type":"string","description":"Universal name of the underlying asset"},"quote_asset":{"type":"string","description":"Universal name of the quote asset"},"settling_asset":{"type":"string","description":"Universal name of the asset the option is settled in"},"denomination_asset":{"type":"string","description":"Universal name of the asset the option is denominated in"},"contract_size":{"type":"number","format":"decimal","description":"Contract size in denomination_asset"},"contract_type":{"type":"string","enum":["LINEAR","INVERSE"],"description":"Type of contract (LINEAR or INVERSE)"},"option_type":{"type":"string","enum":["CALL","PUT"],"description":"Type of option (CALL or PUT)"},"exchange_symbol":{"type":"string","description":"Name of the market on the exchange (as referenced by the exchange API)"}}}}}}
```
## Get all Option Markets
> This endpoint returns all option markets, including both active and expired options.\
> It is useful for retrieving a comprehensive list of all options available across exchanges.\
> \
> This endpoint is limited to 10000 instruments that expired before the \`expired\_before\` parameter in descending order of expiration.
```json
{"openapi":"3.1.1","info":{"title":"Koinju Market Data API","version":"1.0.0"},"servers":[{"url":"https://api.koinju.io","description":"Koinju API Server"}],"security":[],"paths":{"/market/option/all":{"get":{"summary":"Get all Option Markets","description":"This endpoint returns all option markets, including both active and expired options.\nIt is useful for retrieving a comprehensive list of all options available across exchanges.\n\nThis endpoint is limited to 10000 instruments that expired before the `expired_before` parameter in descending order of expiration.\n","tags":["market_data"],"parameters":[{"name":"exchange","in":"query","required":true,"description":"Filter by exchange name.\nExample: 'deribit', 'delta'\n","schema":{"type":"string","enum":["deribit","okx","delta"]}},{"name":"expired_before","in":"query","required":true,"description":"Filter options that expired before a specific date. Accepts a plain\ndate (`2024-12-31`, treated as midnight UTC) or a full ISO 8601\ntimestamp (`2024-12-31T23:59:59Z`).\n","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MarketOption"}}}}}}}}},"components":{"schemas":{"MarketOption":{"type":"object","properties":{"exchange":{"type":"string","description":"The name of the exchange"},"market_symbol":{"type":"string","description":"Universal name of market"},"expiration":{"type":"string","format":"date-time","description":"UTC time of the option expiration"},"underlying_asset":{"type":"string","description":"Universal name of the underlying asset"},"quote_asset":{"type":"string","description":"Universal name of the quote asset"},"settling_asset":{"type":"string","description":"Universal name of the asset the option is settled in"},"denomination_asset":{"type":"string","description":"Universal name of the asset the option is denominated in"},"contract_size":{"type":"number","format":"decimal","description":"Contract size in denomination_asset"},"contract_type":{"type":"string","enum":["LINEAR","INVERSE"],"description":"Type of contract (LINEAR or INVERSE)"},"option_type":{"type":"string","enum":["CALL","PUT"],"description":"Type of option (CALL or PUT)"},"exchange_symbol":{"type":"string","description":"Name of the market on the exchange (as referenced by the exchange API)"}}}}}}
```
## The MarketSpot object
```json
{"openapi":"3.1.1","info":{"title":"Koinju Market Data API","version":"1.0.0"},"components":{"schemas":{"MarketSpot":{"type":"object","properties":{"exchange":{"type":"string","description":"The name of the exchange"},"market_symbol":{"type":"string","description":"Universal name of market"},"base_asset":{"type":"string","description":"Universal name of the base asset"},"quote_asset":{"type":"string","description":"Universal name of the quote asset"},"exchange_specific_symbol":{"type":"string","description":"Name of the market on the exchange (as referenced by the exchange API)"}}}}}}
```
## The MarketFuture object
```json
{"openapi":"3.1.1","info":{"title":"Koinju Market Data API","version":"1.0.0"},"components":{"schemas":{"MarketFuture":{"type":"object","properties":{"exchange":{"type":"string","description":"The name of the exchange"},"market_symbol":{"type":"string","description":"Universal name of market"},"underlying_asset":{"type":"string","description":"Universal name of the underlying asset"},"quote_asset":{"type":"string","description":"Universal name of the quote asset"},"settling_asset":{"type":"string","description":"Universal name of the asset the future is settled in"},"denomination_asset":{"type":"string","description":"Universal name of the asset the future is denominated in"},"expiration":{"type":"string","format":"date-time","description":"UTC time of the contract expiration. Null for perpetual contracts except binance.\nNot-null for perpetual contracts that were delivered on delisting or not expired binance contracts.\n"},"contract_size":{"type":"number","format":"decimal","description":"Contract size in denomination_asset"},"contract_type":{"type":"string","enum":["LINEAR","INVERSE"],"description":"Type of contract (LINEAR or INVERSE)"},"future_type":{"type":"string","enum":["PERPETUAL","EXPIRING"],"description":"Type of future (PERPETUAL or EXPIRING)"}}}}}}
```
## The MarketOption object
```json
{"openapi":"3.1.1","info":{"title":"Koinju Market Data API","version":"1.0.0"},"components":{"schemas":{"MarketOption":{"type":"object","properties":{"exchange":{"type":"string","description":"The name of the exchange"},"market_symbol":{"type":"string","description":"Universal name of market"},"expiration":{"type":"string","format":"date-time","description":"UTC time of the option expiration"},"underlying_asset":{"type":"string","description":"Universal name of the underlying asset"},"quote_asset":{"type":"string","description":"Universal name of the quote asset"},"settling_asset":{"type":"string","description":"Universal name of the asset the option is settled in"},"denomination_asset":{"type":"string","description":"Universal name of the asset the option is denominated in"},"contract_size":{"type":"number","format":"decimal","description":"Contract size in denomination_asset"},"contract_type":{"type":"string","enum":["LINEAR","INVERSE"],"description":"Type of contract (LINEAR or INVERSE)"},"option_type":{"type":"string","enum":["CALL","PUT"],"description":"Type of option (CALL or PUT)"},"exchange_symbol":{"type":"string","description":"Name of the market on the exchange (as referenced by the exchange API)"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.koinju.io/data/market-list.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.