Get wallet balances

Retrieves balances for a custody wallet.

GET/v1/payments/wallets/{walletId}/balancesRun in dashboard

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.

Requires an API key with the wallets.read action.

Path parameters

  • walletId · string · required · min length 1 · example privy_wallet_123

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

Query parameters

  • minimumSlot · string · pattern ^(0|[1-9]\d*)$

Headers

  • x-project-id · string · min length 1 · example prj_example

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

Responses

  • 200 Wallet balances

    • data · object · required

      Wallet balances response payload.

      • walletBalances · object · required

        Wallet balances details.

        • walletId · string · required · min length 1 · example privy_wallet_123

          Provider wallet ID — the walletId field returned by GET /v1/wallets.

        • address · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

          Wallet address.

        • balances · object[] · required

          Token balances.

          • token · string · required · example USDC

            Token symbol or mint address.

          • mint · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

            Token mint address.

          • amount · string · required · example 100000000

            Raw amount in smallest units.

          • uiAmount · string · required · example 100.00

            Token amount in UI units (decimal string).

          • decimals · integer · required · example 6

            Token decimals.

          • usdPrice · number · example 1

            Resolved USD price per token when available.

          • usdValue · number · example 100

            Resolved USD value of this balance when pricing is available.

          • confidential · boolean · example false

            Confidential balance flag (when applicable).

      • balanceReadContext · object

        • minimumSlot · integer · required · min 0 · max 9007199254740991

    • meta · object · required

      Response metadata.

      • requestId · string · required · min length 1 · example req_example

        Request identifier for tracing.

      • timestamp · string · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

  • 400 Bad Request

    • error · object · required

      Standard error payload.

      • code · string · required

        Machine-readable error code.

      • message · string · required

        Human-readable error message.

      • details · object

        Optional error details for debugging.

        • * · any

    • meta · object

      • requestId · string · min length 1 · example req_example

        Request identifier for tracing.

  • 401 Unauthorized

    Same fields as 400.

  • 403 Forbidden. Requires the wallets.read action: an API key must hold it (a module's manage or execute also covers its read), and a signed-in member's organization role must include it. Without it the error is INSUFFICIENT_PERMISSIONS and error.details.action names the action. Any other 403 names its own reason.

    Same fields as 400.

  • 404 Not Found

    Same fields as 400.

  • 409 Conflict

    Same fields as 400.

  • 500 Internal Server Error

    Same fields as 400.

  • 503 Service Unavailable

    Same fields as 400.

Example request

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

Example responses

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

Error responses use the standard error shape.

Is this page helpful?