Quickstart

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

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); scoping happens on its own.

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)

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

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", "")})'
    )

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.

{
  "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:

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.

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:

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

curl "https://api.tetrafi.io/api/v1/workspaces/ws_123/trades/ord_01J49..." \
  -H "X-API-Key: tfk_live_..."

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"]}')

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

Introduction

Core Concepts

RFQ API

TetraFi propAMM (RFS)

Router API

Price API

Trade History API

1. List your workspace’s trades

Reading What Comes Back

Slicing a time window

2. Drill into a single trade

Errors

​1. List your workspace’s trades

​Reading What Comes Back

​Slicing a time window

​Pagination

​2. Drill into a single trade

​Errors

1. List your workspace’s trades

Reading What Comes Back

Slicing a time window

Pagination

2. Drill into a single trade

Errors