> ## Documentation Index
> Fetch the complete documentation index at: https://tetrafi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Pull your workspace's trade history - from filtered lists to single-trade detail.

This guide covers the two core Trade History surfaces: listing your workspace's trades with filters, and drilling into one trade's full detail.

<Info>
  **Outcome:** two small scripts - one listing your trades, one dissecting a single trade.

  **Time:** about 5 minutes.

  **Bring:** a workspace API key or a JWT bearer token ([details](/core-concepts/authentication)); scoping happens on its own.
</Info>

## 1. List your workspace's trades

Fetch trades across every supported chain in one call - no per-network queries.

```
GET /api/v1/workspaces/{id}/trades
```

| Parameter     | Required | Type    | Description                                                                 |
| ------------- | -------- | ------- | --------------------------------------------------------------------------- |
| `id`          | Yes      | string  | Your workspace ID (path parameter)                                          |
| `status`      | No       | string  | Filter by settlement status bucket; `all` (or omitted) matches everything   |
| `corridor`    | No       | string  | Directional corridor as `source-dest`, e.g. `84532-11155420`                |
| `dateFrom`    | No       | string  | Only trades created at or after this time (RFC 3339)                        |
| `dateTo`      | No       | string  | Only trades created at or before this time (RFC 3339)                       |
| `member`      | No       | string  | Admin/Owner only - match on member name or email; ignored for other callers |
| `lpName`      | No       | string  | Case-insensitive match on LP name or solver id                              |
| `routingPath` | No       | string  | `direct` or `via_broker`; `all` (or omitted) matches everything             |
| `amountMin`   | No       | number  | Minimum trade notional in USD (inclusive)                                   |
| `amountMax`   | No       | number  | Maximum trade notional in USD (inclusive)                                   |
| `limit`       | No       | integer | Page size, clamped to 1-100 (default 25)                                    |
| `offset`      | No       | integer | Number of records to skip (default 0)                                       |
| `sortBy`      | No       | string  | Sort column, e.g. `created_at` (default), `amount_usd`, `lp_name`           |
| `sortDir`     | No       | string  | `asc` or `desc` (default)                                                   |

<CodeGroup>
  ```bash bash theme={null} theme={null}
  curl "https://api.tetrafi.io/api/v1/workspaces/ws_123/trades?limit=5&dateFrom=2026-06-20T00:00:00Z" \
    -H "X-API-Key: tfk_live_..."
  ```

  ```python python theme={null} theme={null}
  import httpx

  WS = "ws_123"
  headers = {"X-API-Key": "tfk_live_..."}

  resp = httpx.get(
      f"https://api.tetrafi.io/api/v1/workspaces/{WS}/trades",
      params={"limit": 5, "dateFrom": "2026-06-20T00:00:00Z"},
      headers=headers,
  )
  data = resp.json()

  for trade in data.get("items", []):
      route = trade.get("route", {})
      inp = route.get("input", {}).get("asset", {})
      out = route.get("output", {}).get("asset", {})
      print(
          f'{inp.get("symbol", "?")} -> {out.get("symbol", "?")}  '
          f'${trade.get("amountUsd", 0):.2f}  {trade.get("status", "")}  '
          f'({trade.get("createdAt", "")})'
      )
  ```
</CodeGroup>

### Reading What Comes Back

Trimmed to representative fields - nullable fields come back as `null` when absent (`orderKind` is omitted entirely); the full shape is in the [API reference](/trade-history-api/api-reference/trades).

```json theme={null} theme={null}
{
  "items": [
    {
      "orderId": "ord_01J49...",
      "createdAt": "2026-07-18T19:44:21Z",
      "sourceChain": "84532",
      "destChain": "11155420",
      "route": {
        "input":  { "asset": { "assetId": "eip155:84532/erc20:0x036C...CF7e", "symbol": "USDC", "resolutionStatus": "resolved" }, "rawAmount": "25000000", "decimalAmount": "25" },
        "output": { "asset": { "assetId": "eip155:11155420/erc20:0x5fd8...30D7", "symbol": "USDC", "resolutionStatus": "resolved" }, "rawAmount": "24987500", "decimalAmount": "24.9875" }
      },
      "amountUsd": 25.0,
      "lpName": "lp-atlas",
      "status": "settled",
      "settlementStatus": "settled",
      "lifecycleStatus": { "flowKind": "instant", "primary": { "key": "settled", "label": "Settled", "tone": "positive" }, "isTerminal": true, "rank": 90, "rawStatus": "settled" },
      "executionPrice": { "value": "0.9995", "baseSymbol": "USDC", "quoteSymbol": "USDC", "source": "stored_quote_price" },
      "slippageBps": 5
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 5
}
```

