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

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

```mermaid theme={null}
flowchart LR
  T[Trade] --> O[Obligation]
  O --> W[Window]
  M[Movement] -- matched --> O
```

> [accordion] 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`](https://tetrafi.mintlify.site/trade/balances#list-your-exchange-accounts). Permissions are in [Permissions](https://tetrafi.mintlify.site/authentication.md#permissions) and [Before your first trade](https://tetrafi.mintlify.site/before-you-trade.md).
>
> | 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 |

> [card] [Trade history](#trade-history)
>
> Every trade, filtered and paged.

> [card] [Settlement](#settlement)
>
> Windows, obligations and movements.

> [card] [Credit](#credit-and-the-ledger)
>
> 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](https://tetrafi.mintlify.site/trade/order-status.md)).

### Read a page

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

> [accordion] 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. |

> [accordion] Request and output
>
> ```bash cURL theme={null}
> # 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
> ```
>
> ```json Output on test networks theme={null}
> {"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}
> ```

> [accordion] 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.

> [accordion] 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. |
>
> ```bash cURL theme={null}
> # 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
> ```
>
> ```json Output on test networks theme={null}
> {"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.

> [accordion] 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` |

> [accordion] 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".

> [accordion] 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](#trade-history). The LP's view is a signed-in member read in the app.

> [accordion] 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.

> [accordion] 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

> [accordion] 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.

> [accordion] Settlement and credit
>
> | Code | Status | What to do |
> | - | - | - |
> | `INSUFFICIENT_WORKSPACE_PERMISSION` | 403 | The key's owner lacks the [workspace permission](#at-a-glance). 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](https://tetrafi.mintlify.site/reference/error-codes.md).

> [card] [Run the full script](https://github.com/TetraFi/docs/blob/main/samples/http/trades.sh)
>
> Pages your trade history and reads one trade.

## Next

> [card] [Balances and fees](https://tetrafi.mintlify.site/trade/balances.md)
>
> What each account holds, and what you pay.

> [card] [Order status](https://tetrafi.mintlify.site/trade/order-status.md)
>
> Follow one order.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.