Get order

Returns the latest stored order after a provider refresh. For REST polling, wait 10–15 seconds between reads and honor Retry-After on 429; do not poll in a tight loop. After a webhook delivery, perform this GET to obtain the complete current projection. Never put an API key in a URL. Terminality is order-kind dependent: route and atomic venue orders normally complete at settled, while claim-based or deferred products may advance to finalized.

GET /api/v1/orders/{orderId}

Get an order

cURL

curl --request GET \
  --url https://api.tetrafi.io/api/v1/orders/{orderId} \
  --header 'X-API-Key: <api-key>'

200

{
  "deliverTo": {
    "accountKind": "venueAccount",
    "displayName": "<string>",
    "financialAccountId": "<string>",
    "isDefault": true,
    "kind": "financialAccount",
    "network": "eip155:8453"
  },
  "fundingAccount": {
    "financialAccountId": "<string>",
    "kind": "venueAccount",
    "linkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "fundingModel": "prefunded",
  "settlement": {
    "method": "venueLedger",
    "timing": "immediate",
    "window": {
      "cadence": {
        "dayBasis": "calendarDays",
        "kind": "intraday",
        "everyHours": 1,
        "localTimes": [
          "<string>"
        ]
      },
      "scheduleId": "<string>",
      "scheduleLabel": "<string>",
      "scheduleVersion": 123,
      "snapshotAt": "2023-11-07T05:31:56Z",
      "windowId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "assumedBoundary": {
        "lpName": "<string>",
        "source": "<string>",
        "timeZone": "<string>"
      },
      "cutoffAt": "2023-11-07T05:31:56Z",
      "paymentDeadlineAt": "2023-11-07T05:31:56Z",
      "settlementBasis": "clock",
      "settlesBy": "2023-11-07T05:31:56Z",
      "statementIssuer": "<string>"
    }
  },
  "tradingSource": {
    "financialAccountId": "<string>",
    "kind": "venueAccount",
    "venueEnablementId": "<string>"
  },
  "fees": [
    {
      "amount": "<string>",
      "asset": "<string>",
      "includedInPrice": true,
      "kind": "trading",
      "chain": "<string>"
    }
  ],
  "fills": [
    {
      "amount": "<string>",
      "at": "2023-11-07T05:31:56Z",
      "fillId": "<string>",
      "price": {
        "amount": "<string>",
        "base": "<string>",
        "quote": "<string>"
      },
      "sellAmount": "<string>",
      "venue": {
        "id": "<string>",
        "name": "<string>"
      },
      "network": "<string>",
      "txHash": "<string>"
    }
  ],
  "quotedBuyAmount": "<string>",
  "settledBuyAmount": "<string>",
  "settlesBy": "2023-11-07T05:31:56Z",
  "unrecordedFees": [
    "trading"
  ],
  "operation": {
    "bounds": {
      "buy": {
        "amount": "10000",
        "asset": "USDC",
        "chain": "eip155:8453"
      },
      "maximumFees": [
        {
          "asset": "<string>",
          "maximumAmount": "<string>"
        }
      ],
      "sell": {
        "amount": "10000",
        "asset": "USDC",
        "chain": "eip155:8453"
      },
      "buyAmount": "10000",
      "sellAmount": "10000"
    },
    "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAt": "2023-11-07T05:31:56Z",
    "executionStatus": "notSubmitted",
    "executionTypeId": "<string>",
    "initialReviewDisposition": "review_required",
    "label": "<string>",
    "operationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "providerSite": "<string>",
    "requestKey": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workspaceId": "<string>",
    "dispatch": {
      "claimedAt": "2023-11-07T05:31:56Z",
      "confirmationKey": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "confirmedQuoteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "updatedAt": "2023-11-07T05:31:56Z",
      "inputSpent": "<string>",
      "outcomeCode": "confirmed_fill",
      "outputReceived": "<string>",
      "quotedOutput": "<string>",
      "venueOrderId": "<string>"
    },
    "providerClientOrderId": "<string>",
    "quoteExpiresAt": "2023-11-07T05:31:56Z",
    "quoteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "quoteRequestId": "<string>",
    "requestedDeadline": "2023-11-07T05:31:56Z",
    "reviewRequestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "settlementStatus": "inProgress",
    "venueFilledAt": "2023-11-07T05:31:56Z"
  },
  "orderId": "<string>",
  "status": "pending",
  "statusUrl": "<string>",
  "terminal": true,
  "kind": "basicTrade",
  "creditCheck": {
    "activeHolds": "<string>",
    "available": "<string>",
    "availableSigned": "<string>",
    "checkedAt": "2023-11-07T05:31:56Z",
    "creditPortion": {
      "amount": "<string>",
      "currency": "<string>",
      "lineValue": "<string>"
    },
    "decision": "<string>",
    "effectiveLimit": "<string>",
    "exposureDelta": "<string>",
    "exposureReducing": true,
    "localHeadroom": "<string>",
    "lpAvailable": "<string>",
    "maxAgeMs": 1,
    "observationAgeMs": 1,
    "observationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "projectedUsed": "<string>",
    "source": "tetraFi",
    "termsVersion": 123,
    "used": "<string>",
    "valuationMaxAgeMs": 1,
    "venueAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "journalVersion": "<string>",
    "overLimitBy": {
      "amount": "<string>",
      "currency": "<string>",
      "lineValue": "<string>"
    },
    "positionsBasis": "<string>",
    "zeroAssets": [
      "<string>"
    ]
  },
  "creditPortion": {
    "amount": "<string>",
    "currency": "<string>",
    "lineValue": "<string>"
  },
  "creditReservation": {
    "debitAsset": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "exposureAmount": "<string>",
    "exposureCurrency": "<string>",
    "inputAmount": "<string>",
    "positiveInputAmount": "<string>",
    "reservationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "state": "reserved",
    "operationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "payIn": {
    "afterPayBy": {
      "action": "returned",
      "source": "<string>"
    },
    "payBy": {
      "clock": "payment_started",
      "seconds": 1
    },
    "settlementGrace": {
      "kind": "no_grace"
    }
  },
  "clientOrderId": "<string>",
  "next": {
    "kind": "order"
  },
  "quoteId": "<string>",
  "requestId": "<string>",
  "settlementCarriedInto": {
    "windowId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "settlesBy": "2023-11-07T05:31:56Z"
  },
  "settlementState": "settled",
  "settlementStatement": "pending"
}

