> ## 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. # 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. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/workspaces/{workspaceId}/trades openapi: 3.1.0 info: description: >- TetraFi is an API for institutional trading across on-chain and off-chain venues: discover assets, request quotes, place an order by quote id and read its status. API keys sign every request. Asset-pair quotes: every tagged union is tagged by `kind`; only the outcome of `/prices` rows and `sources[]` entries is tagged by `status`. title: TetraFi API version: 1.0.0-beta.1 servers: - url: https://api.tetrafi.io security: - api_key: [] tags: - description: Request price quotes from multiple solvers for cross-chain transactions name: quotes - description: Submit, track, and manage cross-chain orders name: orders - description: Canonical trading pairs and aggregator metadata name: trading - description: >- Authentication — registration, login, SIWE, OAuth, sessions, login activity name: auth - description: Workspace CRUD, settings, members, and team management name: workspaces - description: >- Webhook management — CRUD, secret rotation, test delivery, delivery history name: webhooks paths: /api/v1/workspaces/{workspaceId}/trades: get: tags: - trades summary: GET /api/v1/workspaces/{workspaceId}/trades description: >- 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. operationId: list_workspace_trades parameters: - $ref: '#/components/parameters/WorkspaceId' - description: Workspace ID in: path name: workspaceId required: true schema: type: string - description: >- mine, workspace or umbrella. Default: workspace. umbrella needs a broker workspace and view_umbrella_compliance; mine needs a member session. in: query name: scope required: false schema: $ref: '#/components/schemas/TradeScope' - description: >- taker (default, in every workspace) or maker. maker needs an LP workspace and view_settlements. in: query name: perspective required: false schema: $ref: '#/components/schemas/TradePerspective' - description: >- all, order or venueTrade. Default: all for taker and umbrella; for maker the fills default (on-chain orders); umbrella has orders only. in: query name: kind required: false schema: $ref: '#/components/schemas/TradeKindFilter' - description: Settlement status filter, as the projection names it. in: query name: status required: false schema: type: string - description: >- 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). in: query name: counterpartyId required: false schema: type: string - description: One of the LP's own venues, by its id (maker only). in: query name: venueId required: false schema: type: string - description: >- The member or client who placed the order: member (taker), user id (umbrella), entity (maker). in: query name: client required: false schema: type: string - description: Settlement stage of an unsettled order (maker only). in: query name: settlementStage required: false schema: type: string - description: >- Only orders at least this many seconds old (maker only, with settlementStage). in: query name: minAgeSeconds required: false schema: format: int64 type: integer - description: 'Placed at or after this RFC 3339 instant (umbrella: a UTC midnight).' in: query name: from required: false schema: format: date-time type: string - description: >- Placed at or before this RFC 3339 instant (umbrella: a UTC midnight). in: query name: to required: false schema: format: date-time type: string - description: Page size; the projection's own bounds apply (default 25). in: query name: limit required: false schema: format: int32 minimum: 0 type: integer - description: The nextCursor of the previous page. in: query name: cursor required: false schema: type: string - description: >- json (default) or csv. csv returns the projection's export of the same filters. in: query name: format required: false schema: $ref: '#/components/schemas/TradesFormat' - description: >- Taker: comma-separated lifecycle buckets (inProgress, completed, failed, refunded, unknown). Maker: the fills lifecycle filter in: query name: lifecycle required: false schema: type: string - description: 'Taker: taker, support, counterparty or none' in: query name: nextActor required: false schema: type: string - description: 'Taker: either side''s display asset symbol (case-insensitive)' in: query name: asset required: false schema: type: string - description: Corridor (source-dest) in: query name: corridor required: false schema: type: string - description: 'Taker: linked wallet id' in: query name: walletId required: false schema: type: string - description: 'Taker: wallet address (custody vault or linked wallet)' in: query name: address required: false schema: type: string - description: 'The row''s routingPath type: direct or via_broker' in: query name: routingPath required: false schema: type: string - description: Minimum USD notional in: query name: amountMin required: false schema: format: double type: number - description: Maximum USD notional in: query name: amountMax required: false schema: format: double type: number - description: Field to sort by, as the projection names it in: query name: sortBy required: false schema: type: string - description: 'Taker: asc or desc' in: query name: sortDir required: false schema: type: string - description: 'Taker: only orders whose nextAction is present' in: query name: actionRequired required: false schema: type: boolean responses: '200': content: application/json: schema: $ref: '#/components/schemas/TradeList' text/csv: schema: type: string description: >- One page of trades; with format=csv, the projection's CSV of the same filters headers: x-ratelimit-limit: description: >- Sent only when the request's API key has its own requests-per-minute limit: that limit. Sessions, and keys without their own limit, never receive it. schema: minimum: 0 type: integer x-ratelimit-remaining: description: >- Requests left before this caller is limited: the per-address limit's when that limit counted the request, otherwise the API key's own remaining allowance. Absent when no finite limit counted the request. schema: minimum: 0 type: integer x-ratelimit-reset: description: >- Sent with x-ratelimit-limit, only when the request's API key has its own limit: whole seconds until that allowance is full again. schema: minimum: 0 type: integer x-request-id: description: >- The request's id: the caller's valid `X-Request-Id`, or a generated UUID v4. Quote it when asking for support. schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: >- INVALID_REQUEST naming the parameter in field: an unknown parameter or value, a filter the projection cannot apply, a cursor from another list, or two names for one filter. VALIDATION_ERROR: a malformed filter headers: x-ratelimit-limit: description: >- Sent only when the request's API key has its own requests-per-minute limit: that limit. Sessions, and keys without their own limit, never receive it. schema: minimum: 0 type: integer x-ratelimit-remaining: description: >- Requests left before this caller is limited: the per-address limit's when that limit counted the request, otherwise the API key's own remaining allowance. Absent when no finite limit counted the request. schema: minimum: 0 type: integer x-ratelimit-reset: description: >- Sent with x-ratelimit-limit, only when the request's API key has its own limit: whole seconds until that allowance is full again. schema: minimum: 0 type: integer x-request-id: description: >- The request's id: the caller's valid `X-Request-Id`, or a generated UUID v4. Quote it when asking for support. schema: type: string '401': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Authentication is missing or invalid. headers: WWW-Authenticate: description: >- Sent when the request presented a bearer token and it was refused: `Bearer error="invalid_token"` (RFC 6750 section 3). Exchange a new token. A refused API key carries no challenge. schema: type: string x-ratelimit-limit: description: >- Sent only when the request's API key has its own requests-per-minute limit: that limit. Sessions, and keys without their own limit, never receive it. schema: minimum: 0 type: integer x-ratelimit-remaining: description: >- Requests left before this caller is limited: the per-address limit's when that limit counted the request, otherwise the API key's own remaining allowance. Absent when no finite limit counted the request. schema: minimum: 0 type: integer x-ratelimit-reset: description: >- Sent with x-ratelimit-limit, only when the request's API key has its own limit: whole seconds until that allowance is full again. schema: minimum: 0 type: integer x-request-id: description: >- The request's id: the caller's valid `X-Request-Id`, or a generated UUID v4. Quote it when asking for support. schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: >- scope=mine with an API key; umbrella without view_umbrella_compliance; maker without an LP workspace and view_settlements; the umbrella or maker projection with an API key (JWT_REQUIRED); an API key without trades_read headers: x-ratelimit-limit: description: >- Sent only when the request's API key has its own requests-per-minute limit: that limit. Sessions, and keys without their own limit, never receive it. schema: minimum: 0 type: integer x-ratelimit-remaining: description: >- Requests left before this caller is limited: the per-address limit's when that limit counted the request, otherwise the API key's own remaining allowance. Absent when no finite limit counted the request. schema: minimum: 0 type: integer x-ratelimit-reset: description: >- Sent with x-ratelimit-limit, only when the request's API key has its own limit: whole seconds until that allowance is full again. schema: minimum: 0 type: integer x-request-id: description: >- The request's id: the caller's valid `X-Request-Id`, or a generated UUID v4. Quote it when asking for support. schema: type: string '404': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: >- WORKSPACE_NOT_FOUND: the path names a workspace other than the caller's headers: x-ratelimit-limit: description: >- Sent only when the request's API key has its own requests-per-minute limit: that limit. Sessions, and keys without their own limit, never receive it. schema: minimum: 0 type: integer x-ratelimit-remaining: description: >- Requests left before this caller is limited: the per-address limit's when that limit counted the request, otherwise the API key's own remaining allowance. Absent when no finite limit counted the request. schema: minimum: 0 type: integer x-ratelimit-reset: description: >- Sent with x-ratelimit-limit, only when the request's API key has its own limit: whole seconds until that allowance is full again. schema: minimum: 0 type: integer x-request-id: description: >- The request's id: the caller's valid `X-Request-Id`, or a generated UUID v4. Quote it when asking for support. schema: type: string '408': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: The request timed out before a response was ready. headers: x-ratelimit-limit: description: >- Sent only when the request's API key has its own requests-per-minute limit: that limit. Sessions, and keys without their own limit, never receive it. schema: minimum: 0 type: integer x-ratelimit-remaining: description: >- Requests left before this caller is limited: the per-address limit's when that limit counted the request, otherwise the API key's own remaining allowance. Absent when no finite limit counted the request. schema: minimum: 0 type: integer x-ratelimit-reset: description: >- Sent with x-ratelimit-limit, only when the request's API key has its own limit: whole seconds until that allowance is full again. schema: minimum: 0 type: integer x-request-id: description: >- The request's id: the caller's valid `X-Request-Id`, or a generated UUID v4. Quote it when asking for support. schema: type: string '429': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: >- Too many requests. Wait the number of seconds in `Retry-After` before retrying. headers: Retry-After: description: >- Whole seconds to wait before retrying. Always sent on 429; sent on 503 when the wait is known. `details.retryAfter` carries the same wait as an ISO 8601 duration. schema: minimum: 0 type: integer x-ratelimit-limit: description: >- Sent only when the request's API key has its own requests-per-minute limit: that limit. Sessions, and keys without their own limit, never receive it. schema: minimum: 0 type: integer x-ratelimit-remaining: description: >- Requests left before this caller is limited: the per-address limit's when that limit counted the request, otherwise the API key's own remaining allowance. Absent when no finite limit counted the request. schema: minimum: 0 type: integer x-ratelimit-reset: description: >- Sent with x-ratelimit-limit, only when the request's API key has its own limit: whole seconds until that allowance is full again. schema: minimum: 0 type: integer x-request-id: description: >- The request's id: the caller's valid `X-Request-Id`, or a generated UUID v4. Quote it when asking for support. schema: type: string '500': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Something went wrong on our side. headers: x-ratelimit-limit: description: >- Sent only when the request's API key has its own requests-per-minute limit: that limit. Sessions, and keys without their own limit, never receive it. schema: minimum: 0 type: integer x-ratelimit-remaining: description: >- Requests left before this caller is limited: the per-address limit's when that limit counted the request, otherwise the API key's own remaining allowance. Absent when no finite limit counted the request. schema: minimum: 0 type: integer x-ratelimit-reset: description: >- Sent with x-ratelimit-limit, only when the request's API key has its own limit: whole seconds until that allowance is full again. schema: minimum: 0 type: integer x-request-id: description: >- The request's id: the caller's valid `X-Request-Id`, or a generated UUID v4. Quote it when asking for support. schema: type: string '503': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: >- TRADE_PROJECTION_UNAVAILABLE: the projection's owner is not installed on this stack headers: Retry-After: description: >- Whole seconds to wait before retrying. Always sent on 429; sent on 503 when the wait is known. `details.retryAfter` carries the same wait as an ISO 8601 duration. schema: minimum: 0 type: integer x-ratelimit-limit: description: >- Sent only when the request's API key has its own requests-per-minute limit: that limit. Sessions, and keys without their own limit, never receive it. schema: minimum: 0 type: integer x-ratelimit-remaining: description: >- Requests left before this caller is limited: the per-address limit's when that limit counted the request, otherwise the API key's own remaining allowance. Absent when no finite limit counted the request. schema: minimum: 0 type: integer x-ratelimit-reset: description: >- Sent with x-ratelimit-limit, only when the request's API key has its own limit: whole seconds until that allowance is full again. schema: minimum: 0 type: integer x-request-id: description: >- The request's id: the caller's valid `X-Request-Id`, or a generated UUID v4. Quote it when asking for support. schema: type: string security: - bearer_auth: [] - api_key: [] components: parameters: WorkspaceId: description: >- 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). in: header name: X-Workspace-Id required: false schema: format: uuid type: string schemas: TradeScope: description: Whose rows the list reads. enum: - mine - workspace - umbrella type: string TradePerspective: description: Which side of the trade the workspace was on. enum: - taker - maker type: string TradeKindFilter: description: Explicit population selection, not an unsupported-filter exclusion. enum: - all - order - venueTrade type: string TradesFormat: description: The representation of the list. enum: - json - csv type: string TradeList: description: One page of the trade history. properties: coverage: description: >- Taker projections: kinds whose rows could not be read; the list shows the rest. items: $ref: '#/components/schemas/TradeKindCoverage' type: array excludedKinds: description: >- Taker projections: kinds a filter or sort left out, each with the parameter it could not apply. items: $ref: '#/components/schemas/TradeKindExclusion' type: array items: items: $ref: '#/components/schemas/TradeRecord' type: array latestTradeAt: description: >- Newest `createdAt` the caller may see in this projection, ignoring every filter. format: date-time type: - string - 'null' limit: description: The page size applied. format: int32 minimum: 0 type: integer makerContext: oneOf: - type: 'null' - $ref: '#/components/schemas/MakerListContext' description: >- Maker projections only: what the fills or settlement-queue read returned about the page beyond its rows, unchanged. Absent for every taker projection. nextCursor: description: Pass as `cursor` for the next page; null on the last page. type: - string - 'null' scope: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeListScope' description: >- Taker projections: whose orders the list holds (every workspace order, or the caller's own). total: description: Rows matching the filters in this projection. format: int64 minimum: 0 type: integer required: - items - total - limit type: object ApiError: description: >- A refusal of an integrator operation. Codes are an open set: a client handles the codes it knows and falls back on the HTTP status for any other. properties: details: oneOf: - type: 'null' - $ref: '#/components/schemas/ApiErrorDetails' docUrl: description: Stable documentation for this refusal code. type: string error: description: The machine-readable code, for example `QUOTE_EXPIRED`. type: string message: description: What happened, in words a person can read. Not for matching. type: string next: oneOf: - type: 'null' - $ref: '#/components/schemas/QuoteNextAction' description: >- The way forward, when there is one (for example `requote` on an expired quote). requestId: description: >- The request's id, the value the `X-Request-Id` response header carries. Quote it when asking for support. type: - string - 'null' retryable: description: >- Whether an unchanged request may succeed later, from the error catalogue. type: boolean timestamp: description: When the refusal was made, in Unix seconds. format: int64 type: integer required: - error - docUrl - retryable - message - timestamp type: object TradeKindCoverage: description: >- A kind whose rows could not be read: the list is partial, never silently shorter. properties: kind: $ref: '#/components/schemas/TradeKind' state: $ref: '#/components/schemas/TradeCoverageState' required: - kind - state type: object TradeKindExclusion: description: >- A kind left out of the list because a filter or sort cannot apply to it, and which. properties: filter: description: >- The query parameter that kind cannot honour (`corridor`, `sortBy`, ...). type: string kind: $ref: '#/components/schemas/TradeKind' required: - kind - filter type: object TradeRecord: allOf: - anyOf: - $ref: '#/components/schemas/CompanyTradeListItem' - not: anyOf: - required: - orderId - required: - createdAt - required: - submittedByYou - required: - route - required: - lpName - required: - lpSource - required: - routingPathLabel - required: - status - required: - settlementStatus - required: - lifecycleStatus - required: - executionPrice - anyOf: - $ref: '#/components/schemas/CompanyVenueTradeListItem' - not: anyOf: - required: - connectionId - required: - operationId - required: - executionTypeId - required: - venueName - required: - venueAccountName - required: - providerSite - required: - createdAt - required: - submittedByYou - required: - sell - required: - buy - required: - executionStatus - required: - lifecycleStatus - properties: kind: $ref: '#/components/schemas/TradeKind' projection: $ref: '#/components/schemas/TradeProjection' description: Which projection produced the row. tradeId: description: >- The order id, or a venue trade's operation id; the detail is `…/trades/{tradeId}`. type: string required: - tradeId - kind - projection type: object description: >- 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. MakerListContext: description: >- The maker read's own page context: the fills list's (perspective=maker) or the settlement queue's (perspective=maker with settlementStage or minAgeSeconds). oneOf: - $ref: '#/components/schemas/MakerFillsContext' - $ref: '#/components/schemas/MakerSettlementContext' TradeListScope: description: |- The order visibility scope used for the trade list. New values may be added; treat unknown values as other. enum: - workspace - own type: string x-extensible-enum: true ApiErrorDetails: additionalProperties: description: >- Any further detail the code carries (for example `stepUpSubject`, `balanceShortfall`, `minimumAmount`), each named in camelCase. description: >- The code's detail. Each field is present only on the codes named beside it; other codes may carry further fields, named in camelCase, which a client may ignore. properties: capabilityBlockers: description: >- `CAPABILITY_BLOCKED` and the other capability refusals: what blocks the workspace. items: $ref: '#/components/schemas/CapabilityBlocker' type: - array - 'null' conflicts: description: '`REQUOTE_FIELDS_CONFLICT`: the fields that cannot go with `requote`.' items: type: string type: - array - 'null' field: description: '`INVALID_REQUEST` (out of range): the field.' type: - string - 'null' reason: description: >- A machine-readable reason token the refusing step gave. Known source reason tokens (not all apply to every status): `adapterPayloadSerializationFailed`, `basicVenueAccountsUnavailable`, `billingPaymentOverdue`, `walletNotOnChain`, `ccxtVenueRequiresCexLane`, `executionStageDisabled`, `jurisdictionUnproven`, `onboardedVenuesUnavailable`, `onchainAccountDefaultWalletRequired`, `onchainAccountDefaultWalletUnavailable`, `onchainAccountWalletRequired`, `onchainAssetDecimalsMismatch`, `onchainAssetIdentityMismatch`, `onchainAssetUnmapped`, `onchainAssetVariantFiltered`, `onchainWalletUnavailable`, `onchainCatalogueUnavailable`, `onchainDeliverToNotReceivingWallet`, `onchainDeliverToUnverified`, `onchainMarketsUnavailable`, `onchainMarketCatalogUnreadable`, `onchainMarketChainRequired`, `onchainMarketVariantRequired`, `onchainMarketTokenRequired`, `onchainSiteChainUnreadable`, `onchainWalletChainUnreadable`, `onchainWalletInactive`, `onchainWalletNotLinked`, `onchainWalletNotUsable`, `onchainWalletPickAmbiguous`, `onchainWalletWrongNetwork`, `payeeDeliveryUnsupported`, `signerLacksRight`, `signerUnavailable`, `signingGrantAmbiguous`, `signingGrantExpired`, `signingGrantRequired`, `signingGrantTokenNotKept`, `signingGrantTokenNotPayable`, `solverChainUnready`, `walletChainMismatch`, `walletNotUsableByYou`, `walletNotVerifiedForAce`, `walletNotWhitelisted`, `withdrawalChainUnsupported`, `accountFeeUnavailable`, `comparisonCostsUnavailable`, `connectionListingUnavailable`, `feeUnverified`, `noPool`, `noPrice`, `noSize`, `notFilled`, `notYetPublished`, `priceArithmetic`, `priceSourceNone`, `referenceMidUnavailable`, `settlementPrecisionUnavailable`, `accountSetupIncomplete`, `admissionUnavailable`, `advancedAccountEligibilityUnavailable`, `advancedAccountStateInconsistent`, `advancedConnectionDisabled`, `advancedConnectionNotConfigured`, `advancedConnectionPaused`, `advancedSettlementNeedsVerification`, `advancedModeDisabled`, `advancedNotAvailableForAccount`, `advancedNotEnabledForAccount`, `allowanceUnavailable`, `acrossCapacityExceeded`, `relayCapacityExceeded`, `acrossChainNotCarried`, `cctpChainNotCarried`, `relayChainNotCarried`, `apiKeyAdvancedWalletUnsupported`, `apiKeyOrganisationWalletScopeRequired`, `grantCapExceeded`, `amountAboveMaximum`, `amountBelowMinimum`, `amountUnreadable`, `amountsUnreadable`, `askFirst`, `authorityUnavailable`, `automationNeverAsks`, `availabilityUnreadable`, `backgroundNeverAsks`, `balanceUnreadable`, `defaultsUnavailable`, `walletHasNoAddress`, `walletUnavailable`, `bondAmountUnreadable`, `bondAssetUnreadable`, `catalogueUnavailable`, `chainFamilyUnknown`, `chainUnrecorded`, `clientSessionRequired`, `clockUnreadable`, `comingSoon`, `connectionChanged`, `connectionRevoked`, `corridorInvalid`, `credential`, `deadlineExceeded`, `defaultsLoading`, `deliverToCalldataUnsupported`, `deliverToTagUnsupported`, `deliverToNotPermitted`, `deliverToUnreadable`, `tradingPermissionRequired`, `directPatienceHarvest`, `economicallyInferior`, `exactAmountConflictsWithCard`, `exactAmountConflictsWithQuote`, `exactOutputDeliveryUnsupported`, `exactOutputEstimateUnavailable`, `exactRouteHypothesisUnavailable`, `expiredOnArrival`, `expiryUnknown`, `feeUnreadable`, `filteredOut`, `firmAskRefused`, `freshnessUnknown`, `fundingWindow`, `insufficientLiquidity`, `venueRelationship`, `venueRelationshipUnavailable`, `lpUnknown`, `mfaEnrolmentRequired`, `mfaRequired`, `minimumUnverified`, `mixedNetworks`, `netReceivedUnavailable`, `networkUnrecorded`, `noAddress`, `noCard`, `noFetcher`, `noInventory`, `noLaneForPair`, `noLegs`, `noOnChainCorridor`, `noPlannedVenue`, `noQuote`, `noRpc`, `notConnected`, `notEligible`, `notExecutable`, `orderPayloadMissing`, `outsideTopComposites`, `pairUnmapped`, `sellChainInvalid`, `permissionsUnreadable`, `placeOrderNotPermitted`, `prefundingMarkerUnreadable`, `prefundingRequired`, `indicative`, `priceOnRequest`, `priceOutOfRange`, `priceProtectionInvalid`, `pricingBookOnly`, `productNotQuoted`, `protocolChainMissing`, `providerFeeTreatmentUnknown`, `providerSiteUnrecorded`, `quoteIdUnissuable`, `quoteNotHeld`, `buyChainInvalid`, `buyAmountUnsupported`, `exactOutputDebitUnavailable`, `pairNotServed`, `receiveWalletNotServed`, `referenceMidUnreadable`, `referencePriceUnavailable`, `registryUnavailable`, `releaseRecheckUnavailable`, `requestUnbuildable`, `routeLegChainUnknown`, `routeLegUnnamed`, `routeLegUnplanned`, `routeUnavailable`, `secondFactorUnreadable`, `shortfallUnmeasured`, `shortfallUnreadable`, `singleChainVenue`, `siteChainUnreadable`, `sizeNotEligible`, `submitOrderBlocked`, `takerOnboardingIncomplete`, `tierNotQuoted`, `tradePaused`, `unsupportedNative`, `venueConnectionStorageUnavailable`, `venueDataStale`, `venueDeclined`, `venueNotConnected`, `venueNotEnabledForWorkspace`, `venueNotListed`, `venueTradeKeyUnavailable`, `venueTradeScopeRequired`, `venueTradeUnreadable`, `venueUnavailable`, `walletRefused`, `withdrawalFeeUnread`, `acrossRoutedViaCctp`, `apiKeyOrganisationWalletNotAllowlisted`, `balanceAvailabilityUnconfirmed`, `bankDestinationUnavailable`, `bebopJamKeyNotEnabled`, `bebopJamQuoteDeclined`, `bebopTokenUnavailable`, `relayCurrencyUnsupported`, `relaySwapImpactTooHigh`, `tetrafiSolverCallbackNotAuthorized`, `tradingLinkSnapshotChanged`, `tradingLinkSnapshotUnavailable`, `uniswapChainReadUnavailable`, `uniswapInsufficientDepth`, `uniswapQuoteUnreadable`, `uniswapUnwrapAboveDailyCap`, `uniswapUnwrapAboveTradeCap`, `uniswapRouteNotGranted`, `venueNotEnabled`, `askLimitReached`, `balanceMeaningUnconfirmed`, `bebopJamWalletUnsupported`, `bebopQuorumWalletTooSlow`, `bebopWalletQuorumUnreadable`, `connectionNotConfigured`, `deliveryAccountNetworkUnavailable`, `deliveryAccountUnavailable`, `destinationCannotSendOnChain`, `dexReferencePriceUnavailable`, `firmQuoteLimited`, `fundingAccountNetworkUnavailable`, `fundingAccountUnavailable`, `insufficientDepth`, `missingPermission`, `needsNativeGas`, `needsWallet`, `notPriced`, `payInTermsUnavailable`, `pilotTradeCapExceeded`, `platformFeeRateUnavailable`, `pricingBookPairUnserved`, `settlementDeclarationUnavailable`, `settlementNotAvailable`, `timedOut`, `timedOutBeforeSend`, `tradingSourceNetworkUnavailable`, `tradingSourceNotLinked`, `venueEnablementRechecking`, `venueEnablementUnavailable`, `venueListingTimedOut`, `venuePoliciesUnavailable`. New values may be added; treat unknown values as other. type: - string - 'null' remediation: description: A machine-readable recovery hint the refusing step gave. type: - string - 'null' retryAfter: oneOf: - type: 'null' - $ref: '#/components/schemas/IsoDuration' description: >- Every `429`, and a `503` that knows: when to try again, as an ISO 8601 duration. The `Retry-After` header carries the same wait in whole seconds. value: description: >- `UNKNOWN_ASSET`, `UNKNOWN_CHAIN`, `UNKNOWN_VENUE`, `INVALID_AMOUNT`: the value refused; `ASSET_NOT_ON_CHAIN`: the pinned chain the Asset is not on. type: - string - 'null' type: object QuoteNextAction: description: |- The one action the caller takes next; later legs run under the order. New values may be added; treat unknown values as other. discriminator: propertyName: kind oneOf: - description: '`POST /orders {quoteId}`.' properties: kind: description: New values may be added; treat unknown values as other. enum: - order type: string x-extensible-enum: true required: - kind type: object - description: >- `POST /orders/preflight`: the held terms may need an approval, allowance or receipt the server cannot confirm from memory. Its response carries the next step. properties: kind: description: New values may be added; treat unknown values as other. enum: - preflight type: string x-extensible-enum: true required: - kind type: object - description: Send these transactions, then order. properties: kind: description: New values may be added; treat unknown values as other. enum: - transact type: string x-extensible-enum: true transactions: items: $ref: '#/components/schemas/TakerTransaction' type: array required: - transactions - kind type: object - description: Sign this EIP-712 document, then order. properties: kind: description: New values may be added; treat unknown values as other. enum: - sign type: string x-extensible-enum: true typedData: {} required: - typedData - kind type: object - description: >- Fund, then requote. `null` instructions when they could not be read; no order is accepted while short either way. properties: instructions: oneOf: - type: 'null' - $ref: '#/components/schemas/FundInstructions' kind: description: New values may be added; treat unknown values as other. enum: - fund type: string x-extensible-enum: true required: - kind type: object - description: Ask the venue again, with these Binding slots filled. properties: kind: description: New values may be added; treat unknown values as other. enum: - requote type: string x-extensible-enum: true needs: items: $ref: '#/components/schemas/RequoteNeed' type: array required: - needs - kind type: object - description: >- Search again: `POST /quotes` with a pair body. The quote is past its requote window, so `{requote: quoteId}` can no longer refresh it. properties: kind: description: New values may be added; treat unknown values as other. enum: - search type: string x-extensible-enum: true required: - kind type: object - description: >- The venue outcome is being reconciled. Read this same order again after the given ISO 8601 duration; never submit a replacement order. properties: kind: description: New values may be added; treat unknown values as other. enum: - wait type: string x-extensible-enum: true retryAfter: $ref: '#/components/schemas/IsoDuration' required: - retryAfter - kind type: object - description: Contact support with this non-secret order reference. properties: kind: description: New values may be added; treat unknown values as other. enum: - contact type: string x-extensible-enum: true reference: type: string required: - reference - kind type: object x-extensible-enum: true TradeKind: description: |- The kinds the one trade history lists. New values may be added; treat unknown values as other. enum: - order - venueTrade type: string x-extensible-enum: true TradeCoverageState: description: New values may be added; treat unknown values as other. enum: - unavailable type: string x-extensible-enum: true CompanyTradeListItem: description: A single trade in the paginated list view. properties: actionRequired: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeActionRequired' description: >- Set when the order is waiting on a person rather than on a chain or a solver: a composite parked until its taker re-quotes and signs the next leg. Its coarse `status` still reads `executing`, identical to a leg in flight, so this is the only list field that tells the two apart. Absent for every other order. amountUsd: description: >- Absent when the order recorded no USD notional; never 0 for an unknown amount. format: double type: - number - 'null' apiKey: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeApiKey' channel: oneOf: - type: 'null' - $ref: '#/components/schemas/OrderChannel' createdAt: format: date-time type: string custodyVaultAddress: description: >- Custody vault address when the order settled through a custody vault. Absent for self-custody orders. type: - string - 'null' deferredSettlement: oneOf: - type: 'null' - $ref: '#/components/schemas/DeferredSettlementInfo' deliveredBuyProvenance: description: >- Provenance of the delivered buy amount behind `slippage_bps`: `"measured"` vs `"quoted"` (carried forward unmeasured). See the detail section. type: - string - 'null' executionPrice: $ref: '#/components/schemas/ExecutionPriceDisplay' failureReason: description: >- Why the order failed or was refunded, as the detail's `settlement.failureReason` reports it: absent while the order has no recorded failure. type: - string - 'null' lifecycleStatus: $ref: '#/components/schemas/TradeLifecycleStatus' linkedWalletId: description: >- Account-linked wallet id that placed the trade, for per-wallet filtering and display. Absent for router-executed or unattributed orders that carry no linked wallet. type: - string - 'null' lpName: type: string lpSource: type: string lpVenueId: description: >- The catalogue Venue id of the order's LP (`keyrock`, `circle-cctp`; a routed order's first leg), so a client draws the LP's logo by identity rather than by `lp_name`. Absent when no catalogue Venue declares that LP. type: - string - 'null' nextAction: oneOf: - type: 'null' - $ref: '#/components/schemas/NextAction' description: >- The typed form of `actionRequired`: the same decision the order page reads (`OrderResponse.nextAction`), computed by the same backend owner. Clients switch on its `kind`; `actionRequired` stays for older clients and is derived from it. nextActor: oneOf: - type: 'null' - $ref: '#/components/schemas/NextActor' description: 'Who acts next: the same decision the order read carries.' orderId: type: string orderKind: description: >- Canonical route-aware order kind (`cctp-v0` / `composite-v0` / `fx-v0` / …) for list clients + API-key parity with the detail. Absent for non-route orders, where `orderType` suffices. type: - string - 'null' route: $ref: '#/components/schemas/TradeRouteDisplay' routingPath: oneOf: - type: 'null' - $ref: '#/components/schemas/RoutingPath' routingPathLabel: type: string settlementSpeedMs: format: int64 minimum: 0 type: - integer - 'null' settlementStatus: type: string slippageBps: format: int64 type: - integer - 'null' status: description: |- Canonical user-facing order lifecycle status from `orders.status`. `settlement_status` remains the coarse analytics bucket. type: string submittedByYou: description: >- The caller submitted this order: the same rule as the order read's `viewer.submittedByYou` (the linked wallet's user or the order's user is the caller). Always false for an API-key caller. type: boolean required: - orderId - createdAt - submittedByYou - route - lpName - lpSource - routingPathLabel - status - settlementStatus - lifecycleStatus - executionPrice type: object CompanyVenueTradeListItem: description: A venue trade in the one trade history. properties: apiKey: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeApiKey' buy: $ref: '#/components/schemas/VenueTradeHistoryLeg' description: >- What the trade buys: its asset and, when recorded, the least it must receive from its consented bounds. connectionId: type: string createdAt: format: date-time type: string executionPrice: description: >- Legacy confirmed output per input (buy asset / sell asset), computed with Decimal; null when unread. executionPriceUnit states its unit; prefer statedExecutionPrice for display. type: - string - 'null' executionPriceUnit: oneOf: - type: 'null' - $ref: '#/components/schemas/VenueTradePriceUnit' executionStatus: $ref: '#/components/schemas/VenueTradeExecutionStatus' executionTypeId: description: The execution type (compiled spec id), not the catalogue Venue. type: string feesPaid: description: >- 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. type: - string - 'null' financials: oneOf: - type: 'null' - $ref: '#/components/schemas/VenueTradeFinancials' description: >- 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: description: What the venue debited and credited, once its outcome is recorded. type: - string - 'null' lifecycleStatus: $ref: '#/components/schemas/TradeLifecycleStatus' description: >- The same lifecycle shape an order row carries; `needsReview` is not final. notSentReason: oneOf: - type: 'null' - $ref: '#/components/schemas/VenueTradeNotSentReason' description: >- Why a `not_sent` outcome was not sent, as the dispatch's `notSentReason`. operationId: type: string outcomeCode: description: >- 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. type: - string - 'null' outputReceived: type: - string - 'null' pair: description: >- The recorded market pair; absent stays absent, never inferred from asset order. type: - string - 'null' placedBy: oneOf: - type: 'null' - $ref: '#/components/schemas/VenueTradePlacedBy' description: >- Who placed the trade: the API key by label, else the member where this reader may see their name. Absent otherwise. providerSite: type: string sell: $ref: '#/components/schemas/VenueTradeHistoryLeg' description: >- What the trade sells: its asset and, when recorded, the most it may spend from its consented bounds. statedExecutionPrice: oneOf: - type: 'null' - $ref: '#/components/schemas/VenueTradeStatedPrice' description: >- QuoteCurrencyPriority market convention, with explicit base/quote and fallback basis. submittedByYou: type: boolean tetrafiFee: description: >- Gross TetraFi fee (list rate, before incentives) from the Basic billing ledger, in tetrafiFeeAsset; absent until accrued. type: - string - 'null' tetrafiFeeAsset: type: - string - 'null' venueAccountName: description: >- 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"). type: string venueName: description: The venue's name, for display. type: string required: - connectionId - operationId - executionTypeId - venueName - venueAccountName - providerSite - createdAt - submittedByYou - sell - buy - executionStatus - lifecycleStatus type: object TradeProjection: description: >- 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. enum: - mine - workspace - umbrella - maker - settlement type: string x-extensible-enum: true MakerFillsContext: description: The fills list's context, field for field as the fills read returns it. properties: accountSummary: oneOf: - type: 'null' - $ref: '#/components/schemas/VenueFillSummary' description: >- Venue-account totals, when the read asked for them (flow=venue_account&includeAccountSummary=true). ownedSolvers: description: The solvers this LP workspace owns. items: $ref: '#/components/schemas/OwnedSolverIdentity' type: array selectedAccountFilter: oneOf: - type: 'null' - $ref: '#/components/schemas/VenueFillFilter' description: >- The venue-account filter the read applied, when one was requested. selectedBrokerId: description: The broker filter the read applied. type: - string - 'null' selectedCohort: description: The cohort filter the read applied. type: - string - 'null' selectedRiskScope: oneOf: - type: 'null' - $ref: '#/components/schemas/RecordedRiskTradeScope' description: >- The recorded risk scope the read applied, when one was requested. selectedSolverId: description: The solver the fills were read for. type: - string - 'null' required: - ownedSolvers - selectedSolverId - selectedBrokerId - selectedCohort type: object MakerSettlementContext: description: >- The settlement queue's context, field for field as the queue read returns it. properties: asOf: description: When the queue snapshot was read. format: date-time type: string maxOffset: description: >- Beyond this bound the operator must narrow stage, corridor or connection. format: int32 minimum: 0 type: integer offset: description: The page's offset. format: int32 minimum: 0 type: integer required: - asOf - offset - maxOffset type: object CapabilityBlocker: description: One reason a capability is blocked, plus the step that unlocks it. properties: code: $ref: '#/components/schemas/CapabilityBlockerCode' currentlyDue: description: |- Requirement keys still due, such as `kyb_review`, `actor_kyc` or `permission:place_order`. Empty when nothing specific is due. items: type: string type: array estimate: $ref: '#/components/schemas/CapabilityUnlockEstimate' message: type: string unlockStep: $ref: '#/components/schemas/CapabilityUnlockStep' description: >- Stable key of the step that unlocks this blocker. The UI maps it to a route or dialog. required: - code - message - unlockStep - estimate type: object IsoDuration: description: An ISO 8601 duration, e.g. PT3S or PT2M. examples: - PT120S format: duration pattern: >- ^PT(?:[0-9]+H(?:[0-9]+M)?(?:[0-9]+(?:\.[0-9]{1,3})?S)?|[0-9]+M(?:[0-9]+(?:\.[0-9]{1,3})?S)?|[0-9]+(?:\.[0-9]{1,3})?S)$ type: string TakerTransaction: description: One transaction the Taker sends itself (an approval included). properties: chain: $ref: '#/components/schemas/Caip2Chain' data: description: Hex calldata (`0x…`). type: string to: type: string value: description: Native value in base units, as a decimal string. type: string required: - chain - data - to - value type: object FundInstructions: description: >- What to fund and how. Bank funding carries only a privacy-safe summary and a non-bearer reference to the separately authorized reveal read. New values may be added; treat unknown values as other. discriminator: propertyName: kind oneOf: - properties: address: type: string asset: type: string chainRef: type: string expiresAt: format: date-time type: string kind: description: New values may be added; treat unknown values as other. enum: - venueDeposit type: string x-extensible-enum: true memo: type: - string - 'null' networkCode: type: string networkConfirmed: description: >- False when the venue reports no network for this address: `networkCode` is empty and `chainRef` is the caller's selection, which the customer must confirm with the venue before sending. type: boolean observedAt: format: date-time type: string tokenContract: type: string required: - asset - chainRef - networkCode - networkConfirmed - address - tokenContract - observedAt - expiresAt - kind type: object - description: >- The only bank-deposit payload allowed in an asset-pair quote, request readback or copied durable/evidence body. It carries no receiving coordinates or payment memo. Fund, then explicitly requote; this summary never authorizes a transfer or order. properties: accountLast4: oneOf: - type: 'null' - $ref: '#/components/schemas/BankAccountSuffix' description: >- An already-qualified masked suffix, not external account ownership proof. amount: $ref: '#/components/schemas/DecimalAmount' bankDisplayName: type: - string - 'null' expiresAt: description: >- UTC ISO instant, or null when expiry is UNKNOWN. Null never means no expiry. format: date-time type: - string - 'null' kind: description: New values may be added; treat unknown values as other. enum: - bankDeposit type: string x-extensible-enum: true revealRef: $ref: '#/components/schemas/BankFundingRevealRef' required: - accountLast4 - amount - bankDisplayName - expiresAt - kind - revealRef type: object - description: >- The quote's own bound pay wallet (an organisation wallet on a Basic on-chain venue account) holds less than the trade debits: send `amount` of `asset` to `address` on `chain`, then get a new price. `walletId` is the binding target the source's `topUp` fix names; `tokenContract` is the registry's deployment address of `asset` on `chain` (the zero address for the chain's native coin). properties: address: type: string amount: $ref: '#/components/schemas/DecimalAmount' asset: $ref: '#/components/schemas/AssetId' chain: $ref: '#/components/schemas/Caip2Chain' kind: description: New values may be added; treat unknown values as other. enum: - walletTopUp type: string x-extensible-enum: true tokenContract: type: string walletId: type: string required: - walletId - address - chain - asset - tokenContract - amount - kind type: object - description: Native gas for a transaction the Taker sends itself. properties: amount: $ref: '#/components/schemas/DecimalAmount' asset: $ref: '#/components/schemas/AssetId' chain: $ref: '#/components/schemas/Caip2Chain' kind: description: New values may be added; treat unknown values as other. enum: - nativeGas type: string x-extensible-enum: true required: - chain - amount - asset - kind type: object - description: >- A bank-funded venue account is short and deposit first isn't offered on it: its bank side declares no deposit instructions, or nothing that credits a declared deposit. The account is funded from its own funding details, then the quote is asked again. `amount` is the shortfall in `currency`; `connectionId` is the venue account to fund; `reason` is the venue's declared sentence for why ("Keyrock gives no deposit reference for bank transfers, so TetraFi can't tell your deposit apart"), product copy without a final period. properties: amount: $ref: '#/components/schemas/DecimalAmount' connectionId: type: string currency: type: string kind: description: New values may be added; treat unknown values as other. enum: - depositFirstNotOffered type: string x-extensible-enum: true reason: type: string required: - connectionId - amount - currency - reason - kind type: object x-extensible-enum: true RequoteNeed: description: >- A Binding slot a requote needs filled. An empty `needs` means requote as is. New values may be added; treat unknown values as other. enum: - wallet:evm - wallet:solana - wallet:tron - account - bankAccount - deliverTo type: string x-extensible-enum: true TradeActionRequired: description: An action a person must take before the order can progress. properties: code: description: >- Stable machine code: `AWAITING_TAKER_SIGNATURE`, `PRICE_MOVED`, `NEXT_LEG_DID_NOT_RUN`, `FINISH_TRADE`, `STOPPED` or `SUPPORT_REVIEW`. type: string message: description: Human-readable explanation of the action. type: string required: - code - message type: object TradeApiKey: properties: keyId: type: string name: type: - string - 'null' required: - keyId type: object OrderChannel: description: New values may be added; treat unknown values as other. enum: - ui - api - whitelabel - embedded type: string x-extensible-enum: true DeferredSettlementInfo: description: >- Deferred LP settlement/withdrawal tracking that is separate from the order's primary execution status. A deferred order can be `Executed` while this object still reports a settlement window or withdrawal state. properties: autoWithdraw: type: boolean estimatedSettlementAvailableAt: format: date-time type: - string - 'null' executedAt: format: date-time type: - string - 'null' settlementWindowHours: format: int32 minimum: 0 type: - integer - 'null' stage: type: string withdrawalStatus: type: - string - 'null' withdrawalTrackingId: type: - string - 'null' withdrawalTxHash: type: - string - 'null' required: - stage - autoWithdraw type: object ExecutionPriceDisplay: description: User-facing execution price for a read model. properties: baseSymbol: type: - string - 'null' quoteSymbol: type: - string - 'null' source: $ref: '#/components/schemas/ExecutionPriceSource' value: type: - string - 'null' required: - source type: object TradeLifecycleStatus: properties: bucket: $ref: '#/components/schemas/TradeLifecycleBucket' description: >- Which history bucket this lifecycle belongs to: decided by the same arm that chose `primary`, so a filter on it can never disagree with the label. execution: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLifecycleStep' flowKind: type: string isTerminal: type: boolean primary: $ref: '#/components/schemas/TradeLifecycleStep' rank: format: int32 minimum: 0 type: integer rawDeferredStatus: type: - string - 'null' rawStatus: type: string settlement: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLifecycleStep' withdrawal: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLifecycleStep' required: - flowKind - primary - bucket - isTerminal - rank - rawStatus type: object NextAction: description: >- What the order needs from its reader next. Absent when nothing is needed. Each variant is a distinct situation with a distinct remedy; none collapses onto another, and a state the backend cannot decide yields no action rather than a `signNextLeg` it cannot back. New values may be added; treat unknown values as other. oneOf: - description: The payout remains unsent with its venue-account hold retained. properties: kind: description: New values may be added; treat unknown values as other. enum: - payoutFeeRose type: string x-extensible-enum: true legId: format: uuid type: string required: - legId - kind type: object - description: >- A bound wallet destination is no longer usable. Funds remain at the LP. properties: kind: description: New values may be added; treat unknown values as other. enum: - provideDestination type: string x-extensible-enum: true legId: format: uuid type: string reason: type: string required: - legId - reason - kind type: object - description: >- The taker signs the next leg. `legIndex` 0 is an FX-first order that has not started: its funds are still in the taker's wallet. properties: kind: description: New values may be added; treat unknown values as other. enum: - signNextLeg type: string x-extensible-enum: true legIndex: format: int32 minimum: 0 type: integer required: - legIndex - kind type: object - description: >- The fresh price moved past the tolerance. The taker may accept it once. properties: kind: description: New values may be added; treat unknown values as other. enum: - priceMoved type: string x-extensible-enum: true offer: $ref: '#/components/schemas/ContinuationRepricingOffer' required: - offer - kind type: object - description: >- A leg did not run and the funds came back to the taker: sign it again, on the same order. properties: attempt: description: The attempt the retry starts (the ended attempts plus one). format: int32 minimum: 0 type: integer fundsAt: oneOf: - type: 'null' - $ref: '#/components/schemas/FundsLocation' kind: description: New values may be added; treat unknown values as other. enum: - retryNextLeg type: string x-extensible-enum: true legIndex: format: int32 minimum: 0 type: integer reason: type: string required: - legIndex - attempt - reason - kind type: object - description: >- The route ended with the funds in the taker's wallet part-way, and no re-quote owner can resume it: finish the trade from there with a new order. properties: fundsAt: $ref: '#/components/schemas/FundsLocation' kind: description: New values may be added; treat unknown values as other. enum: - finishTrade type: string x-extensible-enum: true reason: type: string required: - fundsAt - reason - kind type: object - description: The taker stopped waiting, or the wait reached its bound. properties: fundsAt: oneOf: - type: 'null' - $ref: '#/components/schemas/FundsLocation' kind: description: New values may be added; treat unknown values as other. enum: - stopped type: string x-extensible-enum: true reason: $ref: '#/components/schemas/StopReason' required: - reason - kind type: object - description: An operator must review the order; the taker cannot act on it. properties: kind: description: New values may be added; treat unknown values as other. enum: - supportReview type: string x-extensible-enum: true reason: type: string required: - reason - kind type: object x-extensible-enum: true NextActor: description: >- Who must act before the order can progress, shared by the order read and list. New values may be added; treat unknown values as other. enum: - taker - support - counterparty - none type: string x-extensible-enum: true TradeRouteDisplay: description: The sold and bought sides of a trade for display read models. properties: buy: $ref: '#/components/schemas/AssetAmountDisplay' description: What the order buys. sell: $ref: '#/components/schemas/AssetAmountDisplay' description: What the order sells. required: - sell - buy type: object RoutingPath: description: >- How an LP is available to a requesting workspace: `{"type": "direct"}`, or `{"type": "via_broker", "brokerWorkspaceId": "...", "brokerName": "..."}`. New values may be added; treat unknown values as other. oneOf: - description: >- LP has a direct bilateral relationship with the requesting workspace. properties: type: description: New values may be added; treat unknown values as other. enum: - direct type: string x-extensible-enum: true required: - type type: object - description: LP available through an affiliated broker. properties: brokerName: type: string brokerWorkspaceId: format: uuid type: string type: description: New values may be added; treat unknown values as other. enum: - via_broker type: string x-extensible-enum: true required: - brokerWorkspaceId - brokerName - type type: object x-extensible-enum: true VenueTradeHistoryLeg: description: >- One leg of a venue trade in the trade history, named sell or buy as in POST /quotes. amount is the consented bound in exact decimal units of asset (on sell the most spent, on buy the least received); absent when not recorded, never zero. properties: amount: description: >- The consented bound in exact decimal units of `asset`: on `sell` the most the trade may spend, on `buy` the least it must receive. Absent when not recorded, never `0`. type: - string - 'null' asset: type: string required: - asset type: object VenueTradePriceUnit: description: >- Unit of a price: `quoteAsset / baseAsset` means one base asset costs this many quote assets. properties: baseAsset: type: string quoteAsset: type: string required: - baseAsset - quoteAsset type: object VenueTradeExecutionStatus: description: >- A venue trade's execution status, in camelCase like the order `status` (`outcomeUnknown`). New values may be added; treat unknown values as other. enum: - notSubmitted - dispatching - outcomeUnknown - filled - unfilled - needsReview type: string x-extensible-enum: true VenueTradeFinancials: description: >- A venue trade's recorded money terms. Each field is a stored fact or absent; an absent fact is never zero. properties: fee: oneOf: - type: 'null' - $ref: '#/components/schemas/VenueTradeFillFee' description: The venue's fee as recorded with the fill; absent before a fill. legs: description: >- Its payment legs (bank payout, pay-in, wallet payout), as the order page reads them: rail, state, payout breakdown and a destination reference, never bank coordinates. items: $ref: '#/components/schemas/TradeLegFacts' type: array quotedOutput: description: The confirmed quote's output, beside what was received. type: - string - 'null' type: object VenueTradeNotSentReason: description: >- Why a claimed trade was proven not sent. An unclassified cause is NOT_SENT_UNCLASSIFIED, never free text. New values may be added; treat unknown values as other. enum: - 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 type: string x-extensible-enum: true VenueTradePlacedBy: description: |- Who placed a venue trade, as named on its order read and trade history. New values may be added; treat unknown values as other. oneOf: - description: A workspace member; `name` is first and last name, else the email. properties: kind: description: New values may be added; treat unknown values as other. enum: - member type: string x-extensible-enum: true name: type: string userId: type: string required: - userId - name - kind type: object - description: An API key; `name` is its label, absent when the key has none. properties: keyId: type: string kind: description: New values may be added; treat unknown values as other. enum: - apiKey type: string x-extensible-enum: true name: type: - string - 'null' required: - keyId - kind type: object x-extensible-enum: true VenueTradeStatedPrice: allOf: - $ref: '#/components/schemas/VenueTradePriceUnit' - properties: basis: $ref: '#/components/schemas/VenueTradePriceBasis' value: type: string required: - value - basis type: object description: >- Confirmed quote-asset units per one base asset; not a venue quote or an indicative price. VenueFillSummary: description: >- Exact reported amounts across matched completed requests, not settlement or valuation. properties: amountUnit: type: string candidateLimit: description: >- Source requests admitted before the lifecycle filter; an exceeded cap refuses the read. format: int32 minimum: 0 type: integer filledRequestCount: format: int64 minimum: 0 type: integer groups: items: $ref: '#/components/schemas/VenueFillQuantityGroup' type: array source: $ref: '#/components/schemas/FillSource' required: - source - amountUnit - candidateLimit - filledRequestCount - groups type: object OwnedSolverIdentity: description: >- Minimal owned identity for historical LP reads. No connection configuration, credentials, routing grants or counterparty identities are disclosed. properties: name: type: - string - 'null' retiredAt: format: date-time type: - string - 'null' solverId: type: string status: $ref: '#/components/schemas/SolverStatus' required: - solverId - status type: object VenueFillFilter: description: >- Exact recorded account selectors. Null axes remain unrestricted; no name, case or request-direction normalization changes the selected population. properties: executionTypeId: description: The selected execution type; null for an unrestricted axis. type: - string - 'null' inputAsset: type: - string - 'null' outputAsset: type: - string - 'null' providerSite: type: - string - 'null' required: - executionTypeId - providerSite - inputAsset - outputAsset type: object RecordedRiskTradeScope: description: >- The recorded business population and original rolling Risk window. `asOf` keeps the source's RFC 3339 text, including microsecond precision. It does not record which trades were in the population at that time. properties: asOf: type: string counterparty: type: string windowSeconds: format: int64 type: integer required: - counterparty - asOf - windowSeconds type: object CapabilityBlockerCode: description: |- Stable machine-readable blocker codes returned by the capability gate. New values may be added; treat unknown values as other. enum: - WORKSPACE_NOT_FOUND - WORKSPACE_NOT_ACTIVE - WORKSPACE_SUSPENDED - PARENT_WORKSPACE_INACTIVE - INSUFFICIENT_PERMISSION - WORKSPACE_TYPE_UNSUPPORTED - BASE_PROFILE_INCOMPLETE - BASE_PROFILE_UNREADABLE - KYB_NOT_VERIFIED - KYC_NOT_VERIFIED - SANCTIONS_FLAGGED - MEMBER_COMPLIANCE_FROZEN - MEMBER_COMPLIANCE_DENIED - SCREENING_PENDING - SCREENING_UNAVAILABLE - GEO_RESTRICTED - WALLET_NOT_VERIFIED - DIRECT_USER_NOT_FOUND - DIRECT_USER_SUSPENDED - DIRECT_USER_KYC_NOT_VERIFIED - INSUFFICIENT_SCOPE - TREASURY_DISABLED - NO_USABLE_CREDENTIAL - CROSS_OWNER_WRITE_DENIED - AGGREGATE_SCOPE_READ_ONLY - OWNER_SCOPE_REQUIRED - VENUE_OPERATION_UNSUPPORTED - TAKER_ONBOARDING_INCOMPLETE - TAKER_ADMISSION_UNAVAILABLE type: string x-extensible-enum: true CapabilityUnlockEstimate: description: >- Coarse time-to-unlock class. The UI owns the copy; figures are engineering estimates until the KYB queue and Sumsub webhooks supply measured values. New values may be added; treat unknown values as other. enum: - minutes - forms_then_review - admin_action - other_party - unknown - not_unlockable type: string x-extensible-enum: true CapabilityUnlockStep: description: |- Stable key for the step that unlocks a blocked capability. The backend names the step; the UI owns the step-to-route map. Never a UI route. New values may be added; treat unknown values as other. enum: - finish_onboarding - company_details - kyb_profile - kyc_dialog - link_wallet - ask_admin - contact_broker - manage_direct_users - manage_api_key - connect_custodian - switch_account_scope - contact_support - await_screening - none type: string x-extensible-enum: true Caip2Chain: description: >- A CAIP-2 chain id (`eip155:8453`, `solana:`, `tron:shasta`), syntax-checked: a namespace of 3 to 8 lowercase letters, digits or `-`, and a reference of 1 to 32 letters, digits, `-` or `_`. Compared exactly, as CAIP-2 references are case-sensitive. example: eip155:8453 type: string BankAccountSuffix: description: >- An already-qualified masked account suffix of 1 to 4 ASCII letters/digits, not external account ownership proof. Never truncate a full account number. examples: - A1b2 maxLength: 4 minLength: 1 pattern: ^[A-Za-z0-9]{1,4}$ type: string DecimalAmount: description: >- A non-negative decimal string in Asset units (`"10000"`, `"9994.0"`): digits with an optional fraction, no sign, exponent or leading zero. Never a float and never base units. A request amount must also be positive (`INVALID_AMOUNT`); a fee or a known balance may be zero. example: '10000' type: string BankFundingRevealRef: description: >- Non-bearer lookup metadata for deposit instructions. Possession grants no authority. Each reveal requires current wallet-view authority and exact account membership; an API key additionally needs treasury_read. Missing and foreign accounts share a refusal. Quotes never fetch these instructions. properties: connectionId: description: >- The native held leg's exact connection id, never a first/sole-connection guess. type: string currency: type: string providerBankId: description: >- The provider's linked-bank id when required by that venue; otherwise unknown/null. type: - string - 'null' required: - connectionId - currency - providerBankId type: object AssetId: description: >- A registry Asset id (`USDC`, `USDe`). Matched case-insensitively against the catalogue, which answers it in the registry's own spelling. example: USDC type: string ExecutionPriceSource: description: |- Source used for the execution price exposed by read-model APIs. New values may be added; treat unknown values as other. enum: - stored_quote_price - derived_from_amounts - unavailable type: string x-extensible-enum: true TradeLifecycleBucket: description: |- The history bucket chosen by the server's lifecycle projection. New values may be added; treat unknown values as other. enum: - inProgress - completed - failed - refunded - unknown type: string x-extensible-enum: true TradeLifecycleStep: description: >- A compact backend-owned display status for personal trade/order surfaces. `orders.settlement_status` remains a coarse analytics bucket; UI should use this shape for user-facing execution/settlement state. properties: key: type: string label: type: string tone: type: string required: - key - label - tone type: object ContinuationRepricingOffer: description: >- The fresh price a continuation was refused at, left for the taker to accept once. Carried by the 409 `QUOTE_PRICE_MOVED` body. It binds one attempt of one leg and expires; accepting it rebaselines only that attempt. properties: acceptedAmount: description: >- The reference the order held the leg to (the price accepted at quote time, or a re-price accepted earlier in this attempt), in base units. type: string asset: oneOf: - type: 'null' - $ref: '#/components/schemas/AssetDisplay' description: The compared asset, when the order records it. attempt: description: >- The attempt this offer belongs to, numbered as in the order's `legAttempts`. format: int32 minimum: 0 type: integer boundAmount: description: >- The bound the fresh value had to meet: `acceptedAmount` widened by the tolerance. type: string compared: $ref: '#/components/schemas/RepricedSide' expiresAt: description: Unix seconds after which the offer can no longer be accepted. format: int64 type: integer freshAmount: description: The fresh value the venue quoted, in base units. type: string legIndex: format: int32 minimum: 0 type: integer quoteRef: description: Identifies this offer. Accepting it must name this value. type: string required: - legIndex - attempt - compared - acceptedAmount - boundAmount - freshAmount - quoteRef - expiresAt type: object FundsLocation: description: >- Where a leg's funds are when the leg does not run. Tagged on `holder` so later holders (a venue-held balance, for example) are additive variants rather than a new vocabulary. New values may be added; treat unknown values as other. oneOf: - description: In the taker's own wallet, where they can sign with the funds again. properties: address: description: The wallet, when the order records it. type: - string - 'null' funds: $ref: '#/components/schemas/AssetAmountDisplay' holder: description: New values may be added; treat unknown values as other. enum: - yourWallet type: string x-extensible-enum: true required: - funds - holder type: object - description: >- In another wallet the route recorded as its recipient, such as the end user of a broker's order. The taker cannot re-sign with these funds. properties: address: type: string funds: $ref: '#/components/schemas/AssetAmountDisplay' holder: description: New values may be added; treat unknown values as other. enum: - recipientWallet type: string x-extensible-enum: true required: - funds - address - holder type: object - description: >- In a platform contract (a router, an arrival contract or an escrow), pending a release the platform or an operator performs. properties: contract: type: - string - 'null' funds: $ref: '#/components/schemas/AssetAmountDisplay' holder: description: New values may be added; treat unknown values as other. enum: - platform type: string x-extensible-enum: true required: - funds - holder type: object - description: >- In the route's own balance at a CEX venue, on the CEX ledger. Only this route's trade or its pre-signed payout spends it: the taker retries the trade from it on the same order, or stops and the payout withdraws it. properties: funds: $ref: '#/components/schemas/AssetAmountDisplay' description: The asset and its `available` amount, read from the ledger. holder: description: New values may be added; treat unknown values as other. enum: - yourVenueBalance type: string x-extensible-enum: true routeId: description: The ledger route the balance is scoped to, `bytes32` hex. type: string venueId: description: The venue's registry id. type: string required: - venueId - routeId - funds - holder type: object - description: >- The native owner accepted the move, but no holder has issued a qualified receipt. Reported transit is never a destination balance; references stay in Money's envelope. properties: funds: $ref: '#/components/schemas/AssetAmountDisplay' description: >- The asset and amount reported in transit, without a destination or native reference. holder: description: New values may be added; treat unknown values as other. enum: - inTransit type: string x-extensible-enum: true required: - funds - holder type: object - description: >- Fiat debited by the venue onto a bank rail, not yet confirmed received, including overdue or manual-review payouts. References stay in Money's evidence envelope. properties: funds: $ref: '#/components/schemas/AssetAmountDisplay' description: >- The asset and amount on the bank rail, without a destination or native reference. holder: description: New values may be added; treat unknown values as other. enum: - bankRail type: string x-extensible-enum: true required: - funds - holder type: object - description: >- In a treasury account the workspace controls that is not route-scoped: a custodian account or wallet, an organisation wallet, or an ordinary LP/venue account. The order's own signing wallet stays `yourWallet`; producers choose from the order record. properties: accountId: $ref: '#/components/schemas/InventoryAccountId' description: >- The opaque inventory id, never a native vault, connection or venue-account id. funds: $ref: '#/components/schemas/AssetAmountDisplay' holder: description: New values may be added; treat unknown values as other. enum: - account type: string x-extensible-enum: true required: - accountId - funds - holder type: object x-extensible-enum: true StopReason: description: |- Why a route stopped waiting on its taker. New values may be added; treat unknown values as other. enum: - waitLimitReached - stoppedByYou - continuationComplianceRefused type: string x-extensible-enum: true AssetAmountDisplay: description: Raw and normalized amount for one asset side. properties: asset: $ref: '#/components/schemas/AssetDisplay' decimalAmount: type: - string - 'null' rawAmount: type: - string - 'null' unresolved: oneOf: - type: 'null' - $ref: '#/components/schemas/AmountUnresolved' description: Why `decimalAmount` is absent; absent whenever it is present. required: - asset type: object VenueTradeFillFee: properties: amount: description: Exact decimal, present when the venue reported a fee amount. type: - string - 'null' asset: description: Present exactly when `amount` is. type: - string - 'null' basis: description: >- The venue contract clause, present only when the fee is in the price. type: - string - 'null' lines: description: >- Separate native charges, positive for a fee and negative for a rebate. Outcome amounts already include them in their respective assets. items: $ref: '#/components/schemas/VenueRfqQuoteFee' type: - array - 'null' tradeFeeReport: oneOf: - type: 'null' - $ref: '#/components/schemas/VenueTradeFeeReport' description: Present only when the fee is in the price. treatment: $ref: '#/components/schemas/VenueTradeFeeTreatment' required: - treatment type: object TradeLegFacts: description: The leg facts an order read carries on `OrderLegInfo.tradeLeg`. properties: boundLapsesAt: description: >- Deposit first: the instant the consented bound stops authorizing the trade, 3× the deposit's expected arrival in the rail's business time. Absent on a leg without a deposit-first bound. format: date-time type: - string - 'null' confirmAgainReason: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLegConfirmAgainReason' description: >- Why a deposit-first pay-in in `price_beyond_bound` waits for a new consent. consentedPayoutFee: description: >- The exact fee bound recorded by Confirm, derived from immutable consent. type: - string - 'null' creditedAmount: description: The venue-credited amount that funded this pay-in, exact decimal. type: - string - 'null' currentPayoutFee: description: >- The qualified estimate observed when dispatch stopped for a fee rise. type: - string - 'null' declaredPayoutFee: description: >- Current qualified withdrawal estimate, returned by prepare in the receipt asset. An absent estimate never means a zero fee. type: - string - 'null' destination: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLegDestination' direction: $ref: '#/components/schemas/TradeLegDirection' expectedArrivalAt: format: date-time type: - string - 'null' expectedArrivalSource: description: '`provider` or `default`.' type: - string - 'null' finality: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLegFinality' description: >- Whether a settled payout can still be returned. Absent for an unsettled leg or a settled leg without a provider return watch. fundingDeadlineAt: format: date-time type: - string - 'null' fundingModel: oneOf: - type: 'null' - $ref: '#/components/schemas/FundingModel' description: >- A bank leg's funding model, fixed when it was planned. Absent on a chain leg. fundsReceivedAt: description: The venue's own credit time of that amount. format: date-time type: - string - 'null' holidaysApplied: type: - boolean - 'null' legId: format: uuid type: string outcomeCode: description: The named reason on a refused, cancelled or returned leg. type: - string - 'null' overdueAt: format: date-time type: - string - 'null' overdueSince: format: date-time type: - string - 'null' ownBankVerification: oneOf: - type: 'null' - $ref: '#/components/schemas/OwnBankVerification' description: >- Independent bank evidence, never the venue-reported settlement state. payoutApproval: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLegPayoutApproval' payoutBreakdown: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLegPayoutBreakdown' description: >- A payout's amounts in its asset (operator 2026-10-22: every fee-bearing action shows what leaves the account, the fee and what arrives). Absent on a pay-in and on a payout with no consent yet. payoutBreakdownUnavailableReason: description: >- A payout whose fee/charging declaration could not be read. Never means no fee. type: - string - 'null' payoutHeldReason: description: >- The funding-stage refusal code holding this planned payout: FUNDING_STAGE_DISABLED, EXECUTION_STOPPED, PILOT_PAYOUT_CAP_EXCEEDED, PILOT_DAILY_CAP_EXCEEDED or EXECUTION_NOTIONAL_UNVALUED. The leg stays planned and is retried; absent when not held. type: - string - 'null' quotedExpectedArrivalAt: description: The confirmed quote's estimate for this exact bank rail and option. format: date-time type: - string - 'null' rail: oneOf: - type: 'null' - $ref: '#/components/schemas/FiatRail' description: >- A bank leg's rail (`eft`, `sepa`, ...), fixed when it was planned. Absent on a chain leg. railOption: oneOf: - type: 'null' - $ref: '#/components/schemas/FiatRailOptionKind' description: The rail option the bank leg uses (`standard` or `fast`). railReference: oneOf: - type: 'null' - $ref: '#/components/schemas/PayoutRailReference' description: >- A genuine bank rail reference or named not-reported state; absent on non-bank-payout legs. recipientConfirmation: oneOf: - type: 'null' - $ref: '#/components/schemas/PayoutRecipientConfirmation' description: >- The receiving workspace's assertion, never settlement or independent verification. returnWindowEndsAt: description: >- For a returnable leg whose rail documents a return window, midnight after its last day in the rail's clearing time zone. Absent when no window is documented; never estimated. format: date-time type: - string - 'null' returnedAfterSettlement: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLegReturnedAfterSettlement' description: >- A settled payout the provider later returned. The leg stays `settled` (its row is immutable); the PayoutReturned review item is the one fact, and resolving that review keeps this annotation. returnedTo: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLegReturnedTo' reviewAt: format: date-time type: - string - 'null' reviewEnteredAt: format: date-time type: - string - 'null' reviewItemId: type: - string - 'null' reviewReason: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeLegReviewReason' settlementRail: $ref: '#/components/schemas/TradeLegRail' state: $ref: '#/components/schemas/TradeLegState' submittedAt: format: date-time type: - string - 'null' transactionHash: type: - string - 'null' venueReportedCredited: description: >- Only an explicit receiving-bank credit report from the venue; withdrawal completion is not credit. type: - boolean - 'null' venueWithdrawalId: description: >- A wallet payout's withdrawal as the venue recorded it, once sent: the venue's own withdrawal id and the chain transaction. Absent before the send and on a bank leg. type: - string - 'null' required: - legId - direction - settlementRail - state type: object VenueTradePriceBasis: description: New values may be added; treat unknown values as other. enum: - market_convention - receipt_per_debit type: string x-extensible-enum: true VenueFillQuantityGroup: description: >- Currency identity remains venue/site scoped; different pairs are never netted together. properties: executionTypeId: description: The execution type whose recorded quantities are grouped. type: string filledRequestCount: format: int64 minimum: 0 type: integer inputAmount: type: string inputAsset: type: string outputAmount: type: string outputAsset: type: string providerSite: type: string required: - executionTypeId - providerSite - inputAsset - outputAsset - filledRequestCount - inputAmount - outputAmount type: object FillSource: description: New values may be added; treat unknown values as other. enum: - protocol - venue_account type: string x-extensible-enum: true SolverStatus: description: |- Solver operational status and conformance lifecycle. State machine: ```text Registered → Validating Validating → Active | Inactive Active → Validating | Paused | Disabled Inactive → Validating | Disabled Paused → Validating | Disabled Disabled → ∅ (terminal; only a TetraFi administrator can re-enable it) ``` New values may be added; treat unknown values as other. enum: - registered - validating - active - inactive - paused - disabled type: string x-extensible-enum: true AssetDisplay: description: Display identity for one token/asset. properties: address: type: - string - 'null' assetId: type: string chainId: format: int64 minimum: 0 type: - integer - 'null' chainRef: type: - string - 'null' decimals: format: int32 minimum: 0 type: - integer - 'null' name: type: - string - 'null' resolutionStatus: $ref: '#/components/schemas/AssetResolutionStatus' symbol: type: string required: - assetId - symbol - resolutionStatus type: object RepricedSide: description: >- Which side of a leg a re-price compares. A StableFX leg re-quotes to the exact output and bounds the INPUT it spends; RFQ and solver legs bound the OUTPUT they deliver. New values may be added; treat unknown values as other. enum: - input - output type: string x-extensible-enum: true InventoryAccountId: description: >- Opaque inventory account id. Never a native vault, connection or venue-account id. examples: - acct_0123456789abcdef0123456789abcdef pattern: ^acct_[0-9a-f]{32}$ type: string AmountUnresolved: description: >- Why a side carries no decimal amount. Present exactly when `decimalAmount` is absent, so an unresolved side is a named state and never a guessed or missing number. New values may be added; treat unknown values as other. enum: - assetNotInRegistry - amountUnavailable type: string x-extensible-enum: true VenueRfqQuoteFee: properties: amount: type: string asset: type: string required: - amount - asset type: object VenueTradeFeeReport: description: >- What the native trade record carried in its own fee field when the fee is included in the price. `not_reported` is an absent field, never a zero fee. New values may be added; treat unknown values as other. enum: - not_reported - reported type: string x-extensible-enum: true VenueTradeFeeTreatment: description: >- How a fill's fee is known. `not_qualified` means the venue driver does not yet classify fee reporting: it is neither a zero fee nor "not reported". New values may be added; treat unknown values as other. enum: - included_in_price - reported - separate_charges - not_qualified type: string x-extensible-enum: true TradeLegConfirmAgainReason: description: >- Why a deposit-first pay-in needs a new consent: the fresh price missed the consented minimum receipt, or the bound lapsed before the deposit was credited. New values may be added; treat unknown values as other. enum: - priceBeyondBound - boundLapsed type: string x-extensible-enum: true TradeLegDestination: description: |- Where a payout leg delivers, by reference only: never bank or chain coordinates. properties: approvalId: description: The venue destination approval a wallet delivery goes through. format: uuid type: - string - 'null' kind: $ref: '#/components/schemas/TradeLegDestinationKind' ref: description: The wallet id or the Treasury Destination id. type: string required: - kind - ref type: object TradeLegDirection: description: >- Whether the leg brings money to the LP account before the trade, or takes the trade's output away from it. New values may be added; treat unknown values as other. enum: - pay_in - payout type: string x-extensible-enum: true TradeLegFinality: description: >- A settled payout's finality, from its return watch and any recorded payout-return review. New values may be added; treat unknown values as other. enum: - final - returnable - returnedAfterSettlement type: string x-extensible-enum: true FundingModel: description: >- What backs execution. A venue declares `prefunded` or `payIn`; `credit` is derived per trade (never declared or chosen): the trade creates or increases a negative position on the venue account, and `creditPortion` names how much. New values may be added; treat unknown values as other. enum: - prefunded - payIn - credit type: string x-extensible-enum: true OwnBankVerification: properties: credit: oneOf: - type: 'null' - $ref: '#/components/schemas/OwnBankVerifiedCredit' lastGoodReadAt: format: date-time type: - string - 'null' matchedBy: oneOf: - type: 'null' - $ref: '#/components/schemas/OwnBankVerificationMatchedBy' reason: type: - string - 'null' reviewItemId: type: - string - 'null' source: $ref: '#/components/schemas/OwnBankVerificationSource' state: $ref: '#/components/schemas/OwnBankVerificationState' required: - state - source type: object TradeLegPayoutApproval: description: >- Treasury's existing Run approval for a bank payout. No funds are reserved while this approval is pending; release rechecks balances and terms. properties: approvalRequestId: format: uuid type: - string - 'null' approvalsRequired: format: int32 minimum: 0 type: integer approverGroup: type: - string - 'null' approverGroupName: type: - string - 'null' approverNames: items: type: string type: array runId: format: uuid type: - string - 'null' required: - approvalsRequired - approverNames type: object TradeLegPayoutBreakdown: description: >- What a payout takes from the venue account, its fee and what arrives, as exact decimals in the leg's asset. The venue sends gross minus fee. With on-top charging the account loses gross and the bank receives the amount sent; with deducted charging the bank receives one fee less; when unverified, withdrawn is the maximum debit and receivedMin to receivedMax bounds the receipt. properties: basis: $ref: '#/components/schemas/TradeLegPayoutBreakdownBasis' description: The withdrawal record these amounts come from. charging: oneOf: - type: 'null' - $ref: '#/components/schemas/FiatFeeCharging' description: >- How the venue charges a bank payout's fee, as its rail declares it (`deducted`, `on_top`, `unverified`). Absent on a wallet payout, whose fee is Confirm's bound rather than a declared rail fee. fee: description: |- The most fee: a bank payout's declared payout fee (frozen by the withdrawal review once there is one), else Confirm's fee bound. type: string receivedMax: description: The most that arrives. type: string receivedMin: description: The least that arrives. type: string withdrawn: description: 'The most leaving the venue account: the confirmed trade''s output.' type: string required: - withdrawn - fee - receivedMin - receivedMax - basis type: object FiatRail: type: string FiatRailOptionKind: description: |- A way of using a rail. Every rail has a `standard` option; VALR's fast payout (Blitz over RTC) is the EFT rail's `fast` option. New values may be added; treat unknown values as other. enum: - standard - fast type: string x-extensible-enum: true PayoutRailReference: description: New values may be added; treat unknown values as other. oneOf: - properties: state: description: New values may be added; treat unknown values as other. enum: - not_reported_yet type: string x-extensible-enum: true required: - state type: object - properties: kind: $ref: '#/components/schemas/PayoutRailReferenceKind' state: description: New values may be added; treat unknown values as other. enum: - reported type: string x-extensible-enum: true value: type: string required: - kind - value - state type: object x-extensible-enum: true PayoutRecipientConfirmation: properties: confirmationId: format: uuid type: string confirmedAt: format: date-time type: string confirmedBy: description: '`user:` or `key:`; immutable authenticated identity.' type: string confirmedByName: description: A safe name captured at confirmation, never an email address. type: string legId: format: uuid type: string required: - confirmationId - legId - confirmedBy - confirmedByName - confirmedAt type: object TradeLegReturnedAfterSettlement: description: |- A return the provider reported after the payout leg settled, read from its entry-coupled PayoutReturned review item. properties: detectedAt: description: When TetraFi's own status read first saw the return. format: date-time type: string reviewItemId: description: The PayoutReturned review item support works the return from. type: string required: - reviewItemId - detectedAt type: object TradeLegReturnedTo: description: |- Where a returned leg's funds remain, according to its dispatch backend. New values may be added; treat unknown values as other. enum: - lpAccount - providerBalance type: string x-extensible-enum: true TradeLegReviewReason: description: |- The reason a leg requires review. New values may be added; treat unknown values as other. enum: - uncertain_send - ambiguous_event - expected_arrival_exceeded - provider_failed_after_send - trade_fill_requires_review - late_funds_held - late_funds_worse_rate - amount_mismatch type: string x-extensible-enum: true TradeLegRail: description: |- How the leg settles: a bank rail or a chain transfer. New values may be added; treat unknown values as other. enum: - bank - chain type: string x-extensible-enum: true TradeLegState: description: |- The leg's state. The last five are terminal. New values may be added; treat unknown values as other. enum: - planned - awaiting_funds - funds_received - price_beyond_bound - expired_unfunded - late_funds - awaiting_approval - dispatching - uncertain - in_transit - held_by_provider - refunding - manual_review - settled - returned - refunded - cancelled - refused type: string x-extensible-enum: true AssetResolutionStatus: description: |- Whether the backend resolved the asset to known display metadata. New values may be added; treat unknown values as other. enum: - resolved - unknown type: string x-extensible-enum: true TradeLegDestinationKind: description: |- What a payout leg delivers to, in the binding's endpoint vocabulary. New values may be added; treat unknown values as other. enum: - wallet - bankDestination type: string x-extensible-enum: true OwnBankVerifiedCredit: properties: amount: description: Exact decimal text, never a floating-point approximation. type: string creditedAt: format: date-time type: string currency: type: string referenceMasked: type: - string - 'null' required: - amount - currency - creditedAt type: object OwnBankVerificationMatchedBy: description: New values may be added; treat unknown values as other. enum: - referenceAndAmount - amountAndWindow type: string x-extensible-enum: true OwnBankVerificationSource: description: New values may be added; treat unknown values as other. enum: - revolutBusiness type: string x-extensible-enum: true OwnBankVerificationState: description: New values may be added; treat unknown values as other. enum: - verified - notSeen - unavailable - disagreement type: string x-extensible-enum: true TradeLegPayoutBreakdownBasis: description: |- Which record a payout breakdown comes from. New values may be added; treat unknown values as other. enum: - consent - reviewed type: string x-extensible-enum: true FiatFeeCharging: description: >- How a scheduled bank fee is charged. unverified remains conservative until a real movement measures it; the recipient can only receive more than the quoted minimum. New values may be added; treat unknown values as other. enum: - deducted - on_top - unverified type: string x-extensible-enum: true PayoutRailReferenceKind: description: New values may be added; treat unknown values as other. enum: - swift_uetr - sepa_end_to_end_id - faster_payments_reference - bank_rail_reference type: string x-extensible-enum: true securitySchemes: api_key: description: >- Send the API key in `X-API-Key`. **Request signing.** A key with signing enabled (`POST /api/v1/workspaces/{workspaceId}/users/me/api-keys/{keyId}/signing`, which returns the signing secret once) must also sign every request: - `X-Timestamp`: the current Unix time in seconds, within 300 seconds of the server clock. - `X-Signature`: lower-case hex HMAC-SHA256 of the canonical string, keyed with the signing secret's 32 bytes (the secret is 64 hex characters; decode it first). The canonical string is four lines joined by `\n`, with no trailing newline: the `X-Timestamp` value, the upper-case method, the path with its query exactly as sent (`/api/v1/orders?limit=1`), and the lower-case hex SHA-256 of the exact body bytes (the SHA-256 of an empty body when there is none). A write's signature (POST, PUT, PATCH, DELETE) is accepted once: sending the same signed write again is refused, so a retry signs again. A read (GET, HEAD) changes nothing, so an identical signed read inside the window is admitted again and polling needs no nonce. A signing refusal is a 401 `AUTH_REQUIRED` whose `details.reason` names the cause: `SIGNATURE_REQUIRED` (a header is missing), `SIGNATURE_INVALID` (a malformed header or a wrong signature), `TIMESTAMP_OUT_OF_RANGE` or `SIGNATURE_REPLAYED`. in: header name: X-API-Key type: apiKey x-request-signing: algorithm: HMAC-SHA256 canonicalRequest: - timestamp - method - pathWithQuery - bodySha256Hex canonicalSeparator: |+ oneTimeMethods: - POST - PUT - PATCH - DELETE refusal: error: AUTH_REQUIRED reasons: - SIGNATURE_REQUIRED - SIGNATURE_INVALID - TIMESTAMP_OUT_OF_RANGE - SIGNATURE_REPLAYED status: 401 secretEncoding: hex signatureEncoding: hex-lower signatureHeader: X-Signature timestampHeader: X-Timestamp timestampWindowSeconds: 300 bearer_auth: bearerFormat: JWT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.