---
title: "POST /payments/getPaymentInstrumentBalance"
method: POST
path: "/payments/getPaymentInstrumentBalance"
---

# POST /payments/getPaymentInstrumentBalance

`POST /payments/getPaymentInstrumentBalance`

Get the balance of a payment instrument.

## Headers

- `X-Amzn-Bedrock-AgentCore-Payments-User-Id` string
- `X-Amzn-Bedrock-AgentCore-Payments-Agent-Name` string — The agent name associated with the payment request.

## Request body

- object
  - `paymentManagerArn` string, required — The ARN of the payment manager that owns this payment instrument.
  - `paymentConnectorId` string, required — The ID of the payment connector associated with this instrument.
  - `paymentInstrumentId` string, required — The ID of the payment instrument to query balance for.
  - `chain` 'BASE' | 'BASE_SEPOLIA' | 'ETHEREUM' | 'SOLANA' | 'SOLANA_DEVNET', required — Supported blockchain chain identifiers for balance queries. Each value maps to a specific chain supported by the underlying providers (Privy, Coinbase).
  - `token` 'USDC', required — Supported tokens for instrument balance queries. Only tokens supported for X402 payments are returned.

## Response `200`

Success

- GetPaymentInstrumentBalanceResponse — Response structure for getting payment instrument balance.
  - `paymentInstrumentId` string, required — The ID of the payment instrument.
  - `tokenBalance` object, required — The balance of the supported token on the requested chain.
    - `amount` string, required — Raw balance in the smallest denomination (e.g., USDC base units where 1 USDC = 1000000).
    - `decimals` integer, required — Number of decimal places for the token (e.g., 6 for USDC).
    - `token` 'USDC', required — The supported token for this balance.
    - `network` 'ETHEREUM' | 'SOLANA', required — The blockchain network family (ETHEREUM or SOLANA).
    - `chain` 'BASE' | 'BASE_SEPOLIA' | 'ETHEREUM' | 'SOLANA' | 'SOLANA_DEVNET', required — The specific blockchain chain.

## Other responses

- `480` — AccessDeniedException
- `481` — ValidationException
- `482` — ResourceNotFoundException
- `483` — ThrottlingException
- `484` — InternalServerException

---

[API](https://skmtc.net/aws/apis/bedrock-agentcore.md) · [All operations](https://skmtc.net/aws/apis/bedrock-agentcore/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/bedrock-agentcore/versions/79623b33d495/schema)