Overview

The Balances API allows you to check available funds for both your AI Agent and your customers. A balance is considered “spendable” when:

  • Funds have been fully verified and received
  • Funds aren’t reserved for pending tasks

Check Agent Balance

Check your AI Agent’s available balance in a specific currency:

agent_balance = payman.balances.get_spendable_balance('USD')
print(f"Available balance: ${agent_balance}")  # e.g., "Available balance: $150.00"

Parameters

ParameterDescription
currencyCurrency code (e.g., ‘USD’, ‘USDC’)

Check Customer Balance

Check a specific customer’s available balance:

customer_balance = payman.balances.get_customer_balance(
    customer_id='cust_123',  # Customer ID
    currency='USD'          # Currency
)
print(f"Customer balance: ${customer_balance}")

Parameters

ParameterDescription
customer_idYour system’s customer ID or Payman’s customer ID
currencyCurrency code (e.g., ‘USD’, ‘USDC’)

Response Format

Both methods return a float representing the spendable balance in the currency’s units:

# Examples
50.00    # $50.00 USD
1.50     # $1.50 USD
0.00     # No available balance

For cryptocurrencies, the appropriate decimal places are used:

1.000000  # 1 USDC
0.500000  # 0.5 USDC

Type Hints

from decimal import Decimal
from typing import Union

def get_customer_funds(
    customer_id: str,
    currency: str = 'USD'
) -> Union[float, Decimal]:
    return payman.balances.get_customer_balance(
        customer_id=customer_id,
        currency=currency
    )

Error Handling

try:
    balance = payman.balances.get_customer_balance(
        customer_id='cust_123',
        currency='USD'
    )
except PaymanError as e:
    if e.code == 'customer_not_found':
        print('Customer not found')
    elif e.code == 'invalid_currency':
        print('Invalid currency specified')
    else:
        print('Failed to get balance:', e.message)

Using Both Together

You can check both balances to compare available funds:

async def check_all_balances(customer_id: str, currency: str) -> None:
    try:
        agent_balance = payman.balances.get_spendable_balance(currency)
        customer_balance = payman.balances.get_customer_balance(
            customer_id=customer_id,
            currency=currency
        )
        
        print(f"Agent balance: ${agent_balance}")
        print(f"Customer balance: ${customer_balance}")
    except PaymanError as e:
        print(f"Error checking balances: {e.message}")

Balances are always returned in the currency’s natural units. For USD, this means dollars (e.g., 10.50 is $10.50). For USDC, this means whole tokens with 6 decimal places (e.g., 1.000000 is 1 USDC).