Request & Response Conventions

Request Headers

Header	Description
Content-Type	Must be application/json for POST/PUT/PATCH requests
x-thegrid-signature	Base64-encoded Ed25519 signature
x-thegrid-timestamp	Unix timestamp in seconds
x-thegrid-fingerprint	SHA256 hash of your public key (Base64-encoded)

Example Request Headers:

Content-Type: application/json
x-thegrid-signature: 7Rp4K9mXvQ2hLwYzN8bJcT1gFdAeS6uHxI0oP3nMkWqVrCtByD5aUfGjElZiOsXm+4K8R2vN1hLwYzMbJcT6gFdA==
x-thegrid-timestamp: 1739145600
x-thegrid-fingerprint: Yk3mN7pRtV2xLwQzH8bJcS1gFdAeU6uHxI0oP3nMkWq

Request Format

• Body: JSON-encoded request body for POST/PUT requests

• Query Parameters: URL-encoded for GET requests

Response Headers

All API responses include the following headers:

Header	Description
x-request-id	Unique request identifier for debugging and support inquiries
x-ratelimit-limit	Maximum requests allowed in the current time window
x-ratelimit-remaining	Requests remaining in the current time window
x-ratelimit-reset	Unix timestamp when the rate limit window resets
x-ratelimit-retry-after	Seconds to wait before retrying (only present on 429 responses)

Example Response Headers:

x-request-id: GIkgbPVEdBDYQbcAAChF
x-ratelimit-limit: 100
x-ratelimit-remaining: 95
x-ratelimit-reset: 1640995200

Tip: Always include the x-request-id value when contacting support to help diagnose issues.

Response Body Format

Success Response:

{
  "data": [ ... ],
  "paging": {
    "has_more": false,
    "next_cursor": null,
    "prev_cursor": null
  }
}

Error Response:

{
  "data": null,
  "error": "Error message",
  "errors": {
    "detail": "Detailed error information"
  },
  "meta": {
    "request_id": "GIkgbPVEdBDYQbcAAChF",
    "timestamp": "2025-01-01T00:00:00Z"
  }
}

Filtering

Many list endpoints support filtering to narrow down results. Filter parameters are passed as query parameters and vary by endpoint.

Common filter patterns:

Filter Type	Example	Description
Exact match	status=active	Returns items where field equals value
Date range	start_datetime=2024-01-01T00:00:00Z	Returns items after the specified date

Example filtered request:

GET /api/v1/trading/orders?status=active&market_id=market_b310e860-97cd-45eb-bdc3-5be0b79295d0

See each endpoint's documentation for available filter parameters.

Sorting

List endpoints support sorting results using the order_by and order_direction parameters.

Parameter	Type	Description
order_by	string	Field to sort by. Must be one of the endpoint's sortable fields.
order_direction	string	Sort direction: asc (ascending) or desc (descending). Default: asc.

Example sorted request:

GET /api/v1/trading/orders?order_by=submitted_at&order_direction=desc

See each endpoint's documentation for available sortable fields.