What is BalanceAllowanceParams in py_clob_client?

BalanceAllowanceParams is a data class that specifies which asset to query. Set asset_type to AssetType.COLLATERAL for USDC balance, or AssetType.CONDITIONAL with a token_id for outcome token balance. Import it from py_clob_client.clob_types.

What is the difference between get_balance and get_balance_allowance?

get_balance() returns only your USDC balance as a string in wei. get_balance_allowance() returns both your balance and your token allowance for a specific asset type. Use get_balance for quick checks and get_balance_allowance when you need to verify allowances are set for trading.

Why does get_balance return a string instead of a number?

get_balance() returns balance in wei as a string to avoid floating-point precision issues with large numbers. USDC uses 6 decimal places (1 USDC = 1,000,000 wei), so divide by 1e6 to get the USDC amount: balance_usdc = int(balance_wei) / 1e6.

What is AssetType.COLLATERAL vs AssetType.CONDITIONAL?

AssetType.COLLATERAL queries your USDC balance — the base currency used for trading on Polymarket. AssetType.CONDITIONAL queries your balance of a specific outcome token (YES or NO shares), which requires passing a token_id in BalanceAllowanceParams.

Does get_balance_allowance require authentication?

Yes. Both get_balance() and get_balance_allowance() require authentication. You must initialize ClobClient with your private key and chain_id, then call client.set_api_creds(client.create_or_derive_api_creds()) before using these methods.

py_clob_client get_balance_allowance: Polymarket Balance & Allowance Python Guide

Q: How do I check my balance with py_clob_client?

Use client.get_balance() for a quick USDC balance in wei, or client.get_balance_allowance(BalanceAllowanceParams(asset_type=AssetType.COLLATERAL)) for both balance and token allowance. Divide the balance by 1e6 to convert from wei to USDC.

get_balance_allowance() is the py_clob_client method that returns your USDC balance and token spending allowance on Polymarket. It tells you how much you can trade and whether your wallet has the required approvals. This page covers both get_balance_allowance() and the simpler get_balance(), including parameters, return types, wei conversion, and pre-trade validation patterns.

For the complete py_clob_client method reference covering all methods, see the py_clob_client Reference. For Kalshi’s equivalent balance endpoint, see the Prediction Market API Reference.

get_balance_allowance() Method

Signature

client.get_balance_allowance(params: BalanceAllowanceParams = None) -> dict

Parameters

Parameter	Type	Required	Description
`params`	`BalanceAllowanceParams`	No	Specifies which asset to query

BalanceAllowanceParams fields:

Field	Type	Description
`asset_type`	`AssetType`	`AssetType.COLLATERAL` for USDC, or `AssetType.CONDITIONAL` for outcome tokens
`token_id`	`str`	Required when `asset_type` is `CONDITIONAL` — the specific outcome token ID

Return Type

A dictionary with the following fields:

Field	Type	Description
`balance`	`str`	Balance in wei (1 USDC = 10^6 wei)
`allowance`	`str`	Token spending allowance in wei

Authentication required: Yes. You must call set_api_creds() before using this method.

Check USDC Balance and Allowance

The most common use case — check how much USDC you have available and whether trading is approved:

from py_clob_client.client import ClobClient
from py_clob_client.clob_types import BalanceAllowanceParams, AssetType

client = ClobClient(
    "https://clob.polymarket.com",
    key="<your-private-key>",
    chain_id=137
)
client.set_api_creds(client.create_or_derive_api_creds())

result = client.get_balance_allowance(
    BalanceAllowanceParams(asset_type=AssetType.COLLATERAL)
)

balance_usdc = int(result["balance"]) / 1e6
allowance_usdc = int(result["allowance"]) / 1e6

print(f"Balance:   {balance_usdc:.2f} USDC")
print(f"Allowance: {allowance_usdc:.2f} USDC")

Example output:

Balance:   1250.00 USDC
Allowance: 115792089237316195423570985008687907853269984665640564039457584007913129639935.00 USDC

A very large allowance value (the uint256 max) means unlimited approval is set — this is normal and expected after running the approval transaction.

Check Conditional Token Balance

Query how many YES or NO shares you hold for a specific outcome:

from py_clob_client.clob_types import BalanceAllowanceParams, AssetType

result = client.get_balance_allowance(
    BalanceAllowanceParams(
        asset_type=AssetType.CONDITIONAL,
        token_id="<outcome-token-id>"
    )
)

token_balance = int(result["balance"]) / 1e6
print(f"Token balance: {token_balance:.2f} shares")
print(f"Token allowance: {result['allowance']}")

get_balance() — Simple Balance Check

