Reference
Endpoints, fields, and the transfer status lifecycle.
Every response is { "success": boolean, "data"?: ..., "error"?: string }. Amounts are strings in the token's smallest units unless noted.
POST /api/private-route/quote
Preview a transfer. Nothing is persisted and no deposit address is allocated.
Request:
| Field | Type | Notes |
|---|---|---|
sourceChainId | number | Chain the sender deposits from |
destChainId | number | Chain the recipient is paid on |
amount | string | Human amount, e.g. "100" |
tokenSymbol | string | Source token, defaults to USDC |
destTokenSymbol | string | Destination token, defaults to the source |
Response data:
| Field | Type | Notes |
|---|---|---|
symbol, destSymbol | string | Source and destination token symbols; both are USDC in CCTP mode |
sourceChainId, destChainId, hubChainId | number | Chain identifiers |
amount | string | Input, source token units |
quotedOutputAmount | string | Delivered output, destination token units |
feeAmount | string | Service fee, destination token units |
bridgeFeeAmount | string | CCTP destination bridge fee, or "0" in Relay mode |
privacyFeeAmount | string | Railgun unshield fee in CCTP mode, or "0" in Relay mode |
amountInUsd, quotedOutputUsd, feeUsd, bridgeFeeUsd, privacyFeeUsd | number | null | USD values when priced |
etaSeconds | number | Rough end-to-end estimate |
route | string[] | Display hops |
POST /api/private-route
Create a transfer. Same request as quote, plus userDestinationAddress (where the recipient is paid on the destination chain).
Response data adds:
| Field | Type | Notes |
|---|---|---|
routeId | string | Track the transfer with this |
depositAddress | string | Send USDC here (TEE-managed smart account on the source chain) |
hubAccount | string | Smart account on the privacy hub that receives the bridged funds |
hubIsSmartAccount | boolean | Whether the hub account is a smart account |
status | string | Starts at AWAITING_DEPOSIT |
GET /api/private-route/:routeId
Returns the persisted transfer. Read status to drive progress and error if it failed.
GET /api/relay/chains
Lists the chains exposed by the active bridge provider. Returns chainId, name, displayName, and optional logoUrl and vmType. Relay mode returns enabled deposit-address chains; CCTP mode returns configured Circle networks.
GET /api/relay/tokens
Lists supported tokens on a chain. Query: chainId (required), search (optional). Each token has chainId, address, symbol, name, decimals, and logoUrl when available. CCTP mode returns USDC only.
Status lifecycle
| Status | Meaning |
|---|---|
AWAITING_DEPOSIT | Waiting for the sender to fund the deposit address |
BRIDGING_IN | Bridging USDC to the hub via CCTP |
RECEIVED_ON_HUB | USDC arrived at the hub; shielding next |
SHIELDED | Shielded into Railgun; preparing the payout |
UNSHIELD_SENT | Unshielded for the outbound bridge |
BRIDGING_OUT | Bridging USDC to the destination chain via CCTP |
COMPLETED | Delivered on the destination chain |
FAILED | Terminal failure; inspect the persisted error field for the cause |
Errors return HTTP 400 for a bad request or unsupported pair, 404 for an unknown routeId, and 500 otherwise, with the reason in error.