GET /api/v1/workspaces/{workspaceId}/trades

The one trade history. Projections: scope=workspace (default) reads the workspace’s taker orders and venue trades; a member without view_compliance reads only their own, whatever the scope. scope=mine reads the caller’s own (a member session only). scope=umbrella reads a broker’s clients’ orders with each client category’s field visibility (view_umbrella_compliance). perspective=maker reads an LP workspace’s fills with pseudonymised counterparties (view_settlements); with settlementStage or minAgeSeconds, its unsettled orders by stage (view_bilateral_documents). The default perspective is taker in every workspace. Every row carries tradeId, kind (order or venueTrade) and projection. Page with limit and cursor; format=csv returns the same filtered rows. Accepts a member session or an API key with trades_read; CSV is a member session only.

GET /api/v1/workspaces/{workspaceId}/trades

GET /api/v1/workspaces/{workspaceId}/trades

cURL

curl --request GET \
  --url https://api.tetrafi.io/api/v1/workspaces/{workspaceId}/trades \
  --header 'Authorization: Bearer <token>'

200

{
  "items": [
    {
      "createdAt": "2023-11-07T05:31:56Z",
      "executionPrice": {
        "source": "stored_quote_price",
        "baseSymbol": "<string>",
        "quoteSymbol": "<string>",
        "value": "<string>"
      },
      "lifecycleStatus": {
        "bucket": "inProgress",
        "flowKind": "<string>",
        "isTerminal": true,
        "primary": {
          "key": "<string>",
          "label": "<string>",
          "tone": "<string>"
        },
        "rank": 1,
        "rawStatus": "<string>",
        "execution": {
          "key": "<string>",
          "label": "<string>",
          "tone": "<string>"
        },
        "rawDeferredStatus": "<string>",
        "settlement": {
          "key": "<string>",
          "label": "<string>",
          "tone": "<string>"
        },
        "withdrawal": {
          "key": "<string>",
          "label": "<string>",
          "tone": "<string>"
        }
      },
      "lpName": "<string>",
      "lpSource": "<string>",
      "orderId": "<string>",
      "route": {
        "buy": {
          "asset": {
            "assetId": "<string>",
            "resolutionStatus": "resolved",
            "symbol": "<string>",
            "address": "<string>",
            "chainId": 1,
            "chainRef": "<string>",
            "decimals": 1,
            "name": "<string>"
          },
          "decimalAmount": "<string>",
          "rawAmount": "<string>",
          "unresolved": "assetNotInRegistry"
        },
        "sell": {
          "asset": {
            "assetId": "<string>",
            "resolutionStatus": "resolved",
            "symbol": "<string>",
            "address": "<string>",
            "chainId": 1,
            "chainRef": "<string>",
            "decimals": 1,
            "name": "<string>"
          },
          "decimalAmount": "<string>",
          "rawAmount": "<string>",
          "unresolved": "assetNotInRegistry"
        }
      },
      "routingPathLabel": "<string>",
      "settlementStatus": "<string>",
      "status": "<string>",
      "submittedByYou": true,
      "kind": "order",
      "projection": "mine",
      "tradeId": "<string>",
      "actionRequired": {
        "code": "<string>",
        "message": "<string>"
      },
      "amountUsd": 123,
      "apiKey": {
        "keyId": "<string>",
        "name": "<string>"
      },
      "channel": "ui",
      "custodyVaultAddress": "<string>",
      "deferredSettlement": {
        "autoWithdraw": true,
        "stage": "<string>",
        "estimatedSettlementAvailableAt": "2023-11-07T05:31:56Z",
        "executedAt": "2023-11-07T05:31:56Z",
        "settlementWindowHours": 1,
        "withdrawalStatus": "<string>",
        "withdrawalTrackingId": "<string>",
        "withdrawalTxHash": "<string>"
      },
      "deliveredBuyProvenance": "<string>",
      "failureReason": "<string>",
      "linkedWalletId": "<string>",
      "lpVenueId": "<string>",
      "nextAction": {
        "kind": "payoutFeeRose",
        "legId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "nextActor": "taker",
      "orderKind": "<string>",
      "routingPath": {
        "type": "direct"
      },
      "settlementSpeedMs": 1,
      "slippageBps": 123
    }
  ],
  "limit": 1,
  "total": 1,
  "coverage": [
    {
      "kind": "order",
      "state": "unavailable"
    }
  ],
  "excludedKinds": [
    {
      "filter": "<string>",
      "kind": "order"
    }
  ],
  "latestTradeAt": "2023-11-07T05:31:56Z",
  "makerContext": {
    "ownedSolvers": [
      {
        "solverId": "<string>",
        "status": "registered",
        "name": "<string>",
        "retiredAt": "2023-11-07T05:31:56Z"
      }
    ],
    "selectedBrokerId": "<string>",
    "selectedCohort": "<string>",
    "selectedSolverId": "<string>",
    "accountSummary": {
      "amountUnit": "<string>",
      "candidateLimit": 1,
      "filledRequestCount": 1,
      "groups": [
        {
          "executionTypeId": "<string>",
          "filledRequestCount": 1,
          "inputAmount": "<string>",
          "inputAsset": "<string>",
          "outputAmount": "<string>",
          "outputAsset": "<string>",
          "providerSite": "<string>"
        }
      ],
      "source": "protocol"
    },
    "selectedAccountFilter": {
      "executionTypeId": "<string>",
      "inputAsset": "<string>",
      "outputAsset": "<string>",
      "providerSite": "<string>"
    },
    "selectedRiskScope": {
      "asOf": "<string>",
      "counterparty": "<string>",
      "windowSeconds": 123
    }
  },
  "nextCursor": "<string>",
  "scope": "workspace"
}

Authorizations

bearer_authapi_key

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Workspace-Id · string<uuid>

The workspace the request acts in. An API key bound to a workspace implies it: omit the header, or send that same id (another id answers 403 WORKSPACE_SCOPE_MISMATCH). A member session must send it (400 MISSING_WORKSPACE without it).

Path Parameters

workspaceId · string · required

Workspace ID

Query Parameters

scope · enum<string>

mine, workspace or umbrella. Default: workspace. umbrella needs a broker workspace and view_umbrella_compliance; mine needs a member session. Whose rows the list reads.

Available options: mine, workspace, umbrella

perspective · enum<string>

taker (default, in every workspace) or maker. maker needs an LP workspace and view_settlements. Which side of the trade the workspace was on.

Available options: taker, maker

kind · enum<string>

all, order or venueTrade. Default: all for taker and umbrella; for maker the fills default (on-chain orders); umbrella has orders only. Explicit population selection, not an unsupported-filter exclusion.

Available options: all, order, venueTrade

status · string

Settlement status filter, as the projection names it.

counterpartyId · string

Counterparty: the LP's catalogue venue id, the row's lpVenueId (taker; a venue trade matches its execution type's venue), the client workspace (umbrella) or the taker (maker).

venueId · string

One of the LP's own venues, by its id (maker only).

client · string

The member or client who placed the order: member (taker), user id (umbrella), entity (maker).

settlementStage · string

Settlement stage of an unsettled order (maker only).

minAgeSeconds · integer<int64>

Only orders at least this many seconds old (maker only, with settlementStage).

from · string<date-time>

Placed at or after this RFC 3339 instant (umbrella: a UTC midnight).

to · string<date-time>

Placed at or before this RFC 3339 instant (umbrella: a UTC midnight).

limit · integer<int32>

Page size; the projection's own bounds apply (default 25).

Required range: x >= 0

cursor · string

The nextCursor of the previous page.

format · enum<string>

json (default) or csv. csv returns the projection's export of the same filters. The representation of the list.

Available options: json, csv

lifecycle · string

Taker: comma-separated lifecycle buckets (inProgress, completed, failed, refunded, unknown). Maker: the fills lifecycle filter

nextActor · string

Taker: taker, support, counterparty or none

asset · string

Taker: either side's display asset symbol (case-insensitive)

corridor · string

Corridor (source-dest)

walletId · string

Taker: linked wallet id

address · string

Taker: wallet address (custody vault or linked wallet)

routingPath · string

The row's routingPath type: direct or via_broker

amountMin · number<double>

Minimum USD notional

amountMax · number<double>

Maximum USD notional

sortBy · string

Field to sort by, as the projection names it

sortDir · string

Taker: asc or desc

actionRequired · boolean

Taker: only orders whose nextAction is present

Response

200

application/json

One page of trades; with format=csv, the projection's CSV of the same filters

One page of the trade history.

items · object[] · required

One trade in the trade history.

The core (tradeId, kind, projection) is on every row. Taker rows carry the order or venue-trade fields at the top level, exactly as the taker list has always returned them; umbrella is set only on umbrella rows and maker only on maker rows.

Option 1

Option 2

Option 3

Show child attributes

limit · integer<int32> · required

The page size applied.

Required range: x >= 0

total · integer<int64> · required

Rows matching the filters in this projection.

Required range: x >= 0

coverage · object[]

Taker projections: kinds whose rows could not be read; the list shows the rest.

Show child attributes

excludedKinds · object[]

Taker projections: kinds a filter or sort left out, each with the parameter it could not apply.

Show child attributes

latestTradeAt · string<date-time> | null

Newest createdAt the caller may see in this projection, ignoring every filter.

makerContext · object

Maker projections only: what the fills or settlement-queue read returned about the page beyond its rows, unchanged. Absent for every taker projection.

Option 1

Option 2

Show child attributes

nextCursor · string | null

Pass as cursor for the next page; null on the last page.

scope · null | enum<string>

Taker projections: whose orders the list holds (every workspace order, or the caller's own).

Available options: workspace, own