Skip to navigation

Transfers

A transfer between accounts

URL — No public environment serves this socket yet.

Topic transfer

Request parameters

ParameterTypeRequiredDescription
opstringYessubscribe
reqIdstringYesEchoed byte-exact on the answer. Printable ASCII, escape-free; anything else answers MALFORMED.
paramsobjectYes
> topicsarray of stringsYestransfer

Response parameters

ParameterTypeRequiredDescription
opstringYesOne of subscribe, unsubscribe.
reqIdstringYesEchoed byte-exact on the answer. Printable ASCII, escape-free; anything else answers MALFORMED.
successbooleanYestrue

Push data parameters

Served from 8.2.0 — the name answered TOPIC_NOT_ACTIVE before it. One row per transfer of the organization, keyed by transferId: an amount of one asset moving between two wallets of one account, or on-chain from one venue account to another — where it stands, what the venue and the destination have reported, and its proposal record. Needs transfers:read, or any transfers capability. A member whose deployment has not switched transfers on answers the subscribe TOPIC_NOT_ACTIVE.

How a row moves. On every version of the transfer: its submit, each approval, a withdrawal, the venue accepting and reporting on it, the destination seeing and crediting the deposit, a deadline passing, a resolution by hand proposed, approved or concluded. Every delta is the whole record at its new version — upsert it by transferId.

What the image holds. Every transfer still in flight (isOpen true), however old, and each closed one for the served window after its last change — 24 hours by default and a per-deployment setting — transferId ascending, oldest first. A closed transfer older than the window is not in a new image, though a delta for it would still arrive: read history with the REST API’s GET /transfers.

Writes are the REST API’s. A transfer is submitted, approved, withdrawn and resolved with POST /transfers and the routes beneath it; this channel carries what each did.

