# Instruments
Trading instruments including AI commodities with specifications
## List instruments
> Lists all available instruments with optional filtering and sorting.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Instruments","description":"Trading instruments including AI commodities with specifications\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":{"InstrumentListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InstrumentSummary"}},"paging":{"$ref":"#/components/schemas/CursorPaging"}}},"InstrumentSummary":{"type":"object","properties":{"instrument_id":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"instrument_type":{"type":"string","description":"Category of instrument (was `type` in legacy API). Legacy `commodity` normalized to `ai_commodity`.\n- `ai_commodity`: Tradeable AI inference capacity (e.g., tokens for LLM usage)\n- `currency`: Fiat currency used for settlement (e.g., USD)\n","enum":["ai_commodity","currency","commodity"]},"status":{"type":"string","enum":["draft","active","inactive","suspended","deleted"]},"basic_info":{"type":"object","nullable":true,"properties":{"service_type":{"type":"string"},"model_category":{"type":"string","description":"Model category classification","nullable":true},"currency_code":{"type":"string"},"precision":{"type":"integer"}}},"trading_params":{"type":"object","nullable":true,"properties":{"min_quantity":{"type":"integer"},"max_quantity":{"type":"integer"},"quantity_increment":{"type":"integer"},"fee":{"type":"string","description":"Fee rate (decimal string)"}}},"ai_specs":{"type":"object","nullable":true,"properties":{"context_window":{"type":"string","description":"Maximum context window size in tokens\n"},"token_throughput":{"type":"string","description":"Minimum token throughput rate in tokens per second\n"},"tokens_per_unit":{"type":"integer","description":"Number of tokens per tradeable unit\n"},"unit_definition":{"type":"string"},"qualifying_models":{"type":"array","items":{"type":"string"},"description":"List of AI models that qualify for this instrument\n"},"max_output_length":{"type":"integer","description":"Maximum output length in tokens"},"min_performance_benchmark":{"type":"number","description":"Minimum performance benchmark score"},"min_time_to_first_token_ms":{"type":"integer","description":"Maximum time to first token in milliseconds"},"model_id":{"type":"string","description":"Model identifier","nullable":true},"model_version":{"type":"string","description":"Model version","nullable":true},"usage":{"type":"string","description":"Usage type or category"}}}}},"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":{"/instruments":{"get":{"tags":["Instruments"],"summary":"List instruments","description":"Lists all available instruments with optional filtering and sorting.\n","operationId":"listInstruments","parameters":[{"$ref":"#/components/parameters/next"},{"$ref":"#/components/parameters/prev"},{"$ref":"#/components/parameters/limit"},{"name":"order_by","in":"query","schema":{"type":"string","enum":["symbol","created_at","updated_at"]},"description":"Field to sort by\n"},{"name":"order_direction","in":"query","schema":{"type":"string","enum":["asc","desc"]},"description":"Sort direction\n"},{"name":"symbol","in":"query","schema":{"type":"string"},"description":"Filter by exact symbol match (e.g., \"text-prime\")\n"},{"name":"instrument_type","in":"query","schema":{"type":"string","enum":["ai_commodity","currency","commodity"]},"description":"Filter by instrument type\n"},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","active","inactive","suspended","deleted"]},"description":"Filter by status\n"}],"responses":{"200":{"description":"List of instruments\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstrumentListResponse"}}}}}}}}}
```
## Get instrument details
> Gets a specific instrument by its ID. Returns full instrument details including\
> trading parameters and AI specifications.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Instruments","description":"Trading instruments including AI commodities with specifications\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":{"InstrumentDetailResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InstrumentDetail"}}},"InstrumentDetail":{"type":"object","properties":{"instrument_id":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"instrument_type":{"type":"string","description":"Legacy `commodity` normalized to `ai_commodity`","enum":["ai_commodity","currency","commodity"]},"status":{"type":"string","enum":["draft","active","inactive","suspended","deleted"]},"ai_specs":{"type":"object","nullable":true,"properties":{"context_window":{"type":"string","description":"Maximum context window size in tokens\n"},"token_throughput":{"type":"string","description":"Minimum token throughput rate in tokens per second\n"},"tokens_per_unit":{"type":"integer","description":"Number of tokens per tradeable unit\n"},"unit_definition":{"type":"string"},"qualifying_models":{"type":"array","items":{"type":"string"},"description":"List of AI models that qualify for this instrument\n"},"max_output_length":{"type":"integer","description":"Maximum output length in tokens"},"min_performance_benchmark":{"type":"number","description":"Minimum performance benchmark score"},"min_time_to_first_token_ms":{"type":"integer","description":"Maximum time to first token in milliseconds"},"model_id":{"type":"string","description":"Model identifier","nullable":true},"model_version":{"type":"string","description":"Model version","nullable":true},"usage":{"type":"string","description":"Usage type or category"}}},"basic_info":{"type":"object","nullable":true,"properties":{"service_type":{"type":"string"},"model_category":{"type":"string","description":"Model category classification","nullable":true},"currency_code":{"type":"string"},"precision":{"type":"integer"}}},"sla_requirements":{"type":"object","properties":{"availability_target":{"type":"number","description":"Target uptime as a percentage (e.g., 99.95 means 99.95% availability)\n"},"availability_sla":{"type":"number","description":"Availability SLA (percentage). May be present in API responses.","nullable":true},"max_latency_ms":{"type":"integer","description":"Maximum acceptable response latency in milliseconds\n"},"min_latency_ms":{"type":"integer","description":"Minimum latency in milliseconds. May be present in API responses.","nullable":true},"quality_score_min":{"type":"number","description":"Minimum quality score threshold (0-100)\n"}}},"trading_params":{"type":"object","properties":{"min_quantity":{"type":"integer"},"max_quantity":{"type":"integer"},"quantity_increment":{"type":"integer"},"fee":{"type":"string","description":"Fee rate (decimal string)"}}},"last_trade_price":{"type":"string","nullable":true},"last_trade_at":{"type":"string","format":"date-time","nullable":true},"last_quote_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of most recent quote"},"total_volume":{"type":"string"},"volume_24h":{"type":"string"},"total_trades":{"type":"integer"},"total_quotes":{"type":"integer"},"price_range_24h_high":{"type":"string","nullable":true,"description":"Highest price in last 24 hours"},"price_range_24h_low":{"type":"string","nullable":true,"description":"Lowest price in last 24 hours"}}},"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":{"/instruments/{instrument_id}":{"get":{"tags":["Instruments"],"summary":"Get instrument details","description":"Gets a specific instrument by its ID. Returns full instrument details including\ntrading parameters and AI specifications.\n","operationId":"getInstrument","parameters":[{"name":"instrument_id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier for the instrument (e.g., \"instrument_c18a986c-522b-475a-b319-f2d0ba04a64d\")\n"}],"responses":{"200":{"description":"Instrument details\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstrumentDetailResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
---
# 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/instruments.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.