--- title: "Create an orchestration address" method: POST path: "/v2/users/{userId}/orchestration-addresses" tags: ["Orchestration Address"] --- # Create an orchestration address `POST /v2/users/{userId}/orchestration-addresses` 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. ## Path parameters - `userId` string, required ## Query parameters - `profileId` string, uuid ## Request body - CreateOrchestrationAddress — Provisions a new persistent on-chain address that automatically offramps any stablecoin it receives. **Mode rules (cross-field):** * `mode=PER_DEPOSIT` — must NOT include `schedule` or `thresholdAmount`. * `mode=SCHEDULED` — MUST include `schedule.interval`; must NOT include `thresholdAmount`. `schedule.nextRunAt` is optional. * `mode=THRESHOLD` — MUST include `thresholdAmount`; must NOT include `schedule`. **Source rules:** `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 are rejected with `400`. **Offramp minimums:** each destination rail has a minimum offramp amount (e.g. ≥ 5 for SWIFT, ≥ 1 for wire/ACH/RTP; USDT carries a ≥ 10 floor). `mode=THRESHOLD` requires `thresholdAmount` to meet that minimum, and a batch is only ever created once the pending deposits reach it — deposits below the minimum are held `PENDING` to accumulate. **Idempotency:** `requestId` is the client-supplied idempotency key. Repeating the same `requestId` with the same payload returns the existing record (200). Repeating with a *different* payload returns `409 RESOURCE_CONFLICT` indicating which field differs (e.g. `requestId already used with a different source.currency`). **Wallet provisioning:** the response is returned synchronously after the escrow wallet is provisioned, so `status=ACTIVE` and `address` is non-null in the typical case. If the provider call is in flight, `status=PENDING_WALLET` and `address=null` — retry the same call (same `requestId`) to drive provisioning forward. - `requestId` string, uuid, required — Client-supplied idempotency key (UUID v4 recommended). Unique per `(profileId, requestId)`. - `source` OrchestrationAddressSource, required — The on-chain source the orchestration address accepts deposits in. A stablecoin contract must exist for the `(currency, chain)` pair — USDC and USDT are both supported on Base/Polygon/Ethereum/Solana, while TRON supports USDT only. Unsupported pairs (e.g. USDC on TRON) are rejected at create time with `400`. - `currency` 'usdc' | 'usdt', required — Stablecoin the address accepts. v1 supports USDC and USDT, subject to chain support (see above). - `chain` 'POLYGON' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'FLOW_EVM' | 'BSC' | 'TRON', required — Blockchain network the address lives on, as an abbreviated chain name. The same abbreviated form is used in both requests and responses (e.g. `BASE`). - `destination` OrchestrationAddressDestination, required — The destination payout configuration. v1 ships USD only, via an existing offramp account. - `currency` 'usd', required — Destination fiat currency. v1 ships USD only. - `accountId` string, uuid, required — UUID of the offramp account that will receive the converted fiat. Must belong to the same user, be a USD offramp account, be active, and be routed through HIFI's US fiat partner. Get one via `POST /v2/users/{userId}/accounts`. - `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. - `schedule` OrchestrationAddressSchedule — Schedule config for a `SCHEDULED` orchestration address. - `interval` 'HOURLY' | 'DAILY' | 'WEEKLY', required — How often a `SCHEDULED` orchestration address rolls up pending deposits into a batch. - `nextRunAt` string, date-time — Optional ISO 8601 timestamp for the first scheduled batch. Defaults to `now + interval` if omitted. Subsequent ticks advance by exactly one interval; missed windows (worker downtime) collapse into a single catch-up batch rather than firing N back-to-back. - `thresholdAmount` string, 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. ## Response `200` A single orchestration address record. - OrchestrationAddressObject — An orchestration address record. - `id` string, uuid — Unique orchestration address ID. - `userId` string, uuid — ID of the user that owns this orchestration address. - `address` string, nullable — The on-chain wallet address that accepts deposits. `null` while `status=PENDING_WALLET` (provisioning in flight); populated once the wallet exists. - `source` object — Source token + chain the address accepts. - `currency` 'usdc' | 'usdt' - `chain` string — Abbreviated chain name (e.g. `BASE`, `ETHEREUM`, `SOLANA`) — the same form accepted on create and used across the v2 API. - `destination` object — Destination payout configuration. - `currency` 'usd' - `accountId` string, uuid - `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. - `schedule` object, nullable — Populated only when `mode=SCHEDULED`; `null` otherwise. - `interval` 'HOURLY' | 'DAILY' | 'WEEKLY' — How often a `SCHEDULED` orchestration address rolls up pending deposits into a batch. - `nextRunAt` string, date-time — ISO 8601 timestamp of the next scheduled batch. - `thresholdAmount` string, 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. - `createdAt` string, date-time - `updatedAt` string, date-time - `deactivatedAt` string, date-time, nullable — ISO 8601 timestamp when the address was deactivated. `null` if still active. - `balance` object, nullable — 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`. - `currency` 'usdc' | 'usdt' - `amount` string — Decimal balance in the source `currency` (e.g. `"100.500000"`). ## Other responses - `400` — Bad request - validation error - `401` — Unauthorized - `404` — Resource not found - `409` — Conflict — the request collides with the current state of the resource (e.g. idempotency-key reuse with a different payload). - `500` — Internal Server Error --- [API](https://skmtc.net/hifi/apis/hifi-api.md) · [All operations](https://skmtc.net/hifi/apis/hifi-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hifi/hifi-api/revisions/15a39c342fd1/schema)