Trades and settlement

List your workspace’s trades, see how each one settled, and read your venue accounts’ settlement cycles and credit.

Read every trade your workspace placed or made on an exchange account, how it settled, and the settlement cycle and credit behind each venue account.

​

At a glance

Paths are under /api/v1/workspaces/{workspaceId}.

Endpoint	Permission	Result
GET …/trades	Read trades	Orders and exchange-account trades, newest first.
GET …/trades/{tradeId}	Read trades	One trade, with how it ended.
GET …/trades/{tradeId}/settlement and …/settlement/obligations	Read settlements	Your side of one trade’s settlement.
GET …/settlement/plan	Read settlements	What is due across your venue accounts.
GET …/venue-accounts/{venueAccountId}/settlement/…	Read settlements	One account’s movements, obligations, schedules, windows and matches.
GET …/venue-accounts/{venueAccountId}/credit and …/ledger	Treasury read	The account’s credit line and positions.

What each read needs

Your workspaceId comes from GET /api/v1/me; another answers 404 WORKSPACE_NOT_FOUND. Take a venueAccountId from GET …/venue-enablements. Permissions are in Permissions and Before your first trade.

Reads	Key permission	Key owner’s workspace permission
Trade history	Read trades	None; without View compliance records, only its own trades
Settlement plan, trades, windows, obligations, movements, schedules	Read settlements (settlements_read)	View settlements
…/credit	Treasury read	View wallets and View credit
…/ledger	Treasury read	View wallets

Trade history

Every trade, filtered and paged.

Settlement

Windows, obligations and movements.

Credit

Credit line and positions.

​

Trade history

GET /api/v1/workspaces/{workspaceId}/trades lists orders placed through the API or app and trades on your exchange accounts, newest first, for reconciliation and reporting. To follow one order, read its statusUrl (Order status).

​

Read a page

Filter by kind, status, from and to; page with cursor until nextCursor is null.

Fields and parameters

Field	Meaning
tradeId	The trade’s id.
kind	order (placed through TetraFi) or venueTrade (on your exchange account). Show an unknown kind generically.
projection	The view read through: workspace for an API key.
createdAt	When the trade was placed.

The page also carries total (rows matching your filters), limit and nextCursor.

Parameter	Use
kind	all, order or venueTrade.
status	Rows in this status.
from, to	RFC 3339 times: placed at or after, at or before.
limit	The page size, 25 by default.
cursor	The last nextCursor, same filters, until null.
format=csv	The same rows as CSV.

Request and output

cURL

# The path names your workspace: the workspaceId GET /api/v1/me answers for your key.
workspace=$TETRAFI_WORKSPACE_ID
# GET /api/v1/workspaces/{workspaceId}/trades lists the workspace's trades, newest first. Every row
# has tradeId, kind (order or venueTrade) and projection. Filter with kind, status, from and to;
# follow nextCursor until it is null. coverage lists kinds whose rows could not be read: the page
# is then partial, not shorter.
since=$(date -u -v-30d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%SZ)
page=$(tetrafi GET "/api/v1/workspaces/$workspace/trades?limit=5&from=$since")
jq -c '{total, nextCursor: (.nextCursor != null), coverage, excludedKinds}' <<<"$page" >&2
jq -c '.items[:3][] | {tradeId, kind, projection, createdAt}' <<<"$page" >&2
cursor=$(jq -r '.nextCursor // empty' <<<"$page")
if [[ -n $cursor ]]; then
  next=$(tetrafi GET "/api/v1/workspaces/$workspace/trades?limit=5&from=$since&cursor=$cursor")
  jq -c '{page: 2, rows: (.items | length)}' <<<"$next" >&2
fi

Output on test networks

{"total":628,"nextCursor":true,"coverage":null,"excludedKinds":null}
{"tradeId":"9410e38e-…","kind":"venueTrade","projection":"workspace","createdAt":"2026-11-02T01:36:46.856947Z"}
{"tradeId":"3ba8fe03…","kind":"order","projection":"workspace","createdAt":"2026-11-01T23:51:28Z"}
{"tradeId":"de0a1b4b-…","kind":"venueTrade","projection":"workspace","createdAt":"2026-11-01T22:55:48.448012Z"}
{"page":2,"rows":5}

The page is partial

• coverage lists each kind whose rows could not be read, with its state. The page is partial, not shorter: read again later; the missing rows are not absent.
• excludedKinds lists each kind a filter or sort left out, with the filter it could not apply. Drop that filter to see it.

​

Read one trade

GET /api/v1/workspaces/{workspaceId}/trades/{tradeId} reads one row with its detail; an order’s settlement.status says how it ended.

Settlement fields, request and output

Field	Meaning
settlement.status	pending, settled, failed, refunded or unknown. Treat an unknown value as unknown.
settlement.failureReason	Why, when status is failed or refunded; else null. Show it to people; branch on status, never this text.

cURL

# GET …/trades/{tradeId} reads one trade through the same view. An order's settlement says how it
# ended: status pending, settled, failed, refunded or unknown, and failureReason, a sentence
# saying why, when it failed or was refunded.
failed=$(tetrafi GET "/api/v1/workspaces/$workspace/trades?kind=order&status=failed&limit=1")
trade_id=$(jq -r '.items[0].tradeId // empty' <<<"$failed")
if [[ -z $trade_id ]]; then
  trade_id=$(tetrafi GET "/api/v1/workspaces/$workspace/trades?kind=order&limit=1" | jq -r '.items[0].tradeId // empty')
