Skip to main content
GET
GET /api/v1/workspaces/{workspaceId}/trades/{tradeId}

Authorizations

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

tradeId
string
required

The trade's tradeId: an order id, or a venue trade's operation id

Query Parameters

scope
enum<string>

mine, workspace (default) or umbrella, as on the list Whose rows the list reads.

Available options:
mine,
workspace,
umbrella
perspective
enum<string>

taker (default) or maker, as on the list Which side of the trade the workspace was on.

Available options:
taker,
maker
venueId
string

Maker: the LP's own venue that filled it

flow
string

Maker: protocol, venueAccount or all

Response

The trade, with tradeId, kind and projection

One trade, read through the same projection as the list.

lp
object
required

Section D: LP / counterparty information, including its compliance posture.

For a KYB'd liquidity provider the compliance fields carry the LP's jurisdiction, KYB status, and regulatory licences — the "who is the other side and are they authorised" a compliance officer needs. Router/bridge routes settle through a protocol (CCTP, Relay, …), not a VASP counterparty: those report counterparty_type = "protocol" with no jurisdiction/licences, which is itself the compliance-relevant fact (no VASP-to-VASP Travel Rule message is owed).

settlement
object
required

Section B: On-chain settlement data.

Models the four-step lifecycle of an intent on-chain: submit_tx (user deposit / intent creation), fill_tx (solver fill on destination chain), proof_tx (cross-chain proof submission), finalise_tx (claim/settle on origin). Oracle + settlement_stage describe the proof-relay layer.

trade
object
required

Section A: Trade details.

buy
object
required

What the trade buys: its asset and, when recorded, the least it must receive from its consented bounds.

connectionId
string
required
createdAt
string<date-time>
required
executionStatus
enum<string>
required

A venue trade's execution status, in camelCase like the order status (outcomeUnknown).

New values may be added; treat unknown values as other.

Available options:
notSubmitted,
dispatching,
outcomeUnknown,
filled,
unfilled,
needsReview
executionTypeId
string
required

The execution type (compiled spec id), not the catalogue Venue.

lifecycleStatus
object
required

The same lifecycle shape an order row carries; needsReview is not final.

operationId
string
required
providerSite
string
required
sell
object
required

What the trade sells: its asset and, when recorded, the most it may spend from its consented bounds.

submittedByYou
boolean
required
venueAccountName
string
required

The workspace's venue account it went through, titled by its catalogue Venue ("Keyrock account"), never by the execution type ("Keyrock OTC"); an on-chain venue is never an account and reads as itself ("Circle StableFX").

venueName
string
required

The venue's name, for display.

kind
enum<string>
required

The kinds the one trade history lists.

New values may be added; treat unknown values as other.

Available options:
order,
venueTrade
projection
enum<string>
required

Which view of trades answers the request: the caller's own, the workspace's, a broker's umbrella, an LP's fills, or an LP's unsettled orders.

New values may be added; treat unknown values as other.

Available options:
mine,
workspace,
umbrella,
maker,
settlement
tradeId
string
required
fees
object

Fee breakdown: gas, protocol fee, solver fee, relayer tips. Absent when the order predates fee capture.

legs
object[] | null

Uniform per-leg execution model for multi-leg route orders; absent for single-leg escrow / deferred orders. Mirrors OrderResponse.legs.

orderKind
string | null

Canonical, route-aware order kind (cctp-v0 / composite-v0 / fx-v0 / escrow-v0 / …). Mirrors OrderResponse.orderKind.

substatus
string | null

Finer-grained state within the coarse status (route routeStatus, etc.).

substatusMessage
string | null

Human-readable elaboration of substatus — a Circle StableFX status line, or the reason a parked/refunded/recovered order is in that state. Mirrors OrderResponse.substatusMessage.

apiKey
null | object
executionPrice
string | null

Legacy confirmed output per input (buy asset / sell asset), computed with Decimal; null when unread. executionPriceUnit states its unit; prefer statedExecutionPrice for display.

executionPriceUnit
null | object

Unit of a price: quoteAsset / baseAsset means one base asset costs this many quote assets.

feesPaid
string | null

What a confirmed same-asset fill (a bridge) cost the taker: spent minus received, the venue's protocol and forwarding fees, in the sell asset. Absent unless confirmed and positive.

financials
null | object

The trade's recorded money terms and payment legs, from the same records as the order read; history never re-derives a fee or minimum.

inputSpent
string | null

What the venue debited and credited, once its outcome is recorded.

notSentReason
null | enum<string>

Why a not_sent outcome was not sent, as the dispatch's notSentReason.

Available options:
QUOTE_RECONFIRMATION_REQUIRED,
VENUE_ACCEPT_ADMISSION_REFUSED,
VENUE_SESSION_ACQUIRE_TIMEOUT,
VENUE_GRID_CHANGED,
VENUE_GRID_UNREADABLE,
VENUE_REFUSED_BEFORE_ACCEPTANCE,
LP_TRADING_REFUSED_UNSENT,
COMPLIANCE_AUDIT_UNRECORDED,
ON_CHAIN_UNSENT,
BOOK_SELL_LIMIT_UNREPRESENTABLE,
VENUE_DISPATCH_AUTHORITY_UNAVAILABLE,
BOOK_PLACEMENT_PRICE_UNRECORDED_UNSENT,
VENUE_ORDER_ABSENT_PAST_HORIZON,
VENUE_REQUEST_REFUSED_UNSENT,
NOT_SENT_UNCLASSIFIED
outcomeCode
string | null

Why the trade ended as it did, as its dispatch records it (the order page's dispatch.outcomeCode): the history row names a no-fill's reason from it. Absent until an outcome is recorded.

outputReceived
string | null
pair
string | null

The recorded market pair; absent stays absent, never inferred from asset order.

placedBy
object

Who placed the trade: the API key by label, else the member where this reader may see their name. Absent otherwise.

statedExecutionPrice
null | object

QuoteCurrencyPriority market convention, with explicit base/quote and fallback basis.

tetrafiFee
string | null

Gross TetraFi fee (list rate, before incentives) from the Basic billing ledger, in tetrafiFeeAsset; absent until accrued.

tetrafiFeeAsset
string | null