URL — No public environment serves this socket yet.
Topic transfer
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
op | string | Yes | subscribe |
reqId | string | Yes | Echoed byte-exact on the answer. Printable ASCII, escape-free; anything else answers MALFORMED. |
params | object | Yes | |
> topics | array of strings | Yes | transfer |
Response parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
op | string | Yes | One of subscribe, unsubscribe. |
reqId | string | Yes | Echoed byte-exact on the answer. Printable ASCII, escape-free; anything else answers MALFORMED. |
success | boolean | Yes | true |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
event | string | Yes | transfer |
msgType | string | Yes | transfer |
topic | string | Yes | transfer |
seq | string | Yes | The stream position, as a decimal string — an int64 a JSON number would truncate. |
seqTs | string | Yes | The stream timestamp, epoch-ns as a decimal string. |
isSnapshot | boolean | Yes | One of true, false. |
snapshotId | string | No | Present 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. |
part | integer | No | Present on a snapshot part only; 1-based. |
last | boolean | No | Present on a snapshot part only. The image is complete when true — including for an empty channel, which is still one part. |
data | array of objects | Yes | One 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. |
> transferId | string | Yes | The upsert key, as a decimal string — an int64. |
> version | string | Yes | 1 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. |
> status | string | Yes | Where 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. |
> transition | string | Yes | What 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. |
> isOpen | boolean | Yes | True 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. |
> sourceAccountId | integer | Yes | The account the value leaves. |
> sourceAccount | string, nullable | Yes | That account’s name; null until this member holds its row. |
> sourceWallet | string | Yes | The wallet the value leaves, as the venue names it — funding, trading, a vault’s wallet. |
> destAccountId | integer | Yes | The account the value reaches — the source account on a move between two of its wallets. |
> destAccount | string, nullable | Yes | That account’s name; null until this member holds its row. |
> destWallet | string | Yes | The wallet the value reaches, as the venue names it. |
> assetId | integer | Yes | The asset moved. |
> asset | string, nullable | Yes | The asset’s symbol; null until this member holds its row. |
> chain | string, nullable | Yes | 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. Append-only: a name you do not know is still a network. One of UNKNOWN, BITCOIN, ETHEREUM. |
> amount | string | Yes | The amount instructed, in the asset’s own units, at the scale the submit stated it. The fee is not inside it. |
> feeAmount | string, nullable | Yes | The fee the venue stated, in the asset feeAssetId names. Null until the venue states one. |
> feeAssetId | integer | Yes | 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. |
> feeAsset | string, nullable | Yes | That asset’s symbol; null until this member holds its row. |
> settledAmount | string, nullable | Yes | 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. |
> confirmations | integer | Yes | The highest confirmation count either end of the transfer has reported; 0 until one is. |
> executingCredentialId | integer | Yes | The 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. |
> destAddressId | integer, nullable | Yes | The destination’s verified address the transfer was admitted to (the REST API’s GET /account-addresses); null for a move between two wallets. |
> externalRef | string, nullable | Yes | The venue’s own id for the withdrawal or transfer; null until the venue accepts it. |
> txId | string, nullable | Yes | The on-chain transaction hash, once broadcast or stated by an approved resolution; null otherwise. |
> failureReason | string | Yes | Why 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. |
> failureDetail | string, nullable | Yes | The venue’s own text behind failureReason; null unless it failed. |
> isOverdue | boolean | Yes | 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. |
> overdueLeg | string | Yes | A 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. |
> slaLeg | string | Yes | A 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. |
> slaDeadlineNs | string, nullable | Yes | When the running leg’s deadline falls, epoch-ns; null when none runs. |
> isHeldAtDestination | boolean | Yes | Whether the destination shows the deposit but has not credited it yet; holdDetail says why, where the venue does. |
> holdDetail | string, nullable | Yes | The destination’s own text behind a held deposit; null when none. |
> isFeeAbovePolicy | boolean | Yes | Whether the fee the venue charged exceeded the chain policy’s maximum. |
> isHeadroomAcknowledged | boolean | Yes | Whether 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. |
> isRiskHeld | boolean | Yes | Whether 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. |
> isContradicted | boolean | Yes | Whether the venue completed or failed this transfer after it was resolved by hand; the status is unchanged. |
> assetPolicyVersion | string | Yes | The version of the organization’s asset policy the transfer was admitted under — at the submit, or at the approval that admitted it. |
> chainPolicyVersion | string, nullable | Yes | The version of the chain policy it was admitted under; null for a move between two wallets, which reads none. |
> clientTransferId | string | Yes | The 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. |
> submittedAtNs | string | Yes | When it was submitted, epoch-ns; never moves. |
> submittedBy | object | Yes | The 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. |
> > kind | string | Yes | One of UNKNOWN, USER, API_KEY, MACHINE. |
> > id | integer | Yes | |
> queuedAtNs | string, nullable | Yes | When it became QUEUED, epoch-ns; null before. |
> instructedAtNs | string, nullable | Yes | When the venue accepted the instruction, epoch-ns; null before. |
> heldAtNs | string, nullable | Yes | When the destination first reported the deposit held, epoch-ns; null if it never did. |
> settledAtNs | string, nullable | Yes | When the transfer settled — by the venue’s word, the destination’s credit or an approved resolution — epoch-ns; null before. |
> proposedBy | object | Yes | The 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. |
> > kind | string | Yes | One of UNKNOWN, USER, API_KEY, MACHINE. |
> > id | integer | Yes | |
> pendingTransition | string | Yes | What 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. |
> proposedAtNs | string, nullable | Yes | When the last proposal was made, epoch-ns. |
> concludedAtNs | string, nullable | Yes | When the last proposal concluded, epoch-ns — at the submit itself where nothing needed approving; null while it pends and after a withdrawal. |
> concludedBy | object, nullable | Yes | Who concluded it — the maker where nothing needed approving, else the approver whose approval met the count; null when concludedAtNs is. |
> concludedTransition | string | Yes | What 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. |
> approvals | array of objects | Yes | Who 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. |
> > userId | integer | Yes | The approving member’s user id. |
> > approvedAtNs | string | Yes | When this approval was given, epoch-ns. |
> > isHeadroomAcknowledged | boolean | Yes | Whether this approval overrode the margin headroom check — it stated acknowledgeHeadroom and the check refused the approval without it. |
> remark | string, nullable | Yes | The 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. |
> lastWithdrawalProposedBy | object, nullable | Yes | Who made the last withdrawn proposal; null when none was. |
> lastWithdrawalWithdrawnBy | object, nullable | Yes | Who withdrew it — the maker, or an approver; null when none was. |
> lastWithdrawalAtNs | string, nullable | Yes | When it was withdrawn, epoch-ns; null when none was. |
> lastWithdrawalReason | string, nullable | Yes | Why it was withdrawn, as the withdrawer stated it; null when none was. |
> resolveOutcome | string | Yes | What 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. |
> evidenceKind | string | Yes | What 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. |
> evidence | string, nullable | Yes | What the resolution’s maker saw at the venue, in their words; null when none was proposed. |
> proposedSettledAmount | string, nullable | Yes | 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. |
> proposedTxId | string, nullable | Yes | The transaction hash a pending resolution states, applied to txId when it is approved; null when it states none. |
> updatedAtNs | string | Yes | When this version was written, epoch-ns. |
> updatedBy | object | Yes | The 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. |
> > kind | string | Yes | One of UNKNOWN, USER, API_KEY, MACHINE. |
> > id | integer | Yes |