> 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.

# Trading Data

# Trading Data Collection

This guide covers retrieving market data, instruments, pairs, prices, and trade history.

## Overview

Before trading, you need to understand available markets and their properties. This involves:

1. Fetching available instruments (assets)
2. Fetching trading pairs and their constraints
3. Retrieving price data
4. Viewing trade history

## Prerequisites

* Authenticated session (JWT or API key)
* `CanRead` permission

## Step 1: List Available Instruments

Retrieve all tradable instruments.

**Endpoint:** `GET /api/rest/v1/instruments`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/instruments" \
  -H "Authorization: Bearer <access-token>"
```

### Query Parameters

This endpoint supports [standard pagination, sorting, and filtering](/prime/docs/api-gett-making-requests#pagination).

### Response (200 OK)

```json
{
  "result": [
    {
      "id": "7a3fae7e-5a17-4931-821c-54b021f643da",
      "symbol": "BTC",
      "type": "TYPE_CRYPTO_CURRENCY",
      "decimals": 8,
      "blockchain": "bitcoin",
      "nativeCurrency": true,
      "depositEnabled": true,
      "withdrawalEnabled": true,
      "createdAt": "2023-01-01T00:00:00Z",
      "updatedAt": "2023-01-01T00:00:00Z"
    },
    {
      "id": "8b4gbf8f-6b28-5042-932d-65c132g754eb",
      "symbol": "CHF",
      "type": "TYPE_CURRENCY",
      "decimals": 2,
      "depositEnabled": true,
      "withdrawalEnabled": true,
      "createdAt": "2023-01-01T00:00:00Z",
      "updatedAt": "2023-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "cursors": {
      "self": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "first": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "last": "",
      "next": "",
      "previous": ""
    }
  }
}
```

### Instrument Types

| Type                   | Description                   |
| ---------------------- | ----------------------------- |
| `TYPE_CURRENCY`        | Fiat currency (CHF, EUR, USD) |
| `TYPE_CRYPTO_CURRENCY` | Cryptocurrency (BTC, ETH)     |
| `TYPE_STOCK`           | Tokenized equity              |
| `TYPE_DEBT`            | Debt instrument               |
| `TYPE_FUND_SHARES`     | Fund shares                   |

## Step 2: List Trading Pairs

Retrieve all available trading pairs with their constraints.

**Endpoint:** `GET /api/rest/v1/pairs`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/pairs" \
  -H "Authorization: Bearer <access-token>"
```

### Response (200 OK)

```json
{
  "result": [
    {
      "id": "79b1db24-7dc8-45d1-ab77-44318f872a8e",
      "baseId": "7a3fae7e-5a17-4931-821c-54b021f643da",
      "quoteId": "8b4gbf8f-6b28-5042-932d-65c132g754eb",
      "symbol": "BTC/CHF",
      "status": "STATUS_OPEN",
      "tradable": true,
      "otcTradable": true,
      "minOrderQuantity": "0.0001",
      "maxOrderQuantity": "100",
      "priceDecimalPoints": 2,
      "priceTicks": "0.01",
      "quantityDecimalPoints": 8,
      "quantityTicks": "0.00000001",
      "referencePrice": "45000.00",
      "createdAt": "2023-01-01T00:00:00Z",
      "updatedAt": "2023-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "cursors": {
      "self": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "first": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "last": "",
      "next": "",
      "previous": ""
    }
  }
}
```

### Understanding Pair Constraints

| Field                   | Meaning                    | Example        |
| ----------------------- | -------------------------- | -------------- |
| `minOrderQuantity`      | Minimum order size         | 0.0001 BTC     |
| `maxOrderQuantity`      | Maximum order size         | 100 BTC        |
| `priceDecimalPoints`    | Price precision            | 2 → 45000.00   |
| `priceTicks`            | Minimum price increment    | 0.01           |
| `quantityDecimalPoints` | Quantity precision         | 8 → 0.00000001 |
| `quantityTicks`         | Minimum quantity increment | 0.00000001     |

## Step 3: Get Current Prices

Retrieve current market prices.

**Endpoint:** `GET /api/rest/v1/prices`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/prices" \
  -H "Authorization: Bearer <access-token>"
```

### Response (200 OK)

```json
{
  "result": [
    {
      "pairId": "79b1db24-7dc8-45d1-ab77-44318f872a8e",
      "bid": "44950.00",
      "ask": "45050.00",
      "last": "45000.00",
      "timestamp": "2024-01-15T14:30:00Z"
    }
  ],
  "pagination": {
    "hasNextPage": false,
    "cursor": ""
  }
}
```

## Step 4: Get Public Marketplace Trades

View recent public trades for a pair.

**Endpoint:** `GET /api/rest/v1/marketplace/trades`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/marketplace/trades?pairId=79b1db24-7dc8-45d1-ab77-44318f872a8e&limit=50" \
  -H "Authorization: Bearer <access-token>"
```