fi
if [[ -n $trade_id ]]; then
  trade=$(tetrafi GET "/api/v1/workspaces/$workspace/trades/$trade_id")
  jq -c '{tradeId, kind, settlement: (.settlement | if . == null then null else {status, failureReason} end)}' <<<"$trade" >&2
fi

Output on test networks

{"tradeId":"673828c6…","kind":"order","settlement":{"status":"failed","failureReason":"…"}}

​

Settlement

On some venue accounts, the liquidity provider (LP) and your workspace net what each owes over a settlement window, then settle the result. No read creates a transfer, reservation, approval or instruction to the LP.

Every settlement read

You want to know	Read
What is due across your venue accounts	GET …/workspaces/{workspaceId}/settlement/plan
How one trade settled	GET …/trades/{tradeId}/settlement and …/trades/{tradeId}/settlement/obligations
An account’s settlement windows and statements	GET …/venue-accounts/{venueAccountId}/settlement/windows, …/windows/{windowId} and …/windows/{windowId}/matches
What each side owes, and by when	GET …/venue-accounts/{venueAccountId}/settlement/obligations and …/obligations/{obligationId}
The deposits and withdrawals that settled them	GET …/venue-accounts/{venueAccountId}/settlement/movements and …/movements/{movementId}
The LP’s settlement schedule	GET …/venue-accounts/{venueAccountId}/settlement/schedules
The account’s credit line and positions	GET …/venue-accounts/{venueAccountId}/credit and …/ledger

The settlement plan

GET /api/v1/workspaces/{workspaceId}/settlement/plan is a snapshot of what is due:

• up to horizonDays ahead, paged with cursor and limit;
• a summary per account, with its upcoming windows;
• an unknown deadline stays unknown, never a guess.

A source that could not be read is listed in failedReads, with complete: false: the plan is partial, not “nothing due”.

One trade's settlement

• GET …/trades/{tradeId}/settlement: your side of the trade, with its lifecycle stages, transactions and the LP’s response.
• …/settlement/obligations: the obligations referencing it, each with venue account, window and state.

Take tradeId from the trade history. The LP’s view is a signed-in member read in the app.

Windows, obligations, movements and schedules

Object	What it is	How to read it
Window	One settlement period. Once its snapshot is ready, it carries an indicative statement: positions, snapshot prices (an unavailable one names its stage and reason) and the minimum-settlement decision. An LP-issued window adds the LP’s statement.	Newest first; filter by state, page with cursor. …/windows/{windowId}/matches: movements matched to its obligations, oldest first.
Obligation	What you and the LP owe each other, with status, deadline and origin.	Filter by windowId or tradeId. The detail lists its matched movements.
Movement	A deposit or withdrawal that settles obligations, with its finality and how it matched.	As recorded by TetraFi; lastSuccessfulReadAt and observationState say how current. A key never starts a read from the LP.
Schedule	The LP’s published schedules.	The one in effect, with its minimum settlement, and the next window.

​

Credit and the ledger

…/credit and …/ledger read the account’s credit line and signed positions from the last recorded observation. An unreadable component is unavailable with its code, never zero; readable positions still return when credit does not.

What each read answers

Read	Answers	How current
GET …/venue-accounts/{venueAccountId}/credit	The provider’s reported line (limit, used, available and overrun), the agreed facility, TetraFi’s open credit commitments and the signed positions, each with its observation time.	The last recorded ledger observation; no provider call.
GET …/venue-accounts/{venueAccountId}/ledger	The signed positions and credit line.	For a key, the last recorded observation (source: "recorded"), dated observedAt, stale: true past an hour. A key never starts a venue read.

​

Refusals

Trade history

Code	Status	What to do
INVALID_REQUEST	400	An unknown parameter or value, or an unappliable filter. The answer names the parameter.
WORKSPACE_NOT_FOUND	404	The path’s workspace is not your key’s.
TRADE_PROJECTION_UNAVAILABLE	503	Trade history is unreadable on this deployment right now. Retry later.

A 404 on one trade means the tradeId is unknown, or belongs to another workspace.

Settlement and credit

Code	Status	What to do
INSUFFICIENT_WORKSPACE_PERMISSION	403	The key’s owner lacks the workspace permission. Ask a workspace admin.
LEDGER_ACCOUNT_FORBIDDEN	403	The same, on …/ledger.
VENUE_ACCOUNT_NOT_FOUND	404	No venue account with that id.
WORKSPACE_NOT_FOUND	404	The path’s workspace is not your key’s.
LEDGER_NOT_OBSERVED	409	No ledger observation yet. Read later, or open the account in the app, which reads the venue live.
LEDGER_UNSUPPORTED	409	The venue does not report a ledger.
LEDGER_SETUP_MISSING	409	No current key, or the connection needs setup. A member with Manage credentials adds or verifies the key; read again.
VENUE_ACCOUNT_LEDGER_PENDING	409	Setup unfinished. A member with Manage credentials finishes it (the finishVenueAccountSetup fix); read again.
VENUE_ACCOUNT_FUNDS_IN_WALLETS	409	A wallet-based venue keeps funds in linked wallets: read GET …/balances.

Every other code is in Error codes.

Run the full script

Pages your trade history and reads one trade.

​

Next

Balances and fees

What each account holds, and what you pay.

Order status

Follow one order.