# Markets
Market information, statistics, and orderbook data
## List markets
> Returns markets with instrument details.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Markets","description":"Market information, statistics, and orderbook data\n"}],"servers":[{"url":"{BASE_URL}/v1","description":"GRID Trading API Base URL\n","variables":{"BASE_URL":{"default":"https://trading.api.thegrid.ai","description":"The base URL for the API.\n"}}}],"security":[{"signatureAuth":[]}],"components":{"securitySchemes":{"signatureAuth":{"type":"apiKey","in":"header","name":"x-thegrid-signature","description":"Ed25519 signature authentication. **All three headers are required** for every request:\n\n| Header | Description |\n|--------|-------------|\n| `x-thegrid-signature` | Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`\n| `x-thegrid-timestamp` | Unix timestamp in seconds (must be within 30 seconds of server time) |\n| `x-thegrid-fingerprint` | SHA256 hash of your public key (Base64-encoded, padding stripped) |\n\n[See full authentication docs](./overview-trading-api/authentication)\n"}},"schemas":{"MarketWithInstruments":{"type":"object","properties":{"market_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"market_type":{"type":"string","enum":["spot"]},"status":{"type":"string","description":"Market status. Known values include active, inactive, suspended; API may return other values.\n"},"associated_instruments":{"type":"array","description":"List of instrument IDs (was `allowed_instruments` in legacy API)","items":{"type":"string"}},"instruments":{"type":"array","description":"AI-commodity instruments only, in the order of `associated_instruments`.\nFor full details use GET /v1/instruments/{instrument_id}.\n","items":{"type":"object","required":["instrument_id","instrument_type","symbol"],"properties":{"instrument_id":{"type":"string"},"instrument_type":{"type":"string","description":"Legacy `commodity` normalized to `ai_commodity`","enum":["ai_commodity","currency","commodity"]},"symbol":{"type":"string"},"name":{"type":"string","nullable":true,"description":"May be null if not set on the instrument"},"description":{"type":"string","nullable":true,"description":"May be null if not set on the instrument"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CursorPaging":{"type":"object","description":"Cursor-based pagination\n","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"prev_cursor":{"type":"string","nullable":true}}}}},"paths":{"/markets":{"get":{"tags":["Markets"],"summary":"List markets","description":"Returns markets with instrument details.\n","operationId":"tradingListMarkets","responses":{"200":{"description":"List of markets\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketWithInstruments"}},"paging":{"$ref":"#/components/schemas/CursorPaging"}}}}}}}}}}}
```
## Get market ticker
> Get current ticker data including best bid/ask, last price, and 24h volume.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Markets","description":"Market information, statistics, and orderbook data\n"}],"servers":[{"url":"{BASE_URL}/v1","description":"GRID Trading API Base URL\n","variables":{"BASE_URL":{"default":"https://trading.api.thegrid.ai","description":"The base URL for the API.\n"}}}],"security":[{"signatureAuth":[]}],"components":{"securitySchemes":{"signatureAuth":{"type":"apiKey","in":"header","name":"x-thegrid-signature","description":"Ed25519 signature authentication. **All three headers are required** for every request:\n\n| Header | Description |\n|--------|-------------|\n| `x-thegrid-signature` | Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`\n| `x-thegrid-timestamp` | Unix timestamp in seconds (must be within 30 seconds of server time) |\n| `x-thegrid-fingerprint` | SHA256 hash of your public key (Base64-encoded, padding stripped) |\n\n[See full authentication docs](./overview-trading-api/authentication)\n"}},"schemas":{"Ticker":{"type":"object","description":"Market ticker data including last trade, best bid/ask prices, and 24-hour volume.\n","properties":{"last_price":{"type":"string","nullable":true,"description":"Last trade price (decimal string)\n"},"last_trade_quantity":{"type":"integer","nullable":true,"description":"Last trade quantity (was `last_trade_size` in legacy API)\n"},"last_trade_timestamp":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the most recent trade (ISO8601)\n"},"lowest_ask":{"type":"string","nullable":true,"description":"Best ask (decimal string)\n"},"highest_bid":{"type":"string","nullable":true,"description":"Best bid (decimal string)\n"},"volume_24h":{"type":"integer","nullable":true,"description":"24h volume\n"}}},"ErrorResponse":{"type":"object","properties":{"data":{"description":"Optional payload for non-error responses (typically null on errors)","nullable":true},"error":{"type":"string","nullable":true,"description":"Short, human-readable error summary"},"errors":{"type":"object","description":"Machine-readable error details","properties":{"detail":{"type":"string","description":"High-level error detail message"},"fields":{"type":"object","description":"Per-field validation errors when applicable"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (for rate limit errors)"}}},"meta":{"type":"object","description":"Optional metadata about the error (e.g., request_id, timestamp)"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Invalid or missing authentication headers\n","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not found - The requested resource does not exist\n","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/markets/{market_id}/ticker":{"get":{"tags":["Markets"],"summary":"Get market ticker","description":"Get current ticker data including best bid/ask, last price, and 24h volume.\n","operationId":"tradingGetTicker","parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier for the market (e.g., \"market_b310e860-97cd-45eb-bdc3-5be0b79295d0\")\n"}],"responses":{"200":{"description":"Ticker data including last trade, bid/ask, and 24h volume\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Ticker"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Get order book
> Get the order book (depth of market) for a specific market.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Markets","description":"Market information, statistics, and orderbook data\n"}],"servers":[{"url":"{BASE_URL}/v1","description":"GRID Trading API Base URL\n","variables":{"BASE_URL":{"default":"https://trading.api.thegrid.ai","description":"The base URL for the API.\n"}}}],"security":[{"signatureAuth":[]}],"components":{"securitySchemes":{"signatureAuth":{"type":"apiKey","in":"header","name":"x-thegrid-signature","description":"Ed25519 signature authentication. **All three headers are required** for every request:\n\n| Header | Description |\n|--------|-------------|\n| `x-thegrid-signature` | Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`\n| `x-thegrid-timestamp` | Unix timestamp in seconds (must be within 30 seconds of server time) |\n| `x-thegrid-fingerprint` | SHA256 hash of your public key (Base64-encoded, padding stripped) |\n\n[See full authentication docs](./overview-trading-api/authentication)\n"}},"schemas":{"OrderbookResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"buy":{"type":"array","items":{"$ref":"#/components/schemas/OrderbookLevel"}},"sell":{"type":"array","items":{"$ref":"#/components/schemas/OrderbookLevel"}},"highest_bid":{"type":"string","nullable":true},"lowest_ask":{"type":"string","nullable":true},"highest_bid_price":{"type":"string","nullable":true},"lowest_ask_price":{"type":"string","nullable":true},"updated_at":{"type":"string","format":"date-time"}}}}},"OrderbookLevel":{"type":"object","description":"Single price level in the order book (buy or sell side).\n","properties":{"price":{"type":"string"},"quantity":{"type":"integer","description":"Size at this level (was `size` in legacy API)"},"total":{"type":"integer"},"order_count":{"type":"integer"}}}}},"paths":{"/markets/{market_id}/orderbook":{"get":{"tags":["Markets"],"summary":"Get order book","description":"Get the order book (depth of market) for a specific market.\n","operationId":"tradingGetOrderbook","parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier for the market (e.g., \"market_b310e860-97cd-45eb-bdc3-5be0b79295d0\")\n"},{"name":"depth","in":"query","schema":{"type":"integer","default":10,"minimum":1,"maximum":100},"description":"Maximum number of price levels to return per side (bids and asks). Default: 10. Use lower values for quick price checks, higher values for detailed market depth analysis.\n"}],"responses":{"200":{"description":"Order book data\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderbookResponse"}}}}}}}}}
```
## Get market trades
> Returns public trades for a specific market (not scoped to authenticated user).
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Markets","description":"Market information, statistics, and orderbook data\n"}],"servers":[{"url":"{BASE_URL}/v1","description":"GRID Trading API Base URL\n","variables":{"BASE_URL":{"default":"https://trading.api.thegrid.ai","description":"The base URL for the API.\n"}}}],"security":[{"signatureAuth":[]}],"components":{"securitySchemes":{"signatureAuth":{"type":"apiKey","in":"header","name":"x-thegrid-signature","description":"Ed25519 signature authentication. **All three headers are required** for every request:\n\n| Header | Description |\n|--------|-------------|\n| `x-thegrid-signature` | Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`\n| `x-thegrid-timestamp` | Unix timestamp in seconds (must be within 30 seconds of server time) |\n| `x-thegrid-fingerprint` | SHA256 hash of your public key (Base64-encoded, padding stripped) |\n\n[See full authentication docs](./overview-trading-api/authentication)\n"}},"parameters":{"next":{"name":"next","in":"query","schema":{"type":"string"},"description":"Cursor for forward pagination. Pass the `next_cursor` value from a previous response to fetch the next page. Mutually exclusive with `prev`.\n"},"prev":{"name":"prev","in":"query","schema":{"type":"string"},"description":"Cursor for backward pagination. Pass the `prev_cursor` value from a previous response to fetch the previous page. Mutually exclusive with `next`.\n"}},"schemas":{"PublicTrade":{"type":"object","description":"Public trade for a market (not scoped to the authenticated user; no order_id or trading_account_id).\n","properties":{"trade_id":{"type":"string","description":"Public trade ID"},"market_id":{"type":"string"},"market_name":{"type":"string","nullable":true},"instrument_id":{"type":"string"},"instrument_symbol":{"type":"string","nullable":true},"instrument_name":{"type":"string","nullable":true},"price":{"type":"string"},"quantity":{"type":"integer"},"side":{"type":"string","enum":["buy","sell"]},"total_value":{"type":"string"},"status":{"type":"string"},"execution_timestamp":{"type":"string","format":"date-time","nullable":true},"settlement_timestamp":{"type":"string","format":"date-time","nullable":true}}},"CursorPaging":{"type":"object","description":"Cursor-based pagination\n","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"prev_cursor":{"type":"string","nullable":true}}}}},"paths":{"/markets/{market_id}/trades":{"get":{"tags":["Markets"],"summary":"Get market trades","description":"Returns public trades for a specific market (not scoped to authenticated user).\n","operationId":"tradingGetMarketTrades","parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier for the market (e.g., \"market_b310e860-97cd-45eb-bdc3-5be0b79295d0\")\n"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Filter by trade status"},{"name":"side","in":"query","schema":{"type":"string","enum":["buy","sell"]},"description":"Filter by taker side"},{"name":"min_quantity","in":"query","schema":{"type":"integer"},"description":"Filter trades with quantity >= this value"},{"name":"max_quantity","in":"query","schema":{"type":"integer"},"description":"Filter trades with quantity <= this value"},{"name":"min_price","in":"query","schema":{"type":"string"},"description":"Filter trades with price >= this value"},{"name":"max_price","in":"query","schema":{"type":"string"},"description":"Filter trades with price <= this value"},{"name":"start_date","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter trades executed at or after this time (ISO8601 or Unix timestamp)"},{"name":"end_date","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter trades executed at or before this time (ISO8601 or Unix timestamp)"},{"name":"order_by","in":"query","schema":{"type":"string","enum":["execution_timestamp","quantity","price"]},"description":"Field to sort by"},{"name":"order_direction","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Sort direction"},{"$ref":"#/components/parameters/next"},{"$ref":"#/components/parameters/prev"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100},"description":"Number of trades to return (max: 100)\n"}],"responses":{"200":{"description":"Recent trades\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicTrade"}},"paging":{"$ref":"#/components/schemas/CursorPaging"}}}}}}}}}}}
```
## Get market details
> Returns market details with instruments.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Markets","description":"Market information, statistics, and orderbook data\n"}],"servers":[{"url":"{BASE_URL}/v1","description":"GRID Trading API Base URL\n","variables":{"BASE_URL":{"default":"https://trading.api.thegrid.ai","description":"The base URL for the API.\n"}}}],"security":[{"signatureAuth":[]}],"components":{"securitySchemes":{"signatureAuth":{"type":"apiKey","in":"header","name":"x-thegrid-signature","description":"Ed25519 signature authentication. **All three headers are required** for every request:\n\n| Header | Description |\n|--------|-------------|\n| `x-thegrid-signature` | Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`\n| `x-thegrid-timestamp` | Unix timestamp in seconds (must be within 30 seconds of server time) |\n| `x-thegrid-fingerprint` | SHA256 hash of your public key (Base64-encoded, padding stripped) |\n\n[See full authentication docs](./overview-trading-api/authentication)\n"}},"schemas":{"MarketWithInstruments":{"type":"object","properties":{"market_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"market_type":{"type":"string","enum":["spot"]},"status":{"type":"string","description":"Market status. Known values include active, inactive, suspended; API may return other values.\n"},"associated_instruments":{"type":"array","description":"List of instrument IDs (was `allowed_instruments` in legacy API)","items":{"type":"string"}},"instruments":{"type":"array","description":"AI-commodity instruments only, in the order of `associated_instruments`.\nFor full details use GET /v1/instruments/{instrument_id}.\n","items":{"type":"object","required":["instrument_id","instrument_type","symbol"],"properties":{"instrument_id":{"type":"string"},"instrument_type":{"type":"string","description":"Legacy `commodity` normalized to `ai_commodity`","enum":["ai_commodity","currency","commodity"]},"symbol":{"type":"string"},"name":{"type":"string","nullable":true,"description":"May be null if not set on the instrument"},"description":{"type":"string","nullable":true,"description":"May be null if not set on the instrument"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"data":{"description":"Optional payload for non-error responses (typically null on errors)","nullable":true},"error":{"type":"string","nullable":true,"description":"Short, human-readable error summary"},"errors":{"type":"object","description":"Machine-readable error details","properties":{"detail":{"type":"string","description":"High-level error detail message"},"fields":{"type":"object","description":"Per-field validation errors when applicable"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (for rate limit errors)"}}},"meta":{"type":"object","description":"Optional metadata about the error (e.g., request_id, timestamp)"}}}},"responses":{"NotFound":{"description":"Not found - The requested resource does not exist\n","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/markets/{market_id}":{"get":{"tags":["Markets"],"summary":"Get market details","description":"Returns market details with instruments.\n","operationId":"tradingGetMarket","parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier for the market (e.g., \"market_b310e860-97cd-45eb-bdc3-5be0b79295d0\")\n"}],"responses":{"200":{"description":"Market details\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MarketWithInstruments"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Get price history (OHLCV)
> Returns OHLCV (Open, High, Low, Close, Volume) candle data for charting. \
> Use this endpoint to build price charts and analyze historical market data.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Markets","description":"Market information, statistics, and orderbook data\n"}],"servers":[{"url":"{BASE_URL}/v1","description":"GRID Trading API Base URL\n","variables":{"BASE_URL":{"default":"https://trading.api.thegrid.ai","description":"The base URL for the API.\n"}}}],"security":[{"signatureAuth":[]}],"components":{"securitySchemes":{"signatureAuth":{"type":"apiKey","in":"header","name":"x-thegrid-signature","description":"Ed25519 signature authentication. **All three headers are required** for every request:\n\n| Header | Description |\n|--------|-------------|\n| `x-thegrid-signature` | Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`\n| `x-thegrid-timestamp` | Unix timestamp in seconds (must be within 30 seconds of server time) |\n| `x-thegrid-fingerprint` | SHA256 hash of your public key (Base64-encoded, padding stripped) |\n\n[See full authentication docs](./overview-trading-api/authentication)\n"}},"parameters":{"next":{"name":"next","in":"query","schema":{"type":"string"},"description":"Cursor for forward pagination. Pass the `next_cursor` value from a previous response to fetch the next page. Mutually exclusive with `prev`.\n"},"prev":{"name":"prev","in":"query","schema":{"type":"string"},"description":"Cursor for backward pagination. Pass the `prev_cursor` value from a previous response to fetch the previous page. Mutually exclusive with `next`.\n"},"limit":{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100},"description":"Number of items to return per page (max: 100)\n"}},"schemas":{"PriceHistoryResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceHistory"}},"paging":{"$ref":"#/components/schemas/CursorPaging"}}},"PriceHistory":{"type":"object","description":"OHLCV candle data for a specific time period\n","properties":{"time":{"type":"string","format":"date-time","description":"Period start time (ISO8601)\n"},"market_id":{"type":"string","description":"Market identifier\n"},"resolution":{"type":"string","enum":["1m","5m","15m","30m","1h","4h","1d","1w","1M"],"description":"Candle resolution/timeframe\n"},"open":{"type":"string","description":"Opening price for the period (decimal string)\n"},"high":{"type":"string","description":"Highest price during the period (decimal string)\n"},"low":{"type":"string","description":"Lowest price during the period (decimal string)\n"},"close":{"type":"string","description":"Closing price for the period (decimal string)\n"},"volume":{"type":"integer","description":"Total trading volume during the period\n"},"trade_count":{"type":"integer","description":"Number of trades during the period\n"}}},"CursorPaging":{"type":"object","description":"Cursor-based pagination\n","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"prev_cursor":{"type":"string","nullable":true}}},"ErrorResponse":{"type":"object","properties":{"data":{"description":"Optional payload for non-error responses (typically null on errors)","nullable":true},"error":{"type":"string","nullable":true,"description":"Short, human-readable error summary"},"errors":{"type":"object","description":"Machine-readable error details","properties":{"detail":{"type":"string","description":"High-level error detail message"},"fields":{"type":"object","description":"Per-field validation errors when applicable"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (for rate limit errors)"}}},"meta":{"type":"object","description":"Optional metadata about the error (e.g., request_id, timestamp)"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Invalid or missing authentication headers\n","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ValidationError":{"description":"Validation error - Request parameters failed validation\n","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/price-histories":{"get":{"tags":["Markets"],"summary":"Get price history (OHLCV)","description":"Returns OHLCV (Open, High, Low, Close, Volume) candle data for charting. \nUse this endpoint to build price charts and analyze historical market data.\n","operationId":"tradingGetPriceHistories","parameters":[{"name":"market_id","in":"query","schema":{"type":"string"},"description":"Filter by market ID"},{"name":"resolution","in":"query","schema":{"type":"string","enum":["1m","5m","15m","30m","1h","4h","1d","1w","1M"]},"description":"Candle resolution/timeframe. Determines the time period each candle represents.\n"},{"name":"from","in":"query","schema":{"type":"integer"},"description":"Start of time range (Unix timestamp in seconds)"},{"name":"to","in":"query","schema":{"type":"integer"},"description":"End of time range (Unix timestamp in seconds)"},{"name":"order_by","in":"query","schema":{"type":"string","enum":["period_start"]},"description":"Field to sort by"},{"name":"order_direction","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Sort direction"},{"$ref":"#/components/parameters/next"},{"$ref":"#/components/parameters/prev"},{"$ref":"#/components/parameters/limit"}],"responses":{"200":{"description":"OHLCV candle data\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceHistoryResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}}}}
```
---
# 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://thegrid.ai/docs/beta-trading-api/markets.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.