| Field                        | Type            | Description                                                                     |
| ---------------------------- | --------------- | ------------------------------------------------------------------------------- |
| `items`                      | array           | Trades in this page                                                             |
| `items[].orderId`            | string          | Order id - the trade's key for detail, timeline, and evidence lookups           |
| `items[].createdAt`          | string          | When the order was created (RFC 3339)                                           |
| `items[].member`             | object or null  | Who initiated the trade - present for admin/owner callers only                  |
| `items[].sourceChain`        | string          | Source chain                                                                    |
| `items[].destChain`          | string          | Destination chain                                                               |
| `items[].route`              | object          | Input and output legs with asset identity and raw/decimal amounts               |
| `items[].amountUsd`          | number          | Trade notional in USD                                                           |
| `items[].lpName`             | string          | Display name of the LP or provider that filled the trade                        |
| `items[].lpSource`           | string          | How the LP reached your workspace - `Direct`, `via <broker>`, ...               |
| `items[].routingPathLabel`   | string          | Human-readable routing label                                                    |
| `items[].routingPath`        | object or null  | `{ "type": "direct" }` or `{ "type": "via_broker", ... }`                       |
| `items[].orderKind`          | string          | Route-aware order kind (`cctp-v0`, `fx-v0`, ...) - omitted for non-route orders |
| `items[].status`             | string          | Canonical order lifecycle status                                                |
| `items[].settlementStatus`   | string          | Coarse settlement bucket - what the `status` filter matches against             |
| `items[].lifecycleStatus`    | object          | Display-ready lifecycle steps (primary/execution/settlement/withdrawal)         |
| `items[].deferredSettlement` | object or null  | Deferred settlement/withdrawal tracking, when applicable                        |
| `items[].settlementSpeedMs`  | integer or null | Milliseconds from creation to settlement                                        |
| `items[].executionPrice`     | object          | Execution price with base/quote symbols and its source                          |
| `items[].slippageBps`        | integer or null | Realized slippage in basis points                                               |
| `total`                      | integer         | Total trades matching the filters                                               |
| `offset`                     | integer         | Offset this page starts at                                                      |
| `limit`                      | integer         | Effective page size                                                             |

### Slicing a time window

`dateFrom` and `dateTo` bound the result set:

<Warning>
  Send times as **RFC 3339 strings** - `2026-06-20T00:00:00Z` style. Epoch integers don't silently no-op here; they bounce with a validation error, which is the kinder failure.
</Warning>

```python theme={null} theme={null}
from datetime import datetime, timedelta, timezone

import httpx

now = datetime.now(timezone.utc)
month_ago = now - timedelta(days=30)

resp = httpx.get(
    f"https://api.tetrafi.io/api/v1/workspaces/{WS}/trades",
    params={"dateFrom": month_ago.isoformat(), "dateTo": now.isoformat(), "limit": 100},
    headers=headers,
)
print(f'Fetched {len(resp.json().get("items", []))} trades in last 30 days')
```

### Pagination

Pagination is offset-based: step `offset` forward by `limit` until you've covered `total`:

```python theme={null} theme={null}
import httpx

all_trades = []
offset = 0
limit = 100

while True:
    resp = httpx.get(
        f"https://api.tetrafi.io/api/v1/workspaces/{WS}/trades",
        params={"limit": limit, "offset": offset},
        headers=headers,
    )
    data = resp.json()
    all_trades.extend(data.get("items", []))

    offset += data.get("limit", limit)
    if offset >= data.get("total", 0):
        break

print(f"Fetched {len(all_trades)} trades")
```

## 2. Drill into a single trade

Fetch one trade's full dossier - trade details, on-chain settlement transactions, and LP info. Trades are keyed by **order id**, not transaction hash; the settlement transaction hashes live inside the detail's `settlement` section.

```
GET /api/v1/workspaces/{id}/trades/{orderId}
```

| Parameter | Required | Type   | Description                        |
| --------- | -------- | ------ | ---------------------------------- |
| `orderId` | Yes      | string | The `orderId` from the trades list |

<CodeGroup>
  ```bash bash theme={null} theme={null}
  curl "https://api.tetrafi.io/api/v1/workspaces/ws_123/trades/ord_01J49..." \
    -H "X-API-Key: tfk_live_..."
  ```

  ```python python theme={null} theme={null}
  import httpx

  order_id = "ord_01J49..."
  resp = httpx.get(
      f"https://api.tetrafi.io/api/v1/workspaces/{WS}/trades/{order_id}",
      headers=headers,
  )
  detail = resp.json()

  trade = detail["trade"]
  settlement = detail["settlement"]
  print(f'{trade["sourceChain"]} -> {trade["destChain"]}  ${trade["amountUsd"]:.2f}')
  print(f'Status: {trade["status"]}  Settlement: {settlement["status"]}')
  ```
</CodeGroup>

The detail response groups the record into sections: `trade` (the list fields plus fill time and slippage tolerance), `settlement` (per-stage transaction references), `lp`, and - for admin/owner callers - compliance, Travel Rule, proof, intent, and fee sections.

### Errors

| Code | Detail            | Reason                                 |
| ---- | ----------------- | -------------------------------------- |
| 401  | `AUTH_REQUIRED`   | Missing or invalid credential          |
| 404  | `Trade not found` | No such order in this workspace        |
| 422  | Validation error  | Malformed timestamp or query parameter |