Payments

Get wallet balances

Changed on Nov 2, 2026

Retrieves balances for a custody wallet. If any SOL or SPL balance read fails, returns 503 instead of partial or zero balances. Optional minimumSlot requires confirmed account state at or after that Solana slot; the response acknowledges the bound in data.balanceReadContext.minimumSlot. Wallet lifecycle and provisioning are managed through /v1/wallets.

get/v1/payments/wallets/{walletId}/balances

Request

Base URL
http://localhost:8787
URL
http://localhost:8787/v1/payments/wallets/{walletId}/balances
Auth
HTTP bearer

Path parameters

walletIdstring required

Provider wallet ID — the walletId field returned by GET /v1/wallets. The wallet record id and the public key are not accepted.

Example:privy_wallet_123

Query parameters

minimumSlotstring

Headers

x-project-idstring

Required for dashboard sessions. API keys use their assigned project.

Example:prj_example

Response

Wallet balances

Example response

{
  "data": {
    "walletBalances": {
      "walletId": "privy_wallet_123",
      "address": "So11111111111111111111111111111111111111112",
      "balances": [
        {
          "token": "USDC",
          "mint": "So11111111111111111111111111111111111111112",
          "amount": "100000000",
          "uiAmount": "100.00",
          "decimals": 6,
          "usdPrice": 1,
          "usdValue": 100
        }
      ]
    }
  },
  "meta": {
    "requestId": "req_example",
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}

Changes

Nov 2, 20269f0b1d561064 Revision changes
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
Oct 30, 2026f4a0135eca08 Revision changes
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status

Operation history (12 revisions)