List trades

The one trade history. Projections: scope=workspace (default) reads the workspace’s taker orders and venue trades; a caller not allowed to view the workspace’s compliance records 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 (a member session allowed to view client compliance records). perspective=maker reads an LP workspace’s fills with pseudonymised counterparties (a member session allowed to view settlements); with settlementStage or minAgeSeconds, its unsettled orders by stage (a member session allowed to 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. Required API-key scope: trades_read; CSV is a member session only.

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

List trades

cURL

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

200

{
  "items": [
    {
      "projection": "mine",
      "kind": "order",
      "createdAt": "2023-11-07T05:31:56Z",
      "executionPrice": {
        "source": "storedQuotePrice",
        "baseSymbol": "<string>",
        "quoteSymbol": "<string>",
        "value": "<string>"
      },
      "lifecycleStatus": {
        "bucket": "inProgress",
        "flowKind": "instant",
        "isTerminal": true,
        "primary": {
          "key": "created",
          "label": "<string>",
          "tone": "<string>"
        },
        "rank": 1,
        "rawStatus": "created",
        "execution": {
          "key": "created",
          "label": "<string>",
          "tone": "<string>"
        },
        "rawDeferredStatus": "<string>",
        "settlement": {
          "key": "created",
          "label": "<string>",
          "tone": "<string>"
        },
        "withdrawal": {
          "key": "created",
          "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": "created",
      "submittedByYou": true,
      "tradeId": "<string>",
      "actionRequired": {
        "code": "<string>",
        "message": "<string>"
      },
      "amountUsd": "<string>",
      "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": "measured",
      "failureReason": "<string>",
      "linkedWalletId": "<string>",
      "lpVenueId": "<string>",
      "makerAttribution": {
        "displayName": "<string>",
        "executionTypeId": "<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"
    }
  ],
  "included": {},
  "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>",
    "kind": "fills",
    "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.

Scopes

trades_read · bearer_auth

trades_read · api_key

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 permission to view its clients' compliance records; 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 permission to 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) or an LP workspace UUID (orders only), the client workspace (umbrella) or the taker (maker).

venueId · string

Exact execution-type identity: the maker of an order (taker), or one of the LP's own venues (maker).

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

sort · string

field (ascending) or -field (descending). Every projection: createdAt. Taker: amountUsd, status, corridor, counterparty, member (workspace scope), orderId, settlementSpeedMs. Umbrella: amountUsd. Maker: status, orderId. A cursor pages only the order it was returned for

fields · string

Comma-separated top-level fields of each row to return; tradeId, kind, projection, id and status are always kept. JSON only

include · string

Related objects to expand into included, comma-separated: settlement, each listed trade's settlement by tradeId, as GET …/trades/{tradeId}/settlement answers this caller in the row's perspective, or null with that read's refusal. Unknown relation 400 INCLUDE_UNKNOWN, malformed or repeated 400 INCLUDE_INVALID; not on a signed API-key request or with format=csv

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 taker trade with tradeId, kind and projection, and the fields of its order or venue trade. Session-only maker, settlement and umbrella projections are not available to a programmatic credential.

Option 1

Option 2

Option 3

Option 4

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

included · null | object

With include: each relation's object per listed trade, keyed by tradeId, as that relation's own GET answers this caller, or null with its refusal.

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