# Orders
Order management including creation, cancellation, and updates
## List trader's orders
> Returns the authenticated trader's orders using Ed25519 signature authentication.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management including creation, cancellation, and updates\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":{"TradingOrderListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"paging":{"$ref":"#/components/schemas/CursorPaging"}}},"Order":{"type":"object","properties":{"order_id":{"type":"string","description":"Unique identifier for the order (was `id` in legacy API)"},"market_id":{"type":"string"},"market_name":{"type":"string","nullable":true},"instrument_id":{"type":"string"},"instrument_name":{"type":"string","nullable":true},"instrument_symbol":{"type":"string","nullable":true},"trader_id":{"type":"string"},"type":{"type":"string","enum":["limit","market","stop","stop_limit"]},"side":{"type":"string","enum":["buy","sell"]},"price":{"type":"string","nullable":true,"description":"Limit price per unit in quote currency (USD). Null for market orders.\n"},"quantity":{"type":"integer","description":"Total order quantity in units (was `size` in legacy API)\n"},"filled_quantity":{"type":"integer","description":"Number of units that have been filled so far\n"},"filled_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the order was completely filled. Null if the order has not been fully filled yet.\n"},"average_price":{"type":"string","nullable":true,"description":"Volume-weighted average fill price across all fills for this order\n"},"fee":{"type":"string","description":"Trading fee charged for this order in quote currency (USD)\n"},"status":{"type":"string","enum":["active","pending","partially_filled","filled","closed","cancellation_pending"]},"closure_reason":{"type":"string","nullable":true,"description":"Reason the order was closed. Only present when status is \"closed\" or \"filled\".\n- `filled`: Order was completely filled\n- `cancelled`: Order was manually cancelled by the user\n- `cancel_and_replace`: Order was cancelled as part of a cancel-and-replace operation\n- `expired`: Order expired (e.g., day orders at end of trading day)\n- `rejected`: Order was rejected by the matching engine\n- `partially_filled_no_liquidity`: Order was partially filled then closed because no remaining liquidity was available\n- `partially_filled_max_slippage`: Order was partially filled then closed because price moved beyond acceptable slippage\n- `partially_filled_insufficient_balance`: Order was partially filled then closed due to insufficient balance\n- `no_fill_no_liquidity`: Market order could not fill due to no available liquidity\n- `no_fill_max_slippage`: Market order could not fill within the acceptable slippage tolerance\n- `no_fill_insufficient_balance`: Order could not fill due to insufficient balance\n","enum":["filled","cancelled","cancel_and_replace","expired","rejected","partially_filled_no_liquidity","partially_filled_max_slippage","partially_filled_insufficient_balance","no_fill_no_liquidity","no_fill_max_slippage","no_fill_insufficient_balance",null]},"time_in_force":{"type":"string","enum":["gtc","ioc","fok","day"],"description":"Order duration policy.\n- `gtc` (Good Till Cancelled): Order remains active until completely filled or manually cancelled\n- `ioc` (Immediate Or Cancel): Order executes immediately for available quantity, remainder is cancelled\n- `fok` (Fill Or Kill): Order must be completely filled immediately or entirely cancelled\n- `day`: Order expires at the end of the trading day if not filled\n"},"stop_price":{"type":"string","nullable":true},"client_order_id":{"type":"string","nullable":true},"submitted_at":{"type":"string","format":"date-time"},"closed_at":{"type":"string","format":"date-time","nullable":true},"triggered_by_auto_top_up":{"type":"boolean","description":"Whether this order was automatically triggered by the auto top-up feature\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":{"RateLimitExceeded":{"description":"Rate limit exceeded - Too many requests in the current time window\n","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/orders":{"get":{"tags":["Orders"],"summary":"List trader's orders","description":"Returns the authenticated trader's orders using Ed25519 signature authentication.\n","operationId":"tradingListOrders","parameters":[{"name":"market_id","in":"query","schema":{"type":"string"},"description":"Filter by market ID"},{"name":"trader_id","in":"query","schema":{"type":"string"},"description":"Filter by trader ID"},{"name":"instrument_id","in":"query","schema":{"type":"string"},"description":"Filter by instrument ID"},{"name":"side","in":"query","schema":{"type":"string","enum":["buy","sell"]},"description":"Filter by order side"},{"name":"status","in":"query","schema":{"type":"string","enum":["active","closed","cancelled"]},"description":"Filter by order status"},{"name":"start_datetime","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter orders submitted at or after this time (ISO8601 or Unix timestamp)"},{"name":"end_datetime","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter orders submitted at or before this time (ISO8601 or Unix timestamp)"},{"name":"order_by","in":"query","schema":{"type":"string","enum":["submitted_at","filled_at","price","original_quantity","quantity","order_id"]},"description":"Field to sort by (`quantity` is alias for original_quantity)"},{"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 orders\n","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradingOrderListResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}}}}
```
## Place order
> Create a new order using Ed25519 signature authentication.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management including creation, cancellation, and updates\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":{"TradingCreateOrderRequest":{"type":"object","required":["market_id","side","type","quantity"],"properties":{"market_id":{"type":"string","description":"Market identifier where the order will be placed\n"},"client_order_id":{"type":"string","description":"Optional client-provided order ID for idempotency. Must be unique per account. Duplicate IDs will return a 422 error with message \"client_order_id already exists\".\n","nullable":true},"side":{"type":"string","enum":["buy","sell"],"description":"Order side: \"buy\" to purchase the instrument, \"sell\" to sell. Value is normalized to lowercase.\n"},"type":{"type":"string","enum":["limit","market"],"description":"Order type: \"limit\" executes at specified price or better, \"market\" executes immediately at best available price. Value is normalized to lowercase.\n"},"price":{"type":"string","description":"Price per unit in quote currency (USD). **Required for limit orders, must be omitted for market orders.** Must be a positive number >= 0.0001 with at most 4 decimal places (tick size).\n"},"quantity":{"type":"integer","minimum":1,"maximum":100,"description":"Number of units to buy or sell. Must be a positive integer, maximum 100 per order.\n"},"time_in_force":{"type":"string","enum":["gtc","ioc","fok","day"],"description":"Order duration policy. Value is normalized to lowercase.\n- `gtc` (Good Till Cancelled): Order remains active until completely filled or manually cancelled\n- `ioc` (Immediate Or Cancel): Order executes immediately for available quantity, remainder is cancelled\n- `fok` (Fill Or Kill): Order must be completely filled immediately or entirely cancelled\n- `day`: Order expires at the end of the trading day if not filled\n","default":"gtc"}}},"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":{"/orders":{"post":{"tags":["Orders"],"summary":"Place order","description":"Create a new order using Ed25519 signature authentication.\n","operationId":"tradingCreateOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradingCreateOrderRequest"}}}},"responses":{"201":{"description":"Order created\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"order_id":{"type":"string"},"client_order_id":{"type":"string","nullable":true}}}}}}}},"400":{"description":"Invalid order parameters\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}}}}
```
## Get order details
> Returns details of a specific order.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management including creation, cancellation, and updates\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":{"Order":{"type":"object","properties":{"order_id":{"type":"string","description":"Unique identifier for the order (was `id` in legacy API)"},"market_id":{"type":"string"},"market_name":{"type":"string","nullable":true},"instrument_id":{"type":"string"},"instrument_name":{"type":"string","nullable":true},"instrument_symbol":{"type":"string","nullable":true},"trader_id":{"type":"string"},"type":{"type":"string","enum":["limit","market","stop","stop_limit"]},"side":{"type":"string","enum":["buy","sell"]},"price":{"type":"string","nullable":true,"description":"Limit price per unit in quote currency (USD). Null for market orders.\n"},"quantity":{"type":"integer","description":"Total order quantity in units (was `size` in legacy API)\n"},"filled_quantity":{"type":"integer","description":"Number of units that have been filled so far\n"},"filled_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the order was completely filled. Null if the order has not been fully filled yet.\n"},"average_price":{"type":"string","nullable":true,"description":"Volume-weighted average fill price across all fills for this order\n"},"fee":{"type":"string","description":"Trading fee charged for this order in quote currency (USD)\n"},"status":{"type":"string","enum":["active","pending","partially_filled","filled","closed","cancellation_pending"]},"closure_reason":{"type":"string","nullable":true,"description":"Reason the order was closed. Only present when status is \"closed\" or \"filled\".\n- `filled`: Order was completely filled\n- `cancelled`: Order was manually cancelled by the user\n- `cancel_and_replace`: Order was cancelled as part of a cancel-and-replace operation\n- `expired`: Order expired (e.g., day orders at end of trading day)\n- `rejected`: Order was rejected by the matching engine\n- `partially_filled_no_liquidity`: Order was partially filled then closed because no remaining liquidity was available\n- `partially_filled_max_slippage`: Order was partially filled then closed because price moved beyond acceptable slippage\n- `partially_filled_insufficient_balance`: Order was partially filled then closed due to insufficient balance\n- `no_fill_no_liquidity`: Market order could not fill due to no available liquidity\n- `no_fill_max_slippage`: Market order could not fill within the acceptable slippage tolerance\n- `no_fill_insufficient_balance`: Order could not fill due to insufficient balance\n","enum":["filled","cancelled","cancel_and_replace","expired","rejected","partially_filled_no_liquidity","partially_filled_max_slippage","partially_filled_insufficient_balance","no_fill_no_liquidity","no_fill_max_slippage","no_fill_insufficient_balance",null]},"time_in_force":{"type":"string","enum":["gtc","ioc","fok","day"],"description":"Order duration policy.\n- `gtc` (Good Till Cancelled): Order remains active until completely filled or manually cancelled\n- `ioc` (Immediate Or Cancel): Order executes immediately for available quantity, remainder is cancelled\n- `fok` (Fill Or Kill): Order must be completely filled immediately or entirely cancelled\n- `day`: Order expires at the end of the trading day if not filled\n"},"stop_price":{"type":"string","nullable":true},"client_order_id":{"type":"string","nullable":true},"submitted_at":{"type":"string","format":"date-time"},"closed_at":{"type":"string","format":"date-time","nullable":true},"triggered_by_auto_top_up":{"type":"boolean","description":"Whether this order was automatically triggered by the auto top-up feature\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":{"NotFound":{"description":"Not found - The requested resource does not exist\n","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/orders/{order_id}":{"get":{"tags":["Orders"],"summary":"Get order details","description":"Returns details of a specific order.\n","operationId":"tradingGetOrder","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier for the order (e.g., \"order_TT64AI5BZNLKUFTL\")\n"}],"responses":{"200":{"description":"Order details\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Cancel order
> Cancel an order using Ed25519 signature authentication.
```json
{"openapi":"3.0.3","info":{"title":"Trading API","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management including creation, cancellation, and updates\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"}},"responses":{"NotFound":{"description":"Not found - The requested resource does not exist\n","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"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)"}}}}},"paths":{"/orders/{order_id}":{"delete":{"tags":["Orders"],"summary":"Cancel order","description":"Cancel an order using Ed25519 signature authentication.\n","operationId":"tradingCancelOrder","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier for the order (e.g., \"order_TT64AI5BZNLKUFTL\")\n"}],"responses":{"204":{"description":"Order cancelled successfully\n"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Order already cancelled\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# 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/orders.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.