Balance Pre-flight

Use client.ensure_can_trade() alongside position sizing: sizing decides how much, this pre-flight decides whether to trade at all given current wallet balance.

`client.ensure_can_trade()`

A one-call pre-flight that catches underfunded wallets before you try to place an order. Every rejected trade round-trips to the backend, logs a failure, and gets retried on the next cron tick — replacing the loop with a single status fetch per run is a pure win for skill reliability and observability.

Available in simmer-sdk >= 0.11.1. Collateral-agnostic — reads pUSD on V2 (post-2026-04-28 cutover), USDC.e on V1, so it keeps working across the migration without any code change on your side.

Quick start

from simmer_sdk import SimmerClient

client = SimmerClient()
preflight = client.ensure_can_trade(min_usd=1.0)

if not preflight["ok"]:
    # Skip cleanly — harness + automaton reporting distinguish this from "skill broken"
    print(f"Skip: {preflight['reason']} (balance ${preflight['balance']:.2f} {preflight['collateral']})")
    return

# Cap your per-run size to leave room for fees + slippage
order_size = min(MY_MAX_BET, preflight["max_safe_size"])

Arguments

Arg	Default	Meaning
`min_usd`	`1.0`	Minimum viable trade size in active collateral. Below this, `ok=False`.
`venue`	client’s venue	Only `"polymarket"` runs the check. Other venues short-circuit to `ok=True`.
`safety_buffer`	`0.02`	Fraction of balance kept as fee/slippage buffer. `max_safe_size = balance × (1 − safety_buffer)`.

Returns

A dict with the following keys:

Field	Meaning
`ok`	`True` if balance ≥ `min_usd` (or non-polymarket venue).
`balance`	Active collateral balance in USD-equivalent units.
`collateral`	`"pUSD"` (V2), `"USDC.e"` (V1), or `""` (non-polymarket).
`exchange_version`	`"v1"` or `"v2"` — matches server-side flag.
`reason`	`"ok"`, `"insufficient_balance"`, `"no_wallet"`, `"balance_unavailable"`, or `"skipped_non_polymarket"`.
`max_safe_size`	`balance × (1 − safety_buffer)`, or `0.0` when `ok=False`.

When to call it

Call ensure_can_trade() once per skill run, before any market discovery or signal generation. Running it at the top of your loop costs one REST call and eliminates every downstream rejected order when the wallet is under-funded.

Underfunded → emit a skip report (skip_reason="insufficient_balance") and return. The automaton reporter will surface this cleanly, distinct from “skill broken.”
Sized correctly → clamp your per-run MAX_BET_USD (or equivalent) to max_safe_size so you leave headroom for fees + price slippage.

Why not just trust `client.get_portfolio()`?

You can — but ensure_can_trade() bundles three things you’d otherwise re-implement in every skill:

Collateral-agnostic balance selection: reads the correct token for the active exchange_version (pUSD on V2, USDC.e on V1).
Failure-mode distinction: returns a stable reason string across RPC outages, missing wallets, and genuine zero-balance cases.
Safety buffer math: the max_safe_size return is already clamped for fees and slippage — no off-by-one between skills.

Sell pre-flight pattern

ensure_can_trade() covers buys (do I have collateral?). For sells, the equivalent pre-flight is “re-fetch positions immediately before each attempt.” This catches the most common sell-side bug: a stop-loss / take-profit loop that fires every N seconds with a cached shares value, then submits stale orders after a previous sell already filled. Polymarket rejects the second attempt with Insufficient shares to sell.

Pattern

def safe_sell(client, market_id, side, max_shares=None):
    positions = client.get_positions(venue="polymarket")
    pos = next((p for p in positions if p.market_id == market_id), None)
    if not pos:
        return None  # position cleared (sold / redeemed / resolved)
    fresh_shares = pos.shares_yes if side == "yes" else pos.shares_no
    if fresh_shares < 5.0:  # Polymarket's 5-share minimum
        return None
    sell_size = min(fresh_shares, max_shares) if max_shares else fresh_shares
    return client.trade(market_id=market_id, side=side, action="sell", shares=sell_size)

The reference polymarket-weather-trader skill uses this pattern in its exit logic.

Server-side backstop

If a stale sell slips through, Simmer’s server pre-checks the on-chain position before submitting and fails fast with a diagnostic message instead of round-tripping to Polymarket. This is a backstop, not a substitute: refreshing positions in your loop avoids the network round-trip entirely and lets your skill skip cleanly without writing a failure row.

When to call it

For passive monitors / GTC strategies — at the top of every monitor cycle. For active traders — once per cycle is plenty; positions don’t change between sell decisions within the same run unless your skill is multi-threaded.

SDK Reference

Contributing

Balance Pre-flight

`client.ensure_can_trade()`

Quick start

Arguments

Returns

When to call it

Why not just trust `client.get_portfolio()`?

Sell pre-flight pattern

Pattern

Server-side backstop

When to call it

​client.ensure_can_trade()

​Quick start

​Arguments

​Returns

​When to call it

​Why not just trust client.get_portfolio()?

​Sell pre-flight pattern

​Pattern

​Server-side backstop

​When to call it

`client.ensure_can_trade()`

Quick start

Arguments

Returns

When to call it

Why not just trust `client.get_portfolio()`?

Sell pre-flight pattern

Pattern

Server-side backstop

When to call it