> 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)"}}}}}} ```