> This page is for Taurus PRIME.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://taurushq.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://taurushq.ferndocs.com/_mcp/server.

# Making Requests

# Making Requests

This guide covers the request and response format for the PRIME REST API.

## Base URL

```
https://api.t-dx.com/api/rest/v1/
```

All endpoints are prefixed with `/api/rest/v1/`.

---

## Request Headers

### Required Headers

| Header          | Value                                       | Description                 |
| --------------- | ------------------------------------------- | --------------------------- |
| `Authorization` | `Bearer <token>` or `TDXV1-HMAC-SHA256 ...` | Authentication              |
| `Content-Type`  | `application/json`                          | Required for POST/PUT/PATCH |

### Optional Headers

| Header             | Value              | Description                                 |
| ------------------ | ------------------ | ------------------------------------------- |
| `Accept`           | `application/json` | Response format (default)                   |
| `X-Correlation-ID` | UUID               | Request tracing (auto-generated if omitted) |

### Example Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/instruments" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Accept: application/json"
```

---

## Naming Conventions

The API uses different naming conventions for different contexts:

| Context           | Convention  | Example                                  |
| ----------------- | ----------- | ---------------------------------------- |
| JSON body fields  | camelCase   | `subAccountId`, `pairId`, `createdAt`    |
| Query parameters  | snake\_case | `pair_id`, `instrument_id`, `created_at` |
| URL path segments | kebab-case  | `/sub-accounts`, `/client-accounts`      |

---

## Request Body

For POST, PUT, and PATCH requests, send JSON in the request body. **Use camelCase for all field names.**

```bash
curl -X POST "https://api.t-dx.com/api/rest/v1/orders" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subAccountId": "uuid",
    "pairId": "uuid",
    "side": "SIDE_BUY",
    "type": "TYPE_LIMIT",
    "quantity": "1.5",
    "price": "45000.00"
  }'
```

### Decimal Values

Decimal values (prices, quantities, amounts) are sent as **strings** to preserve precision:

```json
{
  "quantity": "1.50000000",
  "price": "45000.00"
}
```

---

## Response Format

### Success Response

Response bodies use **camelCase** field names:

```json
{
  "id": "resource-uuid",
  "field1": "value1",
  "field2": "value2",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

### List Response with Pagination

```json
{
  "items": [
    { "id": "uuid-1", ... },
    { "id": "uuid-2", ... }
  ],
  "pagination": {
    "cursors": {
      "self": "eyJTb3J0cyI6...",
      "first": "eyJTb3J0cyI6...",
      "last": "eyJTb3J0cyI6...",
      "next": "eyJTb3J0cyI6...",
      "previous": ""
    }
  }
}
```

---

## Pagination

The API uses **cursor-based pagination** for list endpoints.

### Query Parameters

| Parameter | Type    | Description                                  |
| --------- | ------- | -------------------------------------------- |
| `limit`   | integer | Results per page (1-500, default varies)     |
| `cursor`  | string  | Base64-encoded cursor from previous response |

### Example: First Page

```bash
GET /api/rest/v1/instruments?limit=50
```

### Example: Next Page

```bash
GET /api/rest/v1/instruments?limit=50&cursor=eyJTb3J0cyI6W3si...
```

### Cursor Structure

Cursors are Base64-encoded JSON containing:

* Sort configuration
* Filter state
* Position markers

**Do not construct cursors manually.** Always use cursors from the API response.

### Pagination Response

```json
{
  "pagination": {
    "cursors": {
      "self": "current-page-cursor",
      "first": "first-page-cursor",
      "last": "last-page-cursor",
      "next": "next-page-cursor",
      "previous": "previous-page-cursor"
    }
  }
}
```

* Empty `next` = no more pages forward
* Empty `previous` = no more pages backward

---

## Sorting

Sort results using the `sort` query parameter.

### Format

```
sort=<field>-<direction>
```

### Directions

| Direction | Description                    |
| --------- | ------------------------------ |
| `asc`     | Ascending (oldest first, A-Z)  |
| `desc`    | Descending (newest first, Z-A) |

### Example

```bash
GET /api/rest/v1/orders?sort=created_at-desc
```

### Common Sort Fields

| Field        | Description            |
| ------------ | ---------------------- |
| `created_at` | Creation timestamp     |
| `updated_at` | Last update timestamp  |
| `name`       | Alphabetical by name   |
| `symbol`     | Alphabetical by symbol |

---

## Filtering

Filter results using query parameters or the `query` parameter.

### Simple Filters

```bash
GET /api/rest/v1/orders?status=STATUS_OPEN&side=SIDE_BUY
```

### Range Filters

```bash
GET /api/rest/v1/trades?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z
```

### Multiple Values

```bash
GET /api/rest/v1/instruments?type=CRYPTO_CURRENCY&type=CURRENCY
```

### Filter Types

| Type    | Description               | Example                                   |
| ------- | ------------------------- | ----------------------------------------- |
| Value   | Single value match        | `status=STATUS_OPEN`                      |
| Values  | Multiple value match (OR) | `status=STATUS_OPEN&status=STATUS_FILLED` |
| Range   | Between two values        | `from=...&to=...`                         |
| Boolean | True/false                | `tradable=true`                           |

---

## Date and Time

All timestamps use **ISO 8601 format** in **UTC**:

```
2024-01-15T10:30:00Z
```

### Query Parameter Format

```bash
GET /api/rest/v1/trades?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z
```

### Response Format

```json
{
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:22:00Z"
}
```

---

## HTTP Methods

| Method   | Usage              |
| -------- | ------------------ |
| `GET`    | Retrieve resources |
| `POST`   | Create resources   |
| `PUT`    | Replace resources  |
| `PATCH`  | Partial update     |
| `DELETE` | Remove resources   |

---

## Status Codes

### Success Codes

| Code | Description                       |
| ---- | --------------------------------- |
| 200  | Success (GET, PUT, PATCH, DELETE) |
| 201  | Created (POST)                    |
| 204  | No Content (DELETE with no body)  |

### Client Error Codes

| Code | Description                              |
| ---- | ---------------------------------------- |
| 400  | Bad Request - Invalid parameters         |
| 401  | Unauthorized - Authentication required   |
| 403  | Forbidden - Insufficient permissions     |
| 404  | Not Found - Resource doesn't exist       |
| 409  | Conflict - Resource already exists       |
| 422  | Unprocessable Entity - Validation failed |
| 429  | Too Many Requests - Rate limited         |

### Server Error Codes

| Code | Description           |
| ---- | --------------------- |
| 500  | Internal Server Error |
| 503  | Service Unavailable   |

---

## Rate Limiting

The API implements rate limiting to ensure fair usage.

### Response Headers

When rate limited, the response includes:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

### Best Practices

1. Implement exponential backoff on 429 responses
2. Cache responses where appropriate
3. Use WebSocket for real-time data instead of polling
4. Batch requests where possible

---

## CORS

The API supports Cross-Origin Resource Sharing (CORS) for browser-based clients.

### Allowed Headers

* `Content-Type`
* `Accept`
* `Authorization`

### Preflight Requests

OPTIONS requests are handled automatically for CORS preflight.