Update an orchestration address
Partial update of an existing orchestration address. Any combination of
mode, schedule, thresholdAmount, offrampMessage, and destination.accountId may
be passed.
Behavior notes:
- Switching mode wipes the irrelevant config columns.
- Changing
schedule.intervalwithout an explicitnextRunAtresets the next tick tonow + newInterval. - Changing
destination.accountIdre-validates the new account. - Queued batches use the current settings when the worker reads the OA to begin creating their offramp. Later edits do not change that attempt or the saved message of an initialized offramp, including on retry.
Cannot update a DEACTIVATED address — returns 400 RESOURCE_CONFLICT.
If the destination, message, mode, or status changes after validation but before
the update is saved, returns 409 RESOURCE_CONFLICT; reload the settings and retry.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
ID of the user
ID of the orchestration address.
Body
Partial update. Any combination of mode, schedule, thresholdAmount, offrampMessage,
and destination.accountId may be set. Same mode cross-rules as create
apply to the resulting configuration (e.g. switching to THRESHOLD
requires thresholdAmount).
Side effects:
- Switching mode clears schedule-only fields when they no longer apply.
- Changing
schedule.intervalwithout an explicitnextRunAtresets the next tick tonow + newInterval. - Changing
destination.accountIdre-validates the new account (must belong to user, be USD, be an offramp account, etc.). - Queued batches use the current settings when the worker reads the OA to begin offramp initialization. Later edits do not alter that attempt or already-initialized offramps and their saved messages.
A DEACTIVATED address cannot be updated — returns 400 RESOURCE_CONFLICT.
Concurrent changes to the validated message, destination, mode, or status return
409 RESOURCE_CONFLICT; reload the current settings and retry the update.
Optional payment message, preserved exactly. Wire allows at most four lines of 35 characters; ACH allows 10 characters; SWIFT allows 12. Only printable ASCII and newlines are accepted; backslashes and other control characters are rejected. Nonempty messages are unsupported for RTP and other rails. Missing, null, or empty means no message on create; on update omission preserves the setting and null or empty clears it. A destination change revalidates the saved or supplied message. Returns null when unset. Queued batches read current settings when initializing an offramp; initialized offramps retain their saved message on retry.
"Invoice 42"
Determines when deposits are converted into an offramp.
PER_DEPOSIT— each deposit is batched into its own offramp immediately, UNLESS the cumulativePENDINGamount is below the destination rail's offramp minimum, in which case the deposit is heldPENDINGand all pending deposits are batched together once their cumulative amount reaches the minimum.SCHEDULED— deposits accumulate until the next schedule boundary (HOURLY/DAILY/WEEKLY), then the entire pending pool is batched together (only if it meets the offramp minimum; otherwise it rolls into the next tick).THRESHOLD— deposits accumulate until their summed amount reachesthresholdAmount, then the entire pending pool is batched.
PER_DEPOSIT, SCHEDULED, THRESHOLD Schedule config for a SCHEDULED orchestration address.
New aggregate threshold. Required if the resulting mode is THRESHOLD,
and must be at least the destination rail's offramp minimum (else 400).
Partial destination update — only accountId may be changed.
Response
A single orchestration address record.
An orchestration address record.
Unique orchestration address ID.
ID of the user that owns this orchestration address.
The on-chain wallet address that accepts deposits. null while
status=PENDING_WALLET (provisioning in flight); populated once the
wallet exists.
"0xAbC0123456789AbCdEf0123456789AbCdEf01234"
Source token + chain the address accepts.
Destination payout configuration.
Optional payment message, preserved exactly. Wire allows at most four lines of 35 characters; ACH allows 10 characters; SWIFT allows 12. Only printable ASCII and newlines are accepted; backslashes and other control characters are rejected. Nonempty messages are unsupported for RTP and other rails. Missing, null, or empty means no message on create; on update omission preserves the setting and null or empty clears it. A destination change revalidates the saved or supplied message. Returns null when unset. Queued batches read current settings when initializing an offramp; initialized offramps retain their saved message on retry.
"Invoice 42"
Determines when deposits are converted into an offramp.
PER_DEPOSIT— each deposit is batched into its own offramp immediately, UNLESS the cumulativePENDINGamount is below the destination rail's offramp minimum, in which case the deposit is heldPENDINGand all pending deposits are batched together once their cumulative amount reaches the minimum.SCHEDULED— deposits accumulate until the next schedule boundary (HOURLY/DAILY/WEEKLY), then the entire pending pool is batched together (only if it meets the offramp minimum; otherwise it rolls into the next tick).THRESHOLD— deposits accumulate until their summed amount reachesthresholdAmount, then the entire pending pool is batched.
PER_DEPOSIT, SCHEDULED, THRESHOLD Populated only when mode=SCHEDULED; null otherwise.
Populated only when mode=THRESHOLD; null otherwise. Decimal amount
in the source currency.
"100.00"
Lifecycle status of the orchestration address.
PENDING_WALLET— created but the escrow wallet is still being provisioned. The on-chainaddressis null. Typically transient (a few seconds).ACTIVE— wallet provisioned, ready to receive deposits.DEACTIVATED— soft-deleted. The on-chain wallet still exists and can receive funds, but incoming deposits are recorded withstatus=IGNOREDand never offramped.
PENDING_WALLET, ACTIVE, DEACTIVATED ISO 8601 timestamp when the address was deactivated. null if still active.
The escrow wallet's live on-chain balance of the source token. Present
ONLY on the single-address GET (GET /orchestration-addresses/{id}); the
list endpoint omits it to avoid a provider call per row. null if the
wallet isn't provisioned yet or the balance lookup failed — the GET still
returns 200.