Authorizations

api_keybearer_auth

X-API-Key · string · header · required

Send the API key in X-API-Key.

Request signing. A key with signing enabled (enabled for the key in its workspace's credential settings, which return the signing secret once; see Sign requests) must also sign every request:

• X-Timestamp: the current Unix time in seconds, within 300 seconds of the server clock (at most 10 seconds ahead of it on a request that sends X-Nonce).
• X-Nonce: a fresh random value for each request, 16 to 128 characters of A-Z, a-z, 0-9, - and _ (a UUID fits). Required on a write (POST, PUT, PATCH, DELETE); optional on a read (GET, HEAD).
• 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 joined by \n, with no trailing newline: the X-Timestamp value, the X-Nonce 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 request without X-Nonce (a read) omits the nonce line and signs four lines.

A nonce is accepted once per key: the same nonce again inside the window is refused, whatever the body, so two identical writes in one second each carry their own nonce and both succeed, and a retry signs again with a new nonce. Every API server shares one nonce record, so a nonce accepted by one server is refused by all of them. Rate admission runs first: a rate-limited write (429) does not consume its nonce, and a replay sent while the key is rate limited is answered 429; otherwise a replay spends a rate token and is refused. A read without a nonce changes nothing, so an identical signed read inside the window is admitted again. A write whose window has already passed on the nonce record's clock when its nonce is recorded is refused as TIMESTAMP_OUT_OF_RANGE. If the nonce record cannot be read or written the request is refused with 503 API_KEY_UNAVAILABLE; the nonce may have been consumed, so sign again with a new X-Timestamp and X-Nonce before retrying.

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, NONCE_REQUIRED (a write without X-Nonce), NONCE_INVALID (a malformed or repeated X-Nonce header), SIGNATURE_REPLAYED (the nonce was already accepted). SIGNATURE_PREDATES_RESTART and 429 REPLAY_WINDOW_FULL are reserved and not answered today.

Scopes

orders_read · api_key

orders_read · bearer_auth

Headers

X-Workspace-Id · string<uuid>

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

Path Parameters

orderId · string · required

Order ID

Response

200

application/json

Current Basic order. States may be skipped; act on terminal, not on a particular sequence.

Option 1

Option 2

The Basic venue trade created by POST /orders and read from its saved venue-trade operation. Common order identity and progress fields remain stable; undocumented response fields must be ignored.

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

deliverTo · object · required

A resolved destination includes observed presentation facts, unlike a request.

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

Option 1

Option 2

Show child attributes

fundingAccount · object · required

What backs execution. A link id appears only when money moves through that link.

Show child attributes

fundingModel · enum<string> · required

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.

Available options: prefunded, payIn, credit

settlement · object · required

The venue's declared terms and, for delayed timing, the account schedule's window.

Option 1

Option 2

Option 3

Show child attributes

tradingSource · object · required

The exact source selected for a quote, retained through execution and recovery.

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

Option 1

Option 2

Show child attributes

fees · object[] · required

The fees actually charged, as recorded: the venue's own fee report, bridge fees, network gas the order's wallet paid, and the platform fee. Never a quoted estimate. A fee whose amount was not reported or could not be read is left out rather than shown as 0, and its kind is listed in unrecordedFees.

Show child attributes

fills · object[] · required

Each confirmed fill, in execution order. Always present: empty before any fill is confirmed.

Show child attributes

quotedBuyAmount · string | null · required

The buy amount the executed quote said would land. Null when it is not known (for example before a venue order is dispatched).

settledBuyAmount · string | null · required

What actually landed, read from the fill or settlement evidence. Null until it is measured; never the quote carried forward and never 0 for unknown.

settlesBy · string<date-time> | null · required

The latest time the order settles, or can no longer execute, under its recorded terms: the signed order's fill deadline, or, on a route, the latest fill deadline every leg commits to (Advanced); the last on-chain step's send-by time (an on-chain Basic swap). Null when no such term is recorded, for example a same-chain DEX swap, whose call carries no deadline.

unrecordedFees · enum<string>[] · required

Every fee kind the order incurs whose actual charge is not recorded or could not be read: a venue fee taken inside the price without an amount, a bridge leg's fee, gas the order's wallet spent without a readable receipt, a platform fee billed off the order. Always present; empty only when every incurred charge is in fees. An absent kind with no fees line means nothing of that kind was charged. Open set: clients show an unknown kind generically.

What a fee paid for.

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

Available options: trading, relayer, forwarding, transfer, network, platform

operation · object · required

A prepared or placed Basic venue trade. Track it by operationId and connectionId; executionStatus describes the trade and settlementStatus describes any subsequent money movement. initialReviewDisposition is the original planning verdict, not current approval. Only the documented fields are part of the integrator contract; undocumented fields may be sent and must be ignored.

Show child attributes

orderId · string · required

The operation identifier accepted by GET /api/v1/orders/{orderId}.

status · enum<string> · required

Open public lifecycle vocabulary shared by both order kinds. States may be skipped; act on terminal, not on a particular sequence.

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

Available options: pending, working, filled, settled, unfilled, cancelled, failed, refunded, reviewRequired, outcomeUnknown, refused

statusUrl · string · required

Where to read this order (GET), with the orders_read API-key scope.

terminal · boolean · required

kind · enum<string> · required

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

Available options: basicTrade

creditCheck · null | object

The credit decision the funding was derived from: point-in-time evidence, never a reservation or dispatch authority. Present exactly when creditPortion is.

Show child attributes

creditPortion · null | object

A credit trade's exact credit portion: the part of the debit, in the debit asset, that creates or increases a negative position (the rest is spent from positives). Present exactly when fundingModel is credit.

Show child attributes

creditReservation · null | object

The firm ask's combined cash and credit hold on a credit venue account, held until the quote expires or its order adopts it. Absent on indicative cards.

Show child attributes

payIn · null | object

Show child attributes

clientOrderId · string | null

Caller reference supplied when this order was placed.

next · object

The one action the caller takes next; later legs run under the order.

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

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Show child attributes

quoteId · string | null

requestId · string | null

settlementCarriedInto · null | object

The later window the trade's amounts were netted into, which it now settles in by that window's settlesBy. Absent when nothing was netted.

Show child attributes

settlementState · null | enum<string>

Where the filled trade's settlement stands, beside its terms in settlement: settled at once for an immediate venue, a waiting or edge state while a delayed window settles. Absent before the fill and on a trade recorded without settlement terms.

Available options: settled, awaitingWindow, awaitingPayment, partiallySettled, overdue, disputed, failed, inTransit

settlementStatement · null | enum<string>

Whether the statement of the window the trade settles in is out: issued, pending or failed. Absent with settlementState, and on a trade that settles without a window.

Available options: pending, issued, failed