# Trades
Trade history associated with the authenticated user. Trades are individual fills for a given order.
## Get user's trade history
> Get your trade history (fills). Results are always the authenticated user's trades.\
> Use the \`order\_id\` filter to limit results to trades for a specific order (the user's order\
> associated with each trade, as returned in the response \`order\_id\` field).
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Trades","description":"Trade history associated with the authenticated user. Trades are individual fills for a given order.\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":{"TradeListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UserTrade"}},"paging":{"$ref":"#/components/schemas/CursorPaging"}}},"UserTrade":{"type":"object","description":"Trade details from the user's perspective\n","properties":{"trade_id":{"type":"string","description":"Trade identifier\n"},"market_id":{"type":"string"},"market_name":{"type":"string"},"instrument_id":{"type":"string"},"instrument_name":{"type":"string"},"instrument_symbol":{"type":"string"},"order_id":{"type":"string","description":"The user's order ID associated with this trade\n"},"trading_account_id":{"type":"string","description":"The user's trading account ID\n"},"price":{"type":"string"},"quantity":{"type":"integer"},"total_value":{"type":"string"},"fee":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"status":{"type":"string","enum":["executed","settled"]},"execution_timestamp":{"type":"string","format":"date-time"},"settlement_timestamp":{"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":{"/trades":{"get":{"tags":["Trades"],"summary":"Get user's trade history","description":"Get your trade history (fills). Results are always the authenticated user's trades.\nUse the `order_id` filter to limit results to trades for a specific order (the user's order\nassociated with each trade, as returned in the response `order_id` field).\n","operationId":"tradingListTrades","parameters":[{"name":"market_id","in":"query","schema":{"type":"string"},"description":"Filter by market ID"},{"name":"instrument_id","in":"query","schema":{"type":"string"},"description":"Filter by instrument ID"},{"name":"trade_id","in":"query","schema":{"type":"string"},"description":"Filter by trade ID"},{"name":"order_id","in":"query","schema":{"type":"string"},"description":"Filter by the user's order ID associated with the trade (canonical filter for \"my\" trades).\nMatches the `order_id` field returned on each trade.\n"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Filter by trade status"},{"name":"buyer_order_id","in":"query","schema":{"type":"string"},"description":"Filter by buyer's order ID (legacy; prefer `order_id` for user's trades)"},{"name":"seller_order_id","in":"query","schema":{"type":"string"},"description":"Filter by seller's order ID (legacy; prefer `order_id` for user's trades)"},{"name":"triggering_order_id","in":"query","schema":{"type":"string"},"description":"Filter by the order that triggered the trade (legacy; prefer `order_id` for user's trades)"},{"name":"start_datetime","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter trades executed at or after this time (ISO8601 or Unix timestamp)"},{"name":"end_datetime","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","trade_id","price","quantity","total_value"]},"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":"List of trades\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeListResponse"}}}}}}}}}
```
## Get single trade
> Returns a single trade with metadata.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Trades","description":"Trade history associated with the authenticated user. Trades are individual fills for a given order.\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":{"UserTrade":{"type":"object","description":"Trade details from the user's perspective\n","properties":{"trade_id":{"type":"string","description":"Trade identifier\n"},"market_id":{"type":"string"},"market_name":{"type":"string"},"instrument_id":{"type":"string"},"instrument_name":{"type":"string"},"instrument_symbol":{"type":"string"},"order_id":{"type":"string","description":"The user's order ID associated with this trade\n"},"trading_account_id":{"type":"string","description":"The user's trading account ID\n"},"price":{"type":"string"},"quantity":{"type":"integer"},"total_value":{"type":"string"},"fee":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"status":{"type":"string","enum":["executed","settled"]},"execution_timestamp":{"type":"string","format":"date-time"},"settlement_timestamp":{"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":{"/trades/{trade_id}":{"get":{"tags":["Trades"],"summary":"Get single trade","description":"Returns a single trade with metadata.\n","operationId":"tradingGetTrade","parameters":[{"name":"trade_id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier for the trade (e.g., \"trade_d7b40819-0ea6-428b-b00c-deb559206cb7\")\n"}],"responses":{"200":{"description":"Trade details\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserTrade"}}}}}},"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/trades.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.