Sign in

v1

latestOpenAPI 3.0.02026-07-26103425558.9 KB
Orchestration Address

Deactivate an orchestration address

Soft-delete the address: sets status=DEACTIVATED and deactivatedAt=now(). Requires a walletAddress in the body — any deposits still PENDING (not yet rolled into a batch) are refunded in-kind to it. The claim and refund run atomically under the address row lock, so a deposit can never be both offramped and refunded. Idempotent — calling on an already-deactivated address returns 200 with the current record and issues no second refund.

After deactivation:

  • The on-chain wallet still exists and can receive funds (we can't take it offline).
  • Incoming deposits are recorded with status=IGNORED and ignoredReason=ADDRESS_DEACTIVATED. A Slack alert fires for manual ops follow-up. These are NOT auto-refunded — only the deposits that were PENDING at deactivation are.
  • The escrow wallet stays locked to this address (it's never returned to the general allocation pool).
  • Batches already in PROCESSING continue to completion; batches still PENDING will be marked FAILED with failureReason=ADDRESS_NOT_ACTIVE on the next worker tick.
post/v2/users/{userId}/orchestration-addresses/{orchestrationAddressId}/deactivate

Path parameters

userIdstring required

ID of the user

orchestrationAddressIdstring uuid required

ID of the orchestration address.

Request body

walletAddressstring required

Destination address for the in-kind refund of the address's PENDING deposits. Must be a valid address for the orchestration address's chain (else 400 FIELD_VALIDATION_ERROR). Required even when there are no pending deposits to refund.

Response

A single orchestration address record.

idstring uuid

Unique orchestration address ID.

userIdstring uuid

ID of the user that owns this orchestration address.

addressstring nullable

The on-chain wallet address that accepts deposits. null while status=PENDING_WALLET (provisioning in flight); populated once the wallet exists.

mode'PER_DEPOSIT' | 'SCHEDULED' | 'THRESHOLD'

Determines when deposits are converted into an offramp.

  • PER_DEPOSIT — each deposit is batched into its own offramp immediately, UNLESS the cumulative PENDING amount is below the destination rail's offramp minimum, in which case the deposit is held PENDING and 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 reaches thresholdAmount, then the entire pending pool is batched.
thresholdAmountstring nullable

Populated only when mode=THRESHOLD; null otherwise. Decimal amount in the source currency.

status'PENDING_WALLET' | 'ACTIVE' | 'DEACTIVATED'

Lifecycle status of the orchestration address.

  • PENDING_WALLET — created but the escrow wallet is still being provisioned. The on-chain address is 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 with status=IGNORED and never offramped.
createdAtstring date-time
updatedAtstring date-time
deactivatedAtstring date-time nullable

ISO 8601 timestamp when the address was deactivated. null if still active.

Example response

{
  "address": "0xAbC0123456789AbCdEf0123456789AbCdEf01234",
  "source": {
    "chain": "BASE"
  },
  "thresholdAmount": "100.00",
  "balance": {
    "currency": "usdc",
    "amount": "100.500000"
  }
}