Skip to main content

Withdrawals API Reference

Complete reference for the Withdrawals API endpoints. Manage withdrawal settings and create withdrawal requests.

Withdrawal strategy values​

The strategy field is a number in both settings and withdrawal requests:

ValueNameDescription
1multi-networkDirect transfers per chain; no cross-chain bridge.
2bridgeUse Relay to bridge when the quote requires it; otherwise same as multi-network.

See Withdrawal strategy for details. For how gas is paid (paymaster, self-fund, hot wallet), see Gas and fee funding.

Valid chain types​

Withdrawal addresses are keyed by chain type. Valid keys are: evm, solana, bitcoin, tron, cosmos, polkadot, move, ton. Use these as keys in:

  • Withdrawal Settings — addresses: e.g. { "evm": "0x...", "solana": "...", "bitcoin": "bc1q..." }
  • Payment Intents and Payment Links — withdrawal_addresses: same shape

Each address is validated for that chain type (EVM, Solana, Bitcoin, etc.). To list networks by chain type, use GET /payments/networks?chainType=evm (or another valid chain type). See Payment minimums for per-chain-type minimums.

Per-payment withdrawal addresses (by chain type)​

When you create a Payment Intent or Payment Link, you can optionally set withdrawal_addresses (or withdrawalAddresses for links) as a key-value object. Keys are chain types from the network table (e.g. evm, solana, bitcoin). Each value is the withdrawal address for that chain. If omitted or empty for a chain, your account's default from Withdrawal Settings for that chain type is used. Addresses are validated per chain (EVM, Solana, Bitcoin, etc.).

Base URL​

https://api.orcarail.com/api/v1

Withdrawal Settings​

Get Withdrawal Settings​

Get the authenticated user's withdrawal settings (addresses by chain type, strategy, enabled flag).

GET /withdrawals/settings

Authentication​

  • Bearer Token (JWT) - Required

Response​

{
  "id": "uuid",
  "userId": "uuid",
  "addresses": {
    "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "solana": "GTtzwxqy67xx9DVESJjx28TgXqpc8xTqtiytgNMaQBTE",
    "bitcoin": "bc1q..."
  },
  "isEnabled": true,
  "strategy": 1,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Keys in addresses are chain types (evm, solana, bitcoin, tron, cosmos, polkadot, move, ton). Each address is validated for that chain. Returns null if no settings exist yet.

Update Withdrawal Settings​

Create or update withdrawal settings.

PUT /withdrawals/settings

Authentication​

  • Bearer Token (JWT) - Required

Request Body​

All fields are optional. Only include fields to update.

ParameterTypeRequiredDescription
addressesobjectNoWithdrawal addresses by chain type. Keys: evm, solana, bitcoin, etc. Values: address string for that chain. Validated against a network of that chain type.
isEnabledbooleanNoWhether withdrawals are enabled
strategynumberNoWithdrawal strategy (e.g. multi-network, bridge)

Response​

Same shape as GET; addresses is the key-value object. When auto-withdraw is enabled, at least one address is required.

Withdrawal Requests​

Create Withdrawal Request​

Create a new withdrawal request.

POST /withdrawals/requests

Authentication​

  • Bearer Token (JWT) - Required

Request Body​

ParameterTypeRequiredDescription
amountstringYesAmount to withdraw (e.g., "0.1")
tokenIdstringYesToken ID (UUID) to withdraw
sourceNetworkIdstringYesSource network ID (UUID)
destinationNetworkIdstringNoDestination network ID (UUID, optional)
addressstringYesDestination address (e.g., 0x...)
strategynumberYesWithdrawal strategy: 1 = multi-network, 2 = bridge. See strategy values.

Response​

{
  "id": "uuid",
  "userId": "uuid",
  "amount": "0.1",
  "tokenId": "uuid",
  "sourceNetworkId": "uuid",
  "destinationNetworkId": "uuid",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "strategy": 1,
  "status": "pending",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

List Withdrawal Requests​

List withdrawal requests for the authenticated user.

GET /withdrawals/requests

Authentication​

  • Bearer Token (JWT) - Required

Query Parameters​

ParameterTypeRequiredDescription
limitnumberNoMaximum number of requests to return

Response​

[
  {
    "id": "uuid",
    "userId": "uuid",
    "amount": "0.1",
    "tokenId": "uuid",
    "sourceNetworkId": "uuid",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "strategy": 1,
    "status": "completed",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

Withdrawal Summary​

Get Withdrawal Summary​

Get a summary of balances and withdrawal totals by network and token.

GET /withdrawals/summary

Authentication​

  • Bearer Token (JWT) - Required

Response​

{
  "byNetwork": [
    {
      "networkId": 1,
      "networkName": "Ethereum",
      "totalAmount": "100.50",
      "totalUsdcValue": "100.50"
    }
  ],
  "byToken": [
    {
      "tokenId": 1,
      "tokenSymbol": "USDC",
      "totalAmount": "100.50",
      "totalUsdcValue": "100.50"
    }
  ],
  "totals": {
    "totalEarnedUsdc": "1250.50",
    "totalWithdrawnUsdc": "500.0",
    "remainingUsdc": "750.5"
  }
}

Status Codes​

Status CodeDescription
200Success
201Created
400Bad Request
401Unauthorized
404Not Found
500Internal Server Error

See Also​