Skip to main content
POST
Submit a step of an order
Walkthrough: Place an order.

Authorizations

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_write

Headers

X-Workspace-Id
string<uuid>

The workspace the request acts in, for an operation whose path does not name one. Every API key is bound to exactly one workspace and implies it, so an API-key caller never needs this header; if sent, it must be that same id (another id answers 403 WORKSPACE_SCOPE_MISMATCH). A member session must send it (400 MISSING_WORKSPACE without it).

Idempotency-Key
string
required

Required.

TetraFi-Version
enum<string>

The dated API version to answer this request in. Without it, an API key's requests use the version the key pinned when it was created, and a member session uses the current version. A value that is not exactly one supported date answers 400 API_VERSION_UNSUPPORTED before anything runs. The response's TetraFi-Version header names the version used.

Available options:
2026-11-17

Path Parameters

orderId
string
required

The order's identifier

stepId
string
required

The step's stepId from the order's next.step

Body

application/json

How the client answers a step: the step's signed transaction for TetraFi to relay, the hash of one it broadcast itself, a typed-data signature, or a refusal to sign.

kind
enum<string>
required
Available options:
signedTransaction
raw
string
required

Response

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.

fundingAccount
object
required

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

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.

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.

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.

fills
object[]
required

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

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.

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.

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.

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.

payIn
null | object
signing
null | object

Who signs a Basic on-chain quote's wallet steps, with the first step when the client signs. Absent off-chain.

executionMethod
string
default:Unknown method

Human execution-method label, or Unknown method when it cannot be resolved.

venueId
string | null

Catalogue venue id; null when the recorded execution type cannot be resolved.

venueName
string
default:Unknown venue

Catalogue product name, or Unknown venue with the recorded id when unresolved.

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.

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.

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