# 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:**

```http
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:**

```http
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:**

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

**Error Response:**

```json
{
  "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 /v1/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 /v1/orders?order_by=submitted_at&order_direction=desc
```

See each endpoint's documentation for available sortable fields.