ParameterTypeRequiredDescription
eventstringYestransfer
msgTypestringYestransfer
topicstringYestransfer
seqstringYesThe stream position, as a decimal string — an int64 a JSON number would truncate.
seqTsstringYesThe stream timestamp, epoch-ns as a decimal string.
isSnapshotbooleanYesOne of true, false.
snapshotIdstringNoPresent on a snapshot part only, and the same on every part of one image; the next image of any topic carries a different one. Opaque — compare it for equality and nothing else. It is not a sequence, a version or a timestamp, and its shape may change; a client that ordered by it would be relying on how a member happens to mint it. Use it to keep two images apart. A repeat subscribe re-pushes the image — that is the resync, and there is no separate op — so a client can start image N+1 while N is still arriving, and without a name on each part it cannot tell which last: true closes which, nor stop a straggling part of N landing in the map N+1 just cleared. Discard any part whose snapshotId is not the one you are currently applying.
partintegerNoPresent on a snapshot part only; 1-based.
lastbooleanNoPresent on a snapshot part only. The image is complete when true — including for an empty channel, which is still one part.
dataarray of objectsYesOne transfer, keyed by transferId — the upsert key. The same row GET /transfers serves on the HTTP lane, with the two accounts’ names and the two assets’ symbols — the moved asset’s and the fee’s — beside their ids and isOpen beside the status; text nobody stated is null here, where that lane serves an empty string. Every version is the whole record. Three actors are always stated: submittedBy submitted it, proposedBy made its last proposal — the submit, or a resolution by hand — and updatedBy produced this version: a principal, or the platform (MACHINE) on a venue’s report, a deadline passing or a risk hold. Every principal on a transfer is a member: the platform admits no API key to a transfer write.
> transferIdstringYesThe upsert key, as a decimal string — an int64.
> versionstringYes1 at the submit and one more on every change, as a decimal string. It is the REST API’s ETag for the transfer: an approval, a withdrawal and a resolution state it as If-Match.
> statusstringYesWhere a transfer stands. 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. Append-only: read an unknown value as UNKNOWN, and tell a transfer in flight from a closed one by the row’s isOpen. One of UNKNOWN, PENDING_APPROVAL, QUEUED, INSTRUCTED, PENDING_PROVIDER_APPROVAL, IN_TRANSIT, SETTLED, FAILED, WITHDRAWN, RESOLVED_SETTLED, RESOLVED_FAILED.
> transitionstringYesWhat a version of a transfer 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. One of UNKNOWN, SUBMIT, APPROVE, WITHDRAW, QUEUE, INSTRUCT, PROVIDER_HOLD, PROVIDER_RELEASE, OBSERVE, ARRIVE, SETTLE, FAIL, SLA_BREACH, RESOLVE, CONTRADICT, RISK_HOLD, RISK_RELEASE.
> isOpenbooleanYesTrue while the transfer is in flight — awaiting approval, queued, instructed, with the custodian’s approvers or in transit — and false once it is closed. The forward-compatible read of status: a status added later arrives with this already set, so bucket on it rather than on the statuses’ names.
> sourceAccountIdintegerYesThe account the value leaves.
> sourceAccountstring, nullableYesThat account’s name; null until this member holds its row.
> sourceWalletstringYesThe wallet the value leaves, as the venue names it — funding, trading, a vault’s wallet.
> destAccountIdintegerYesThe account the value reaches — the source account on a move between two of its wallets.
> destAccountstring, nullableYesThat account’s name; null until this member holds its row.
> destWalletstringYesThe wallet the value reaches, as the venue names it.
> assetIdintegerYesThe asset moved.
> assetstring, nullableYesThe asset’s symbol; null until this member holds its row.
> chainstring, nullableYesThe 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. Append-only: a name you do not know is still a network. One of UNKNOWN, BITCOIN, ETHEREUM.
> amountstringYesThe amount instructed, in the asset’s own units, at the scale the submit stated it. The fee is not inside it.
> feeAmountstring, nullableYesThe fee the venue stated, in the asset feeAssetId names. Null until the venue states one.
> feeAssetIdintegerYesThe 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.
> feeAssetstring, nullableYesThat asset’s symbol; null until this member holds its row.
> settledAmountstring, nullableYesWhat 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.
> confirmationsintegerYesThe highest confirmation count either end of the transfer has reported; 0 until one is.
> executingCredentialIdintegerYesThe key that executes the transfer — a row of the credential channel: the account’s own key for a move between its wallets, the source account’s transfers key for an on-chain one.
> destAddressIdinteger, nullableYesThe destination’s verified address the transfer was admitted to (the REST API’s GET /account-addresses); null for a move between two wallets.
> externalRefstring, nullableYesThe venue’s own id for the withdrawal or transfer; null until the venue accepts it.
> txIdstring, nullableYesThe on-chain transaction hash, once broadcast or stated by an approved resolution; null otherwise.
> failureReasonstringYesWhy a 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 maximum); else VENUE_ERROR or TIMEOUT. UNKNOWN while it has not failed. Append-only: read an unknown value as UNKNOWN. One of UNKNOWN, INSUFFICIENT_FUNDS, ADDRESS_NOT_ALLOWLISTED, BELOW_MINIMUM, ABOVE_LIMIT, ASSET_SUSPENDED, PERMISSION_DENIED, PROVIDER_DENIED, AMOUNT_PRECISION, FEE_ABOVE_POLICY, VENUE_ERROR, TIMEOUT.
> failureDetailstring, nullableYesThe venue’s own text behind failureReason; null unless it failed.
> isOverduebooleanYesWhether 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.
> overdueLegstringYesA leg of a transfer’s journey, each with a deadline: 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. As slaLeg it is the leg whose deadline is running now, UNKNOWN while the transfer awaits approval and once it is closed; as overdueLeg the leg that went overdue, UNKNOWN while on time. Append-only: read an unknown value as UNKNOWN. One of UNKNOWN, ACTION, PROVIDER, CHAIN, HELD.
> slaLegstringYesA leg of a transfer’s journey, each with a deadline: 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. As slaLeg it is the leg whose deadline is running now, UNKNOWN while the transfer awaits approval and once it is closed; as overdueLeg the leg that went overdue, UNKNOWN while on time. Append-only: read an unknown value as UNKNOWN. One of UNKNOWN, ACTION, PROVIDER, CHAIN, HELD.
> slaDeadlineNsstring, nullableYesWhen the running leg’s deadline falls, epoch-ns; null when none runs.
> isHeldAtDestinationbooleanYesWhether the destination shows the deposit but has not credited it yet; holdDetail says why, where the venue does.
> holdDetailstring, nullableYesThe destination’s own text behind a held deposit; null when none.
> isFeeAbovePolicybooleanYesWhether the fee the venue charged exceeded the chain policy’s maximum.
> isHeadroomAcknowledgedbooleanYesWhether the submit overrode the margin headroom check — its maker stated acknowledgeHeadroom and the check refused the move without it. Each approval states its own in approvals.
> isRiskHeldbooleanYesWhether the transfer, queued out of a margin wallet, is held because its account’s riskPosture is BLOCKED: nothing instructs the venue until the posture leaves BLOCKED. Its deadline keeps running.
> isContradictedbooleanYesWhether the venue completed or failed this transfer after it was resolved by hand; the status is unchanged.
> assetPolicyVersionstringYesThe version of the organization’s asset policy the transfer was admitted under — at the submit, or at the approval that admitted it.
> chainPolicyVersionstring, nullableYesThe version of the chain policy it was admitted under; null for a move between two wallets, which reads none.
> clientTransferIdstringYesThe submit’s Idempotency-Key on the REST API, the caller’s own handle for the transfer: taken while the transfer is open and for 24 hours after it closes.
> submittedAtNsstringYesWhen it was submitted, epoch-ns; never moves.
> submittedByobjectYesThe principal behind an act, as the platform records it on every command and fact: a member of your organization (USER, id their user id — the REST API’s GET /users/{id}), an API key it issued (API_KEY, id the key’s — GET /api-keys/{id}), or the platform itself (MACHINE, id 0) when a strategy’s instance acted — then algoInstanceId beside it names the instance. Tell a strategy’s act from a principal’s by algoInstanceId, never by the kind alone. On a transfer row the platform is also updatedBy wherever no principal moved the transfer: a venue’s report, a deadline passing, a risk hold. UNKNOWN is the sentinel of a fact that stated none, which nothing in this release writes; tolerate it as you would a kind you do not know.
> > kindstringYesOne of UNKNOWN, USER, API_KEY, MACHINE.
> > idintegerYes
> queuedAtNsstring, nullableYesWhen it became QUEUED, epoch-ns; null before.
> instructedAtNsstring, nullableYesWhen the venue accepted the instruction, epoch-ns; null before.
> heldAtNsstring, nullableYesWhen the destination first reported the deposit held, epoch-ns; null if it never did.
> settledAtNsstring, nullableYesWhen the transfer settled — by the venue’s word, the destination’s credit or an approved resolution — epoch-ns; null before.
> proposedByobjectYesThe principal behind an act, as the platform records it on every command and fact: a member of your organization (USER, id their user id — the REST API’s GET /users/{id}), an API key it issued (API_KEY, id the key’s — GET /api-keys/{id}), or the platform itself (MACHINE, id 0) when a strategy’s instance acted — then algoInstanceId beside it names the instance. Tell a strategy’s act from a principal’s by algoInstanceId, never by the kind alone. On a transfer row the platform is also updatedBy wherever no principal moved the transfer: a venue’s report, a deadline passing, a risk hold. UNKNOWN is the sentinel of a fact that stated none, which nothing in this release writes; tolerate it as you would a kind you do not know.
> > kindstringYesOne of UNKNOWN, USER, API_KEY, MACHINE.
> > idintegerYes
> pendingTransitionstringYesWhat a transfer’s proposal proposes: SUBMIT — the transfer itself, while it is PENDING_APPROVAL; RESOLVE — a resolution by hand, whose content is resolveOutcome, evidenceKind, evidence, proposedSettledAmount and proposedTxId. As pendingTransition it is what awaits approval now, UNKNOWN when nothing does; as concludedTransition what the last proposal proposed, kept once it concluded — UNKNOWN while it pends, or when it was withdrawn. The REST API’s approvals inbox lists the two as ACTIVATE and AMEND. Append-only: read an unknown value as UNKNOWN. One of UNKNOWN, SUBMIT, RESOLVE.
> proposedAtNsstring, nullableYesWhen the last proposal was made, epoch-ns.
> concludedAtNsstring, nullableYesWhen the last proposal concluded, epoch-ns — at the submit itself where nothing needed approving; null while it pends and after a withdrawal.
> concludedByobject, nullableYesWho concluded it — the maker where nothing needed approving, else the approver whose approval met the count; null when concludedAtNs is.
> concludedTransitionstringYesWhat a transfer’s proposal proposes: SUBMIT — the transfer itself, while it is PENDING_APPROVAL; RESOLVE — a resolution by hand, whose content is resolveOutcome, evidenceKind, evidence, proposedSettledAmount and proposedTxId. As pendingTransition it is what awaits approval now, UNKNOWN when nothing does; as concludedTransition what the last proposal proposed, kept once it concluded — UNKNOWN while it pends, or when it was withdrawn. The REST API’s approvals inbox lists the two as ACTIVATE and AMEND. Append-only: read an unknown value as UNKNOWN. One of UNKNOWN, SUBMIT, RESOLVE.
> approvalsarray of objectsYesWho approved the transfer’s last proposal and when, in approval order; empty until the first approval. A submit concludes when they number the organization’s transfers approval rule; a resolution needs at least one, whatever the rule.
> > userIdintegerYesThe approving member’s user id.
> > approvedAtNsstringYesWhen this approval was given, epoch-ns.
> > isHeadroomAcknowledgedbooleanYesWhether this approval overrode the margin headroom check — it stated acknowledgeHeadroom and the check refused the approval without it.
> remarkstring, nullableYesThe maker’s note on the submit, for its approvers; null when none, and once a resolution by hand is proposed — its maker’s words are evidence.
> lastWithdrawalProposedByobject, nullableYesWho made the last withdrawn proposal; null when none was.
> lastWithdrawalWithdrawnByobject, nullableYesWho withdrew it — the maker, or an approver; null when none was.
> lastWithdrawalAtNsstring, nullableYesWhen it was withdrawn, epoch-ns; null when none was.
> lastWithdrawalReasonstring, nullableYesWhy it was withdrawn, as the withdrawer stated it; null when none was.
> resolveOutcomestringYesWhat a resolution by hand proposes while it pends, or closed the transfer as once approved; UNKNOWN when none was ever proposed. Append-only: read an unknown value as UNKNOWN. One of UNKNOWN, SETTLED, FAILED.
> evidenceKindstringYesWhat a resolution by hand 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. Append-only: read an unknown value as UNKNOWN. One of UNKNOWN, VENUE_SETTLED, VENUE_CANCELLED, VENUE_FAILED, VENUE_NO_RECORD.
> evidencestring, nullableYesWhat the resolution’s maker saw at the venue, in their words; null when none was proposed.
> proposedSettledAmountstring, nullableYesWhat 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, nullableYesThe transaction hash a pending resolution states, applied to txId when it is approved; null when it states none.
> updatedAtNsstringYesWhen this version was written, epoch-ns.
> updatedByobjectYesThe principal behind an act, as the platform records it on every command and fact: a member of your organization (USER, id their user id — the REST API’s GET /users/{id}), an API key it issued (API_KEY, id the key’s — GET /api-keys/{id}), or the platform itself (MACHINE, id 0) when a strategy’s instance acted — then algoInstanceId beside it names the instance. Tell a strategy’s act from a principal’s by algoInstanceId, never by the kind alone. On a transfer row the platform is also updatedBy wherever no principal moved the transfer: a venue’s report, a deadline passing, a risk hold. UNKNOWN is the sentinel of a fact that stated none, which nothing in this release writes; tolerate it as you would a kind you do not know.
> > kindstringYesOne of UNKNOWN, USER, API_KEY, MACHINE.
> > idintegerYes