For a quick USDC balance check without allowance details:

Signature

client.get_balance() -> str

Example

from py_clob_client.client import ClobClient

client = ClobClient(
    "https://clob.polymarket.com",
    key="<your-private-key>",
    chain_id=137
)
client.set_api_creds(client.create_or_derive_api_creds())

balance_wei = client.get_balance()
balance_usdc = int(balance_wei) / 1e6
print(f"Balance: {balance_usdc:.2f} USDC")
# Example output: Balance: 1250.00 USDC

When to Use Each Method

Scenario	Use	Why
Quick balance check before an order	`get_balance()`	Simpler, returns just the number
Verify trading approvals are set	`get_balance_allowance()`	Returns allowance — essential for EOA wallets
Check outcome token holdings	`get_balance_allowance()`	Only way to query conditional token balances
Pre-trade validation in a bot	`get_balance_allowance()`	Catches both insufficient funds and missing approvals

Pre-Trade Balance Validation

A production pattern for validating funds before placing an order:

from py_clob_client.client import ClobClient
from py_clob_client.clob_types import (
    BalanceAllowanceParams, AssetType,
    OrderArgs, OrderType
)
from py_clob_client.order_builder.constants import BUY

def validate_and_place_order(client, token_id, price, size):
    """Check balance and allowance before placing a limit order."""

    # Step 1: Check USDC balance and allowance
    result = client.get_balance_allowance(
        BalanceAllowanceParams(asset_type=AssetType.COLLATERAL)
    )

    balance_usdc = int(result["balance"]) / 1e6
    allowance_usdc = int(result["allowance"]) / 1e6
    order_cost = price * size

    # Step 2: Validate sufficient balance
    if balance_usdc < order_cost:
        print(f"Insufficient balance: {balance_usdc:.2f} USDC "
              f"< order cost {order_cost:.2f} USDC")
        return None

    # Step 3: Validate sufficient allowance
    if allowance_usdc < order_cost:
        print(f"Insufficient allowance: {allowance_usdc:.2f} USDC. "
              f"Run approval transaction first.")
        return None

    # Step 4: Place the order
    order = OrderArgs(
        token_id=token_id,
        price=price,
        size=size,
        side=BUY
    )
    signed = client.create_order(order)
    response = client.post_order(signed, OrderType.GTC)

    print(f"Order placed: {response['orderID']}")
    print(f"Remaining balance: {balance_usdc - order_cost:.2f} USDC")
    return response

# Usage
client = ClobClient(
    "https://clob.polymarket.com",
    key="<your-private-key>",
    chain_id=137
)
client.set_api_creds(client.create_or_derive_api_creds())

validate_and_place_order(client, "<token-id>", price=0.45, size=100)

Wei Conversion Reference

Polymarket returns all balances in wei (micro-USDC). Here’s the conversion:

Wei Value	USDC Amount
`"1000000"`	1.00 USDC
`"500000"`	0.50 USDC
`"100000000"`	100.00 USDC
`"1250000000"`	1,250.00 USDC

Conversion formula:

# Wei to USDC
balance_usdc = int(balance_wei) / 1e6

# USDC to wei
balance_wei = int(balance_usdc * 1e6)

Common pitfall: Forgetting the wei conversion is the most frequent source of bugs with balance methods. A balance of "1000000" is 1 USDC, not 1 million USDC.

Common Errors

Error	Cause	Fix
`UNAUTHORIZED` or `403`	API credentials not set	Call `client.set_api_creds(client.create_or_derive_api_creds())` first
`KeyError: 'balance'`	Unexpected response format	Check that authentication succeeded — unauthenticated calls return different responses
Balance is `"0"` but you have funds	Wrong wallet type or funder address	Verify `signature_type` (0 for EOA, 1 for Magic) and `funder` address
Allowance is `"0"`	Token approval not set	Run the approval transaction: `polymarket approve set` via CLI, or submit on-chain
`ConnectionError`	API unreachable	Retry with backoff. See the Rate Limits Guide

CLI Equivalent

Check balance via the Polymarket CLI:

# Check USDC balance and allowance
polymarket clob balance --asset-type collateral

# Check conditional token balance
polymarket clob balance --asset-type conditional --token TOKEN_ID

# JSON output for scripting
polymarket -o json clob balance --asset-type collateral

get_balance_allowance() Method

Signature

Parameters

Return Type

Check USDC Balance and Allowance

Check Conditional Token Balance

get_balance() — Simple Balance Check

Signature

Example

When to Use Each Method

Pre-Trade Balance Validation

Wei Conversion Reference

Common Errors

CLI Equivalent

See Also