---
title: "Retrieve an orchestration address"
method: GET
path: "/v2/users/{userId}/orchestration-addresses/{orchestrationAddressId}"
tags: ["Orchestration Address"]
---

# Retrieve an orchestration address

`GET /v2/users/{userId}/orchestration-addresses/{orchestrationAddressId}`

Fetch a single orchestration address by ID. Returns `404 RESOURCE_NOT_FOUND`
if the address doesn't exist *or* doesn't belong to the specified user —
the API never discloses whether a foreign address exists.

## Path parameters

- `userId` string, required
- `orchestrationAddressId` string, uuid, required

## 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

- `401` — Unauthorized
- `404` — Resource not found
- `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/versions/15a39c342fd1/schema)