> ## Documentation Index > Fetch the complete documentation index at: https://docs.hifi.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://production.hifi.com/api/v2/openapi.json post /v2/users/{userId}/orchestration-addresses openapi: 3.0.0 info: title: Hifi API version: 2.0.0 description: API documentation for Hifi servers: - url: https://production.hifibridge.com description: Production server - url: https://sandbox.hifibridge.com description: Sandbox server security: - bearerAuth: [] tags: - name: Common description: Common endpoints - name: User description: User endpoints - name: Kyc description: Kyc endpoints - name: Wallet description: Wallet endpoints - name: Account description: Account endpoints - name: External Account description: External Account endpoints for managing beneficiary bank accounts - name: Fiat Account description: Fiat Account endpoints - name: Virtual Account description: Virtual Account endpoints - name: Onramp description: Onramp endpoints - name: Offramp description: Offramp endpoints - name: Orchestration Address description: >- Orchestration Address endpoints — persistent on-chain wallets that automatically off-ramp incoming stablecoin deposits to a USD bank account - name: Crypto Transfer description: Crypto Transfer endpoints - name: Cross-Chain Bridge description: Cross-Chain Bridge endpoints - name: Token Swap description: Token Swap endpoints - name: Canton Offers description: Canton Offers endpoints - name: Transfer Rules description: Transfer approval rules and configuration - name: Transfer Approvals description: Transfer approval workflow and admin actions - name: File description: File endpoints - name: Reporting description: Reporting and metrics endpoints paths: /v2/users/{userId}/orchestration-addresses: post: tags: - Orchestration Address summary: Create an orchestration address description: > 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. parameters: - $ref: '#/components/parameters/UserIdPathParameter' - $ref: '#/components/parameters/OrchestrationProfileIdQueryParameter' requestBody: $ref: '#/components/requestBodies/CreateOrchestrationAddressBody' responses: '200': $ref: '#/components/responses/OrchestrationAddressResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '404': $ref: '#/components/responses/NotFoundResponse' '409': $ref: '#/components/responses/ConflictResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: parameters: UserIdPathParameter: name: userId in: path schema: type: string description: ID of the user required: true OrchestrationProfileIdQueryParameter: name: profileId in: query schema: type: string format: uuid required: false description: > 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)`. requestBodies: CreateOrchestrationAddressBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrchestrationAddress' responses: OrchestrationAddressResponse: description: A single orchestration address record. content: application/json: schema: $ref: '#/components/schemas/OrchestrationAddressObject' BadRequestResponse: description: Bad request - validation error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object description: Field-specific validation errors UnauthorizedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' NotFoundResponse: description: Resource not found content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string ConflictResponse: description: >- Conflict — the request collides with the current state of the resource (e.g. idempotency-key reuse with a different payload). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerErrorResponse: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' schemas: CreateOrchestrationAddress: type: object title: Create Orchestration Address description: > 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. properties: requestId: type: string format: uuid description: >- Client-supplied idempotency key (UUID v4 recommended). Unique per `(profileId, requestId)`. source: $ref: '#/components/schemas/OrchestrationAddressSource' destination: $ref: '#/components/schemas/OrchestrationAddressDestination' mode: $ref: '#/components/schemas/OrchestrationAddressModeEnum' schedule: allOf: - $ref: '#/components/schemas/OrchestrationAddressSchedule' description: | Required when `mode=SCHEDULED`. Forbidden otherwise. nullable: true thresholdAmount: type: string description: > 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: '100.00' nullable: true required: - requestId - source - destination - mode OrchestrationAddressObject: type: object description: An orchestration address record. properties: id: type: string format: uuid description: Unique orchestration address ID. userId: type: string format: uuid description: ID of the user that owns this orchestration address. address: type: string nullable: true description: | The on-chain wallet address that accepts deposits. `null` while `status=PENDING_WALLET` (provisioning in flight); populated once the wallet exists. example: '0xAbC0123456789AbCdEf0123456789AbCdEf01234' source: type: object description: Source token + chain the address accepts. properties: currency: type: string enum: - usdc - usdt chain: type: string description: > Abbreviated chain name (e.g. `BASE`, `ETHEREUM`, `SOLANA`) — the same form accepted on create and used across the v2 API. example: BASE destination: type: object description: Destination payout configuration. properties: currency: type: string enum: - usd accountId: type: string format: uuid mode: $ref: '#/components/schemas/OrchestrationAddressModeEnum' schedule: description: | Populated only when `mode=SCHEDULED`; `null` otherwise. nullable: true type: object properties: interval: $ref: '#/components/schemas/OrchestrationScheduleIntervalEnum' nextRunAt: type: string format: date-time description: ISO 8601 timestamp of the next scheduled batch. thresholdAmount: type: string nullable: true description: > Populated only when `mode=THRESHOLD`; `null` otherwise. Decimal amount in the source `currency`. example: '100.00' status: $ref: '#/components/schemas/OrchestrationAddressStatusEnum' createdAt: type: string format: date-time updatedAt: type: string format: date-time deactivatedAt: type: string format: date-time nullable: true description: >- ISO 8601 timestamp when the address was deactivated. `null` if still active. balance: type: object nullable: true description: > 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`. properties: currency: type: string enum: - usdc - usdt amount: type: string description: Decimal balance in the source `currency` (e.g. `"100.500000"`). example: currency: usdc amount: '100.500000' Unauthorized: type: object properties: code: type: integer description: Error code error: type: string description: Error type errorDetails: type: string description: Detailed error message ErrorResponse: type: object properties: error: type: string description: Error message describing what went wrong example: Invalid API key or user not found InternalServerError: type: object properties: code: type: integer description: Error code error: type: string description: Error type errorDetails: type: string description: Detailed error message OrchestrationAddressSource: type: object description: > 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`. properties: currency: type: string enum: - usdc - usdt description: >- Stablecoin the address accepts. v1 supports USDC and USDT, subject to chain support (see above). chain: type: string enum: - POLYGON - ETHEREUM - SOLANA - BASE - FLOW_EVM - BSC - TRON description: > 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`). required: - currency - chain OrchestrationAddressDestination: type: object description: >- The destination payout configuration. v1 ships USD only, via an existing offramp account. properties: currency: type: string enum: - usd description: Destination fiat currency. v1 ships USD only. accountId: type: string format: uuid description: > 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`. required: - currency - accountId OrchestrationAddressModeEnum: type: string enum: - PER_DEPOSIT - SCHEDULED - THRESHOLD description: | 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. OrchestrationAddressSchedule: type: object description: Schedule config for a `SCHEDULED` orchestration address. properties: interval: $ref: '#/components/schemas/OrchestrationScheduleIntervalEnum' nextRunAt: type: string format: date-time description: > 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. required: - interval OrchestrationScheduleIntervalEnum: type: string enum: - HOURLY - DAILY - WEEKLY description: >- How often a `SCHEDULED` orchestration address rolls up pending deposits into a batch. OrchestrationAddressStatusEnum: type: string enum: - PENDING_WALLET - ACTIVE - DEACTIVATED description: | 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. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````