Approve a transfer proposal
Adds one approval to the transfer’s pending proposal — its submit, or a resolution (transfers:approve); the maker cannot (403 SELF_APPROVAL), nor can anyone twice (409 ALREADY_APPROVED). The last approval a submit needs queues the transfer; a resolution’s closes it. Answers the transfer. A submit’s approval re-runs the headroom check; where it refuses (409), state acknowledgeHeadroom.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
The transfer’s id — a positive 64-bit integer as decimal digits.
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.
Required on every entity write: the ETag the read minted, quoted or bare — the version this write was computed against — or * to write unconditionally on purpose, except on a notification endpoint’s approval, which refuses * 400 INVALID_IF_MATCH. Absent is 428 PRECONDITION_REQUIRED; a weak validator 400 INVALID_IF_MATCH; a stale value 412 VERSION_CONFLICT (CONFIG_SEQ_CONFLICT on an algo’s config write) with currentVersion and a fresh ETag: re-read, reapply, retry. A * write overwrites every field from your copy, a colleague’s amend since your read included.
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
State true to approve a submit the headroom check refuses at your approval — 409 EXCEEDS_MARGIN_HEADROOM or HEADROOM_UNKNOWN, judged on the account as it stands now — and to record that you did: kept on your entry in the transfer’s approvals, and only where the check refuses your approval. false when absent.
Response
The transfer as the platform now holds it after the write — the same row the read serves, 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.