Skip to navigation

Withdraw a transfer proposal

Withdraws the transfer’s pending proposal, with a reason — its maker, or anyone holding transfers:approve. A transfer awaiting approval becomes WITHDRAWN and releases what it reserved; a pending resolution is dropped and the transfer stands as it was. Answers the transfer.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idstringRequired

The transfer’s id — a positive 64-bit integer as decimal digits.

Headers

Idempotency-KeystringRequired

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.

If-MatchstringRequired

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.

X-Request-IdstringOptional

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

minGlobalSequencestringOptionalformat: "^[0-9]{1,19}$"

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

This endpoint expects an object.
reasonstringOptional<=256 characters

Why the proposal is withdrawn, kept on the transfer; US-ASCII, at most 256 bytes.

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.

transferIdstringformat: "^-?[0-9]+$"

The transfer’s id, a 64-bit integer as decimal digits.

versionstringformat: "^-?[0-9]+$"

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.

statusenum

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.

transitionenum

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.

sourceAccountIdinteger

The account the value leaves (GET /accounts).

sourceWalletstring

The wallet the value leaves, as the venue names it — funding, trading, a vault’s wallet.

destAccountIdinteger

The account the value reaches — the source account on a move between two of its wallets.

destWalletstring
The wallet the value reaches, as the venue names it.
assetIdinteger
The asset moved.
chainenum or null

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.

Allowed values:
amountstringformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

feeAmountstring or nullformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

feeAssetIdinteger

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.

settledAmountstring or nullformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

confirmationsinteger

The highest confirmation count either end of the transfer has reported; 0 until one is.

executingCredentialIdinteger

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.

destAddressIdinteger or null

The destination’s verified address the transfer was admitted to (GET /account-addresses); null for a move between two wallets.

externalRefstring

The venue’s own id for the withdrawal or transfer, once it accepted it; empty until then.

txIdstring

The on-chain transaction hash, once broadcast or stated by an approved resolution; empty otherwise.

failureReasonenum

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.

failureDetailstring

The venue’s own text behind failureReason; empty unless it failed.

isOverdueboolean

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.

overdueLegenum

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.

Allowed values:
slaLegenum

The leg whose deadline is running now, as overdueLeg names them; UNKNOWN while the transfer awaits approval and once it is closed.

Allowed values:
slaDeadlineNsstring or nullformat: "^-?[0-9]+$"

When the running leg’s deadline falls, epoch nanoseconds; null when none runs.

isHeldAtDestinationboolean

Whether the destination shows the deposit but has not credited it yet; holdDetail says why, where the venue does.

holdDetailstring

The destination’s own text behind a held deposit; empty when none.

isFeeAbovePolicyboolean

Whether the fee the venue charged exceeded the chain policy’s maxFeeAmount.

isHeadroomAcknowledgedboolean

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.

isRiskHeldboolean

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.

isContradictedboolean

Whether the venue completed or failed this transfer after it was resolved by hand; the status is unchanged.

assetPolicyVersionstringformat: "^-?[0-9]+$"

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.

chainPolicyVersionstring or nullformat: "^-?[0-9]+$"

The version of the chain policy it was admitted under (GET /chain-policies); null for a move between two wallets, which reads none.

clientTransferIdstring

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.

submittedAtNsstringformat: "^-?[0-9]+$"

When it was submitted, epoch nanoseconds; never moves.

submittedByobject

Who submitted it — the one principal whose later submit under clientTransferId is a retry of this transfer.

queuedAtNsstring or nullformat: "^-?[0-9]+$"

When it became QUEUED, epoch nanoseconds; null before.

instructedAtNsstring or nullformat: "^-?[0-9]+$"

When the venue accepted the instruction, epoch nanoseconds; null before.

heldAtNsstring or nullformat: "^-?[0-9]+$"

When the destination first reported the deposit held, epoch nanoseconds; null if it never did.

settledAtNsstring or nullformat: "^-?[0-9]+$"

When the transfer settled — by the venue’s word, the destination’s credit or an approved resolution — epoch nanoseconds; null before.

proposedByobject

The maker of the transfer’s last proposal — the submit, or a resolution — kept once it concludes or is withdrawn.

pendingTransitionenum

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.

Allowed values:
proposedAtNsstring or nullformat: "^-?[0-9]+$"
When the last proposal was made, epoch nanoseconds.
concludedAtNsstring or nullformat: "^-?[0-9]+$"

When the last proposal concluded, epoch nanoseconds — at the submit itself where nothing needed approving; null while it pends and after a withdrawal.

concludedByobject or null

Who concluded it — the maker where nothing needed approving, else the approver whose approval met the count; null when concludedAtNs is.

concludedTransitionenum

What the last proposal proposed, kept once it concluded: SUBMIT or RESOLVE; UNKNOWN while it pends, or when it was withdrawn.

Allowed values:
approvalslist of objects

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.

remarkstring

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.

lastWithdrawalProposedByobject or null

Who made the last withdrawn proposal; null when none was.

lastWithdrawalWithdrawnByobject or null

Who withdrew it — the maker, or an approver; null when none was.

lastWithdrawalAtNsstring or nullformat: "^-?[0-9]+$"

When it was withdrawn, epoch nanoseconds; null when none was.

lastWithdrawalReasonstring

Why it was withdrawn, as the withdrawer stated it; empty when none was.

resolveOutcomeenum

What a resolution by hand proposes while it pends, or closed the transfer as once approved; UNKNOWN when none was ever proposed.

Allowed values:
evidenceKindenum

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.

Allowed values:
evidencestring

What the resolution’s maker saw at the venue, in their words; empty when none was proposed.

proposedSettledAmountstring or nullformat: "^-?[0-9]+(\.[0-9]+)?$"<=64 characters

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.

proposedTxIdstring

The transaction hash a pending resolution states, applied to txId when it is approved; empty when it states none.

updatedAtNsstringformat: "^-?[0-9]+$"
When this version was written, epoch nanoseconds.
updatedByobject

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.

globalSequencestringOptionalformat: "^[0-9]+$"

The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.

Errors

400
Withdraw Transfers Request Bad Request Error
401
Withdraw Transfers Request Unauthorized Error
403
Withdraw Transfers Request Forbidden Error
404
Withdraw Transfers Request Not Found Error
409
Withdraw Transfers Request Conflict Error
412
Withdraw Transfers Request Precondition Failed Error
413
Withdraw Transfers Request Content Too Large Error
422
Withdraw Transfers Request Unprocessable Entity Error
428
Withdraw Transfers Request Precondition Error
429
Withdraw Transfers Request Too Many Requests Error
500
Withdraw Transfers Request Internal Server Error
503
Withdraw Transfers Request Service Unavailable Error