### Query Parameters

This endpoint supports [standard pagination and sorting](/prime/docs/api-gett-making-requests#pagination).

| Parameter | Type | Required | Description               |
| --------- | ---- | -------- | ------------------------- |
| `pairId`  | UUID | Yes      | Pair ID to get trades for |

### Response (200 OK)

```json
{
  "result": [
    {
      "id": "trade-uuid-1",
      "pairId": "79b1db24-7dc8-45d1-ab77-44318f872a8e",
      "side": "SIDE_BUY",
      "quantity": "0.25",
      "originalQuantity": "0.50",
      "cumulativeQuantity": "0.25",
      "price": "45000.00",
      "grossAmount": "11250.00",
      "isTaker": true,
      "executedAt": "2024-01-15T14:29:55Z",
      "createdAt": "2024-01-15T14:29:55Z",
      "updatedAt": "2024-01-15T14:29:55Z"
    },
    {
      "id": "trade-uuid-2",
      "pairId": "79b1db24-7dc8-45d1-ab77-44318f872a8e",
      "side": "SIDE_SELL",
      "quantity": "0.10",
      "originalQuantity": "0.10",
      "cumulativeQuantity": "0.10",
      "price": "44995.00",
      "grossAmount": "4499.50",
      "isTaker": false,
      "executedAt": "2024-01-15T14:29:30Z",
      "createdAt": "2024-01-15T14:29:30Z",
      "updatedAt": "2024-01-15T14:29:30Z"
    }
  ],
  "pagination": {
    "hasNextPage": false,
    "cursor": ""
  }
}
```

### Marketplace Trade Fields (Anonymized)

| Field                | Type      | Description                    |
| -------------------- | --------- | ------------------------------ |
| `id`                 | UUID      | Trade identifier               |
| `pairId`             | UUID      | Trading pair ID                |
| `side`               | enum      | `SIDE_BUY` or `SIDE_SELL`      |
| `quantity`           | decimal   | Quantity in this trade         |
| `originalQuantity`   | decimal   | Original order quantity        |
| `cumulativeQuantity` | decimal   | Total executed quantity        |
| `price`              | decimal   | Execution price                |
| `grossAmount`        | decimal   | Amount in quote currency       |
| `isTaker`            | boolean   | Whether this was a taker trade |
| `executedAt`         | timestamp | Execution time                 |
| `createdAt`          | timestamp | Creation time                  |
| `updatedAt`          | timestamp | Last update time               |

## Step 5: Get Your Trade History

View your own executed trades.

**Endpoint:** `GET /api/rest/v1/trades`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/trades?subAccountId=7376524e-6b6b-4137-9719-7e07a7709804" \
  -H "Authorization: Bearer <access-token>"
```

### Query Parameters

This endpoint supports [standard pagination, sorting, and filtering](/prime/docs/api-gett-making-requests#pagination).

| Parameter      | Type | Description                      |
| -------------- | ---- | -------------------------------- |
| `subAccountId` | UUID | Filter by sub-account (optional) |

**Supported filters:** `side`, `pair_id`

### Response (200 OK)

```json
{
  "result": [
    {
      "id": "9120c519-9b22-4afe-9c73-998638d83e4a",
      "orderId": "2312bb39-a624-4785-aaf7-49b09034b560",
      "pairId": "79b1db24-7dc8-45d1-ab77-44318f872a8e",
      "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
      "clientAccountId": "8aee564e-2eb1-4a57-b686-05476c2cfd93",
      "userId": "c43f7356-ad91-48bf-b647-96aa3ec59cf2",
      "side": "SIDE_BUY",
      "quantity": "0.50",
      "originalQuantity": "1.00",
      "cumulativeQuantity": "0.50",
      "price": "45000.00",
      "grossAmount": "22500.00",
      "transactionFee": "22.50",
      "transactionFeeRate": "0.001",
      "swissStampTax": "3.38",
      "swissStampTaxRate": "0.00015",
      "isTaker": true,
      "executedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "cursors": {
      "self": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "first": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "last": "",
      "next": "",
      "previous": ""
    }
  }
}
```

### Trade Fields

| Field                | Type               | Description                                 |
| -------------------- | ------------------ | ------------------------------------------- |
| `id`                 | UUID               | Trade identifier                            |
| `orderId`            | UUID               | Parent order ID                             |
| `pairId`             | UUID               | Trading pair ID                             |
| `subAccountId`       | UUID               | Sub-account ID                              |
| `clientAccountId`    | UUID               | Client account ID                           |
| `userId`             | UUID               | User who created the order                  |
| `side`               | enum               | `SIDE_BUY` or `SIDE_SELL`                   |
| `quantity`           | decimal            | Quantity matched in this trade              |
| `originalQuantity`   | decimal            | Original order quantity                     |
| `cumulativeQuantity` | decimal            | Total executed quantity of the order        |
| `price`              | decimal            | Execution price                             |
| `grossAmount`        | decimal            | Amount in quote currency (quantity × price) |
| `transactionFee`     | decimal (optional) | Trading fee                                 |
| `transactionFeeRate` | decimal (optional) | Fee rate applied                            |
| `swissStampTax`      | decimal (optional) | Swiss stamp tax if applicable               |
| `swissStampTaxRate`  | decimal (optional) | Stamp tax rate                              |
| `isTaker`            | boolean            | Whether this was a taker trade              |
| `executedAt`         | timestamp          | Execution time                              |
| `createdAt`          | timestamp          | Creation time                               |
| `updatedAt`          | timestamp          | Last update time                            |

## Step 6: Get Trade Volumes

Get aggregated trade volumes by pair over a date range.

**Endpoint:** `GET /api/rest/v1/trade-volumes`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/trade-volumes?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer <access-token>"
```

### Query Parameters

This endpoint supports [standard pagination and sorting](/prime/docs/api-gett-making-requests#pagination).

| Parameter   | Type      | Required | Description         |
| ----------- | --------- | -------- | ------------------- |
| `startDate` | timestamp | Yes      | Start of date range |
| `endDate`   | timestamp | Yes      | End of date range   |

### Response (200 OK)

```json
{
  "result": [
    {
      "pairId": "79b1db24-7dc8-45d1-ab77-44318f872a8e",
      "symbol": "BTC/CHF",
      "volume": "125.50",
      "participants": {
        "volume": "62.75",
        "maxDaily": "12.50"
      },
      "venue": {
        "volume": "62.75",
        "maxDaily": "15.00"
      }
    }
  ],
  "pagination": {
    "cursors": {
      "self": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "first": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "last": "",
      "next": "",
      "previous": ""
    }
  }
}
```

### TradeVolume Fields

| Field                   | Type    | Description                             |
| ----------------------- | ------- | --------------------------------------- |
| `pairId`                | UUID    | Trading pair ID                         |
| `symbol`                | string  | Pair symbol (e.g., "BTC/CHF")           |
| `volume`                | decimal | Total volume across all parties         |
| `participants`          | object  | Participant volume data                 |
| `participants.volume`   | decimal | Total participant volume over the range |
| `participants.maxDaily` | decimal | Largest daily participant volume        |
| `venue`                 | object  | Venue volume data                       |
| `venue.volume`          | decimal | Total venue volume over the range       |
| `venue.maxDaily`        | decimal | Largest daily venue volume              |

## Step 7: Get a Specific Trade

**Endpoint:** `GET /api/rest/v1/trades/{id}`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/trades/9120c519-9b22-4afe-9c73-998638d83e4a" \
  -H "Authorization: Bearer <access-token>"
```

### Response (200 OK)

```json
{
  "result": {
    "id": "9120c519-9b22-4afe-9c73-998638d83e4a",
    "orderId": "2312bb39-a624-4785-aaf7-49b09034b560",
    "pairId": "79b1db24-7dc8-45d1-ab77-44318f872a8e",
    "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
    "clientAccountId": "8aee564e-2eb1-4a57-b686-05476c2cfd93",
    "userId": "c43f7356-ad91-48bf-b647-96aa3ec59cf2",
    "side": "SIDE_BUY",
    "quantity": "0.50",
    "originalQuantity": "1.00",
    "cumulativeQuantity": "0.50",
    "price": "45000.00",
    "grossAmount": "22500.00",
    "transactionFee": "22.50",
    "transactionFeeRate": "0.001",
    "swissStampTax": "3.38",
    "swissStampTaxRate": "0.00015",
    "isTaker": true,
    "executedAt": "2024-01-15T10:30:00Z",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
```

## Error Scenarios

| Status | Code              | Description                          |
| ------ | ----------------- | ------------------------------------ |
| 401    | `UNAUTHENTICATED` | Invalid or expired token             |
| 404    | `NOT_FOUND`       | Pair, instrument, or trade not found |

## Related

* [OTC Trading](/prime/docs/api-usec-05-otc-trading) - OTC trading workflow
* [Wallet Information](/prime/docs/api-usec-03-wallet-information) - Balance information
* [Domains: Trading](/prime/docs/api-doma-trad-trading) - Full trading API reference