Layer 3 — Trading

py_clob_client get_balance_allowance — Check Your pUSD Balance on Polymarket (CLOB V2)

Q: "How do I check my balance with py_clob_client?"

"Use client.get_balance_allowance(BalanceAllowanceParams(asset_type=AssetType.COLLATERAL)) — it returns both your balance and token allowance. In CLOB V2 there is no standalone get_balance(); get_balance_allowance is the way. The balance is your pUSD balance in wei (CLOB V2 migrated collateral from USDC.e to pUSD); divide by 1e6 to convert."

Q: "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 your pUSD balance, or AssetType.CONDITIONAL with a token_id for outcome token balance. In CLOB V2, import it from py_clob_client_v2."

Q: "What is the difference between get_balance and get_balance_allowance?"

"In CLOB V2 there is no get_balance() — it was removed. Use get_balance_allowance(), which returns both your balance and your token allowance for a given asset type. If you're porting V1 code that called get_balance(), replace it with get_balance_allowance(BalanceAllowanceParams(asset_type=AssetType.COLLATERAL)) and read the balance field."

Q: "Why does get_balance_allowance return a string instead of a number?"

"It returns the balance in wei as a string to avoid floating-point precision issues. pUSD uses 6 decimal places (1 pUSD = 1,000,000 wei), so divide by 1e6 to get the pUSD amount: balance_pusd = int(result['balance']) / 1e6."

Q: "What is AssetType.COLLATERAL vs AssetType.CONDITIONAL?"

"AssetType.COLLATERAL queries your pUSD balance — the collateral currency used for trading on Polymarket since CLOB V2 (it replaced USDC.e). AssetType.CONDITIONAL queries your balance of a specific outcome token (YES or NO shares), which requires passing a token_id in BalanceAllowanceParams."

Q: "Does get_balance_allowance require authentication?"

"Yes. get_balance_allowance() requires authentication. Initialize ClobClient with your private key and chain_id, then call client.set_api_creds(client.create_or_derive_api_key()) before using it. (CLOB V2 renamed create_or_derive_api_creds() to create_or_derive_api_key().)"

By AgentBets.ai Research Team March 3, 2026May 25, 2026 · 8 min read

How to check your pUSD balance and token allowance on Polymarket with py-clob-client-v2. Covers get_balance_allowance, BalanceAllowanceParams, AssetType, wei conversion, and Python examples (CLOB V2 — get_balance() was removed).

py_clob_client get_balance_allowance — Check Your pUSD Balance on Polymarket (CLOB V2)

get_balance_allowance() is the py-clob-client-v2 method that returns your pUSD 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 get_balance_allowance() (and update_balance_allowance()), including parameters, return types, wei conversion, and pre-trade validation patterns.

⚠️ CLOB V2 (live April 28, 2026). Two things changed for balances: (1) collateral migrated from USDC.e to pUSD (an ERC-20 backed 1:1 by USDC), and (2) the standalone get_balance() method was removed — use get_balance_allowance() instead. The package is py-clob-client-v2 (from py_clob_client_v2 import ...); the V1 py-clob-client no longer works on production. See Migrating to CLOB V2.

For the complete V2 method reference, see the py-clob-client-v2 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 pUSD, or `AssetType.CONDITIONAL` for outcome tokens
`token_id`	`str`	Required when `asset_type` is `CONDITIONAL` — the specific outcome token ID
`signature_type`	`int`	Optional — override the client’s signature type for this lookup (default `-1`)

Return Type

A dictionary with the following fields:

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

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

Check pUSD Balance and Allowance

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

from py_clob_client_v2 import ClobClient, BalanceAllowanceParams, AssetType

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

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

balance_pusd = int(result["balance"]) / 1e6
allowance_pusd = int(result["allowance"]) / 1e6

print(f"Balance:   {balance_pusd:.2f} pUSD")
print(f"Allowance: {allowance_pusd:.2f} pUSD")

Example output:

Balance:   1250.00 pUSD
Allowance: 115792089237316195423570985008687907853269984665640564039457584007913129639935.00 pUSD

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_v2 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() — Removed in V2

There is no client.get_balance() method in CLOB V2. The standalone balance method was removed; get_balance_allowance() (above) is the single way to read your balance. If you’re porting V1 code:

# V1 (no longer works):
# balance_wei = client.get_balance()

