# 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)* | Column | Type | Description | | -------------------------- | ------ | ---------------------------------------- | | `exchange` | String | Exchange name (e.g., "binance") | | `market_symbol` | String | Normalized symbol (e.g., "BTC-USDT") | | `base_asset` | String | Base asset (e.g., "BTC") | | `quote_asset` | String | Quote asset (e.g., "USDT") | | `exchange_specific_symbol` | String | Native exchange symbol (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)* | Column | Type | Description | | -------------------------- | -------------- | ---------------------------------------------- | | `exchange` | String | Exchange name | | `market_symbol` | String | Normalised symbol (e.g., "BTC-USDT-PERP") | | `underlying_asset` | String | Underlying asset (e.g., "BTC") | | `quote_asset` | String | Quote asset (e.g., "USDT") | | `settling_asset` | String | Settlement asset (e.g., "BTC") | | `denomination_asset` | String | Margin denomination (e.g., "USDT") | | `expiration` | DateTime64(9) | Contract expiry (null for perpetuals) | | `contract_size` | Decimal(38,18) | Size per contract (e.g., 0.001) | | `contract_type` | String | "INVERSE" or "LINEAR" | | `future_type` | String | "PERPETUAL" or "EXPIRING" | | `exchange_specific_symbol` | String | Native exchange symbol (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-2025-08-02-112400-C)* | Column | Type | Description | | -------------------------- | -------------- | ---------------------------------------------------- | | `exchange` | String | Exchange name | | `market_symbol` | String | Normalised symbol (e.g., "BTC-USDT-30000-C") | | `underlying_asset` | String | Underlying asset (e.g., "BTC") | | `quote_asset` | String | Quote asset (e.g., "USDT") | | `settling_asset` | String | Settlement asset (e.g., "BTC") | | `expiration` | DateTime64(9) | Option expiry timestamp | | `strike` | Decimal(38,18) | Strike price (e.g., 30000) | | `contract_size` | Decimal(38,18) | Size per contract (e.g., 0.1) | | `contract_type` | String | "INVERSE" or "LINEAR" | | `option_type` | String | "CALL" or "PUT" | | `exchange_specific_symbol` | String | Native exchange symbol (e.g., "BTC-30JUN23-30000-C") | **Use Case Example**\ Find all BTC call options expiring in Q3 2024: ```sql SELECT * FROM api.market_option WHERE underlying_asset = 'BTC' AND option_type = 'CALL' AND toYear(expiration) = 2024 and toQuarter(expiration) = 3 order by expiration, strike ``` Here is the doc of the handy toQuarter function : ## 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.\nFormat: ISO 8601 date-time (e.g., '2023-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: 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: ``` GET https://docs.koinju.io/data/market-list.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.