Wallet balances

Per-wallet token balances with optional USD valuation via SDP.

GET /v1/payments/wallets/{walletId}/balances returns the wallet's native SOL balance plus every SPL token balance held by a custody wallet — raw amount, human-readable amount, decimals, and optional USD valuation when a price source is configured. SOL is always prepended as the first entry and is represented with token: "SOL" and mint: "So11111111111111111111111111111111111111112".

Request

curl 'https://api.solana.com/v1/payments/wallets/privy_wallet_123/balances' \
  -H "Authorization: Bearer $SDP_API_KEY"

The response's data.walletBalances.balances array contains the token balances.

Response shape

The payload is wrapped in the standard data / meta envelope, with the balances under a walletBalances key:

response.json
{
  "data": {
    "walletBalances": {
      "walletId": "wal_abc123",
      "address": "3xYZa...2aBc",
      "balances": [
        {
          "token": "SOL",
          "mint": "So11111111111111111111111111111111111111112",
          "amount": "2500000000",
          "uiAmount": "2.5",
          "decimals": 9
        },
        {
          "token": "USDC",
          "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "amount": "1500000000",
          "uiAmount": "1500.00",
          "decimals": 6,
          "usdPrice": 1.0,
          "usdValue": 1500.0
        }
      ]
    }
  },
  "meta": { "requestId": "req_...", "timestamp": "2026-05-18T00:00:00.000Z" }
}

Per-balance fields:

FieldNotes
tokenToken symbol if known, otherwise the on-chain mint.
mintOn-chain mint address.
amountRaw amount in the smallest unit (string to preserve precision).
uiAmountHuman-readable decimal string — amount / 10^decimals.
decimalsToken's decimal count.
usdPricePer-token USD price; omitted when no pricing data is available.
usdValueTotal USD value (= usdPrice * uiAmount); omitted when pricing is unavailable.
confidentialReserved for confidential transfer balances; absent for standard balances.

Use cases

  • Account dashboards — display the contents of a custody wallet to its operator.
  • Pre-transfer balance checks — validate that a wallet has enough of a specific token before kicking off a payout batch.
  • Treasury accounting — periodic snapshots into an internal ledger.

Pricing freshness

usdPrice is a display estimate from Tokens.xyz. SDP caches successful snapshots for up to 60 seconds. Some source snapshots refresh hourly; SDP omits snapshots older than two hours or without a timestamp. The snapshot timestamp does not prove when its underlying price was observed.

Use an executable quote for a trade and an independently verified valuation for accounting. The on-chain amount and uiAmount remain the balance values. When pricing is unavailable, usdPrice and usdValue are absent. The omission means "unknown," not "$0.00."

Comparison to on-chain RPC

You can also enumerate SPL token balances by calling getTokenAccountsByOwner against a Solana RPC and decoding the returned token-account data. Reasons to use SDP's balances endpoint instead:

  • Token resolution — SDP resolves the mint to a symbol when it knows one; raw RPC returns mints only.
  • USD pricing — RPC has no concept of price.
  • No RPC dependency in your stack — one fewer external integration when you are already calling SDP.

Reasons to skip SDP and go to RPC directly:

  • Cluster-of-truth — you want the wallet's state at a specific slot for an audit.
  • Confidential transfer balances — full extension support is RPC-side.
  • Latency-sensitive paths — RPC is one hop closer to the cluster.
Is this page helpful?