# V2 equivalent:
result = client.get_balance_allowance(
    BalanceAllowanceParams(asset_type=AssetType.COLLATERAL)
)
balance_pusd = int(result["balance"]) / 1e6
print(f"Balance: {balance_pusd:.2f} pUSD")

Refresh the Cached Value: update_balance_allowance()

After an on-chain deposit or approval, the CLOB may not reflect the change immediately. Call update_balance_allowance() with the same params to force a refresh:

client.update_balance_allowance(
    BalanceAllowanceParams(asset_type=AssetType.COLLATERAL)
)

When to Use Each Method

Scenario	Use	Why
Read your pUSD balance	`get_balance_allowance()`	The only balance method in V2 (`get_balance()` is gone)
Verify trading approvals are set	`get_balance_allowance()`	Returns allowance — essential for EOA wallets
Check outcome token holdings	`get_balance_allowance()`	Pass `AssetType.CONDITIONAL` with a `token_id`
After a deposit/approval	`update_balance_allowance()`	Forces the CLOB to re-read on-chain state

Pre-Trade Balance Validation

A production pattern for validating funds before placing an order:

from py_clob_client_v2 import (
    ClobClient, BalanceAllowanceParams, AssetType,
    OrderArgs, OrderType, PartialCreateOrderOptions, Side,
)

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

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

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

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

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

    # Step 4: Place the order
    response = client.create_and_post_order(
        order_args=OrderArgs(token_id=token_id, price=price, size=size, side=Side.BUY),
        options=PartialCreateOrderOptions(tick_size="0.01"),
        order_type=OrderType.GTC,
    )

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

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

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

Wei Conversion Reference

Polymarket returns all balances in wei (micro-pUSD). pUSD uses 6 decimals, same as USDC.e did — so the conversion is unchanged:

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

Conversion formula:

# Wei to pUSD
balance_pusd = int(balance_wei) / 1e6

# pUSD to wei
balance_wei = int(balance_pusd * 1e6)

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

Common Errors

Error	Cause	Fix
`AttributeError: get_balance`	Calling the removed V1 method	Use `get_balance_allowance(BalanceAllowanceParams(asset_type=AssetType.COLLATERAL))`
`UNAUTHORIZED` or `403`	API credentials not set	Call `client.set_api_creds(client.create_or_derive_api_key())` 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 = EOA, 1 = POLY_PROXY, 2 = GNOSIS_SAFE, 3 = POLY_1271) and `funder`. Also confirm you’ve wrapped USDC.e → pUSD
Allowance is `"0"`	Token approval not set	Approve the V2 Exchange contracts on-chain (EOA only), then `update_balance_allowance()`
`ConnectionError`	API unreachable	Retry with backoff. See the Rate Limits Guide

Frequently Asked Questions

How do I check my balance with py_clob_client?

Use client.get_balance_allowance(BalanceAllowanceParams(asset_type=AssetType.COLLATERAL)) — it returns both your balance and token allowance. In CLOB V2 there is no standalone get_balance(); get_balance_allowance is the way. The balance is your pUSD balance in wei (CLOB V2 migrated collateral from USDC.e to pUSD); divide by 1e6 to convert.

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 your pUSD balance, or AssetType.CONDITIONAL with a token_id for outcome token balance. In CLOB V2, import it from py_clob_client_v2.

What is the difference between get_balance and get_balance_allowance?

In CLOB V2 there is no get_balance() — it was removed. Use get_balance_allowance(), which returns both your balance and your token allowance for a given asset type. If you're porting V1 code that called get_balance(), replace it with get_balance_allowance(BalanceAllowanceParams(asset_type=AssetType.COLLATERAL)) and read the balance field.

Why does get_balance_allowance return a string instead of a number?

It returns the balance in wei as a string to avoid floating-point precision issues. pUSD uses 6 decimal places (1 pUSD = 1,000,000 wei), so divide by 1e6 to get the pUSD amount: balance_pusd = int(result['balance']) / 1e6.

What is AssetType.COLLATERAL vs AssetType.CONDITIONAL?

AssetType.COLLATERAL queries your pUSD balance — the collateral currency used for trading on Polymarket since CLOB V2 (it replaced USDC.e). 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. get_balance_allowance() requires authentication. Initialize ClobClient with your private key and chain_id, then call client.set_api_creds(client.create_or_derive_api_key()) before using it. (CLOB V2 renamed create_or_derive_api_creds() to create_or_derive_api_key().)