Sign in

v1

latestOpenAPI 3.0.02026-07-26103425558.9 KB
Orchestration Address

Create an orchestration address

Create a persistent on-chain wallet that automatically offramps any stablecoin deposit to a USD bank account.

The endpoint provisions the escrow wallet synchronously, so the response typically already carries status=ACTIVE and a populated address. If the provider call is mid-flight, status=PENDING_WALLET and address=null — retry the same call (same requestId) to drive provisioning forward.

Idempotency. Repeating the same requestId with an identical payload returns the existing record (200). Repeating it with a different payload returns 409 RESOURCE_CONFLICT indicating which field differs (e.g. requestId already used with a different source.chain).

Mode rules:

  • PER_DEPOSIT — each deposit is batched into its own offramp immediately, unless it's below the destination rail's offramp minimum, in which case it's held PENDING until the cumulative pending reaches the minimum, then batched together.
  • SCHEDULED — deposits accumulate until the next HOURLY/DAILY/WEEKLY tick.
  • THRESHOLD — deposits accumulate until thresholdAmount is reached.

Source & minimums. source.currency must be supported on source.chain (e.g. USDT on TRON, USDC on Base/Polygon/Ethereum/Solana) — unsupported pairs like USDC on TRON return 400. Each rail also has a minimum offramp amount (e.g. ≥ 5 for SWIFT, ≥ 1 for wire/ACH/RTP; USDT ≥ 10); THRESHOLD's thresholdAmount must meet it.

See the schema description on CreateOrchestrationAddress for the exact field-combination rules.

post/v2/users/{userId}/orchestration-addresses

Path parameters

userIdstring required

ID of the user

Query parameters

profileIdstring uuid

Optional profile (client/organization) scope. When omitted the request is scoped to the caller's default profile. Used by requestId idempotency: addresses are unique per (profileId, requestId).

Request body

requestIdstring uuid required

Client-supplied idempotency key (UUID v4 recommended). Unique per (profileId, requestId).

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

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

Required when mode=THRESHOLD. Forbidden otherwise. Decimal amount in the address's source currency (e.g. "100.00"). Must be at least the destination rail's offramp minimum (e.g. ≥ 5 for SWIFT, ≥ 1 for wire/ACH/RTP; USDT ≥ 10), else 400. Aggregate pending deposits are summed in integer token units (BigInt) and compared to this value, so floating-point drift never blocks the threshold.

Example request

{
  "thresholdAmount": "100.00"
}

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"
  }
}