Submit a transfer
Submits a transfer (transfers:propose; a member’s — an API key is refused 403): an amount of one asset from one account’s wallet to another’s — on a chain between two venues, or with none between two wallets of one account. The Idempotency-Key becomes its clientTransferId. Answers 201 with the transfer: QUEUED, or PENDING_APPROVAL where it awaits a second person. Takes no If-Match.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Headers
Required on every write: a URL-safe string of 1 to 64 characters from [A-Za-z0-9._~-] (a UUID fits), scoped to you. It names one operation on one record, ever: a retry replays the stored outcome (Idempotent-Replay: true) or attaches to the live one, and reuse on another record refuses 409 IDEMPOTENCY_KEY_REUSED. Missing or malformed, 400.
Your own id for the request: 8 to 128 of [A-Za-z0-9._-]. It becomes the request’s id and is echoed on the response. A value off that grammar is replaced with a fresh id, never refused.
Query parameters
A position you hold — an X-Immix-Global-Sequence you read, or a 202’s commandGlobalSequence: this member answers only once it has folded the platform’s stream through it, waiting up to its deadline, then 503 PROJECTION_BEHIND with Retry-After. Within that stream a read is never older than what you have seen; drop your positions after an announced stream cut. A retry stating its 202’s position attaches to or replays that operation while the journal holds its key, never publishing twice. Stated once: one to nineteen digits, at most 9223372036854775807; else 400 MALFORMED_REQUEST.
Request
The account the value leaves — one of your organisation’s, ACTIVE.
The wallet the value leaves, as the venue names it (funding, trading, a vault’s wallet); US-ASCII, at most 64 bytes.
The account the value reaches — the source account itself for a move between two of its wallets.
The wallet the value reaches, as the venue names it; US-ASCII, at most 64 bytes.
The asset to move — one your organisation holds an asset policy for.
money (a decimal string in the asset’s own units): the amount to move, above 0. The fee is charged beside it, never taken from it.
The network to settle on, for a transfer between two venues — the destination needs a verified address on it. Omit it, or send null, for a move between two wallets of one account.
State true to send a move out of a margin wallet that the headroom check refuses — 409 EXCEEDS_MARGIN_HEADROOM: more than the account’s margin wallets could shed and stay inside its risk limits; 409 HEADROOM_UNKNOWN: that cannot be evaluated — and to record that you did: kept on the transfer (isHeadroomAcknowledged) for its approver. It is recorded only where the check refuses the move: stated on any other move it changes nothing, and the transfer does not show it. false when absent.
A note for the transfer’s approvers; US-ASCII, at most 256 bytes.
Response
The transfer exists — QUEUED, or PENDING_APPROVAL where it awaits a second person — with the answering change’s position, its ETag and, on a replayed key, Idempotent-Replay.
The transfer’s id, a 64-bit integer as decimal digits.
The transfer’s version as a decimal string: 1 at the submit, one more on every change; its ETag, which an approval, a withdrawal and a resolution state as If-Match.
PENDING_APPROVAL: submitted, awaiting a second person. QUEUED: admitted, waiting for the venue. INSTRUCTED: the venue accepted it. PENDING_PROVIDER_APPROVAL: the custodian’s own approvers must act. IN_TRANSIT: broadcast on its chain. SETTLED, FAILED, WITHDRAWN: closed. RESOLVED_SETTLED, RESOLVED_FAILED: closed by hand. The value set is append-only: read an unknown value as UNKNOWN.
What this version records: the SUBMIT; an APPROVE counted, or the one that admitted it (QUEUE); a WITHDRAW; the venue’s INSTRUCT, PROVIDER_HOLD and PROVIDER_RELEASE; an OBSERVE — a broadcast, more confirmations, a deposit seen and held; ARRIVE, SETTLE, FAIL; SLA_BREACH — it went overdue; a RESOLVE proposed, approved or concluded; CONTRADICT; RISK_HOLD and RISK_RELEASE. Append-only: read an unknown value as UNKNOWN.
The account the value leaves (GET /accounts).
The wallet the value leaves, as the venue names it — funding, trading, a vault’s wallet.
The account the value reaches — the source account on a move between two of its wallets.
The network an on-chain transfer settles on; null for a move between two wallets of one account, which crosses none. UNKNOWN: an on-chain transfer on a network this member cannot name yet — it runs a build older than the network — never a move between two wallets. The value set is append-only: a name you do not know is still a network.
money (an exact decimal string at the scale the submit stated it): the amount instructed, in the asset’s own units. The fee is not inside it.
money (an exact decimal string at the scale it was stated at): the fee the venue stated, in the asset feeAssetId names; null until the venue states one.
The asset feeAmount is stated in: the fee asset named by the chain policy the transfer was admitted under — the moved asset where that policy names none, and for a move between two wallets of one account. Stated on every row, whether or not the venue has stated a fee yet; it moves only if an approval admits the transfer under a chain policy amended since the submit.
money (an exact decimal string at the scale it was stated at): what the destination credited, net of fees; null until the destination reports a credit — or, on a transfer resolved SETTLED by hand, until that resolution is approved.
The highest confirmation count either end of the transfer has reported; 0 until one is.
The key that executes the transfer (GET /accounts/{id}/keys): the account’s own key for a move between its wallets, the source account’s transfers key for an on-chain one.
The destination’s verified address the transfer was admitted to (GET /account-addresses); null for a move between two wallets.
The venue’s own id for the withdrawal or transfer, once it accepted it; empty until then.
The on-chain transaction hash, once broadcast or stated by an approved resolution; empty otherwise.
Why the transfer failed. The venue’s refusal by name — INSUFFICIENT_FUNDS, ADDRESS_NOT_ALLOWLISTED, BELOW_MINIMUM, ABOVE_LIMIT, ASSET_SUSPENDED, PERMISSION_DENIED, PROVIDER_DENIED — or the platform’s own before it instructed the venue: AMOUNT_PRECISION (an amount the venue’s precision cannot carry), FEE_ABOVE_POLICY (the venue’s fee above the chain policy’s maxFeeAmount); else VENUE_ERROR or TIMEOUT. UNKNOWN while it has not failed. Append-only.
The venue’s own text behind failureReason; empty unless it failed.
Whether the transfer’s current leg has run past its deadline (slaDeadlineNs); cleared when the leg advances. An overdue QUEUED or PENDING_PROVIDER_APPROVAL transfer may be resolved by hand.
The leg that went overdue: ACTION — the venue’s acceptance, or a move between two wallets; PROVIDER — the custodian’s own approvers; CHAIN — from the instruction to the destination first seeing the deposit; HELD — a deposit seen at its destination and not yet credited. UNKNOWN while on time.
The leg whose deadline is running now, as overdueLeg names them; UNKNOWN while the transfer awaits approval and once it is closed.
When the running leg’s deadline falls, epoch nanoseconds; null when none runs.
Whether the destination shows the deposit but has not credited it yet; holdDetail says why, where the venue does.
The destination’s own text behind a held deposit; empty when none.
Whether the fee the venue charged exceeded the chain policy’s maxFeeAmount.
Whether the submit overrode the headroom check: its maker stated acknowledgeHeadroom and the check refused the move without it — capital taken out of a margin wallet knowingly. Each approval states its own in approvals.
Whether the transfer, queued out of a margin wallet, is held because its account’s posture is BLOCKED (GET /risk/postures): nothing instructs the venue until the posture leaves BLOCKED. Its deadline keeps running.
Whether the venue completed or failed this transfer after it was resolved by hand; the status is unchanged.
The version of the organisation’s asset policy the transfer was admitted under (GET /asset-policies) — at the submit, or at the approval that admitted it.
The version of the chain policy it was admitted under (GET /chain-policies); null for a move between two wallets, which reads none.
The submit’s Idempotency-Key, the caller’s own handle for the transfer: taken while the transfer is open and for 24 hours after it closes.
When it was submitted, epoch nanoseconds; never moves.
Who submitted it — the one principal whose later submit under clientTransferId is a retry of this transfer.
When it became QUEUED, epoch nanoseconds; null before.
When the venue accepted the instruction, epoch nanoseconds; null before.
When the destination first reported the deposit held, epoch nanoseconds; null if it never did.
When the transfer settled — by the venue’s word, the destination’s credit or an approved resolution — epoch nanoseconds; null before.
The maker of the transfer’s last proposal — the submit, or a resolution — kept once it concludes or is withdrawn.
What awaits approval: SUBMIT — the transfer itself, while PENDING_APPROVAL; RESOLVE — a resolution by hand, whose content is resolveOutcome, evidenceKind, evidence, proposedSettledAmount and proposedTxId; UNKNOWN when nothing does. The inbox (GET /approvals) lists the two as ACTIVATE and AMEND.
When the last proposal concluded, epoch nanoseconds — at the submit itself where nothing needed approving; null while it pends and after a withdrawal.
Who concluded it — the maker where nothing needed approving, else the approver whose approval met the count; null when concludedAtNs is.
What the last proposal proposed, kept once it concluded: SUBMIT or RESOLVE; UNKNOWN while it pends, or when it was withdrawn.
Who approved the transfer’s last proposal and when, in approval order; empty until the first approval. A submit concludes when they number the organisation’s transfers rule in force at that approval (GET /approval-rules?family=TRANSFERS); a resolution needs at least one, whatever the rule.
The maker’s note on the submit, for its approvers; empty when none — and once a resolution by hand is proposed, whose maker’s words are evidence.
Who made the last withdrawn proposal; null when none was.
Who withdrew it — the maker, or an approver; null when none was.
When it was withdrawn, epoch nanoseconds; null when none was.
Why it was withdrawn, as the withdrawer stated it; empty when none was.
What a resolution by hand proposes while it pends, or closed the transfer as once approved; UNKNOWN when none was ever proposed.
What the resolution rests on: VENUE_SETTLED — the venue shows the transfer complete; VENUE_CANCELLED, VENUE_FAILED; VENUE_NO_RECORD — the venue holds nothing under the transfer’s reference. UNKNOWN when no resolution was proposed.
What the resolution’s maker saw at the venue, in their words; empty when none was proposed.
money (an exact decimal string at the scale it was stated at): what a pending SETTLED resolution states arrived, applied to settledAmount when it is approved; null when it states none — the destination’s own figure stands, else the whole amount — and when no resolution pends.
The transaction hash a pending resolution states, applied to txId when it is approved; empty when it states none.
Who produced this version: the principal behind a submit, an approval, a withdrawal or a resolution — or the platform (MACHINE) on a venue’s report, a deadline passing or a risk hold.
The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.