Payments

Get wallet balances

Retrieves balances for a custody wallet. Wallet lifecycle and provisioning are managed through /v1/wallets.

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

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

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

Headers

x-project-idstring

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Example:prj_example

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

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

Changed in 1 of the 10 revisions of this API.41

Aug 15, 20263e302bba538641See the full diff
- ●
  added the new SERVICE_UNAVAILABLE enum value to the error/code response property for the response status 401
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the error/code response property for the response status 403
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the error/code response property for the response status 404
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the error/code response property for the response status 500
  response-property-enum-value-added
- ○
  added the non-success response with the status 409
  response-non-success-status-added

Full history