Build a production trading bot

import os
from polyester import AsyncPolyester, POLYESTER_TESTNET_ENVIRONMENT

client = AsyncPolyester(
    environment=POLYESTER_TESTNET_ENVIRONMENT,
    api_key_id=os.environ["POLYESTER_API_KEY_ID"],
    api_private_key=os.environ["POLYESTER_API_PRIVATE_KEY"],
    default_account_id=os.environ["POLYESTER_ACCOUNT_ID"],
)
await client.wait_for_catalogs()

Catalog readiness is a hard startup gate. Decimal order helpers must use the backend's actual price and quantity scales; a trading system should never fall back to an assumed scale. For a subaccount-scoped key, attach an API-key policy that permits ledger reads and the trading mutations this bot uses. The key policy is separate from, and intersects with, subaccount policy.

book_state: dict[str, object] = {}
book_sub = await client.orderbook.create_subscription(
    symbol="BTC-USDT",
    depth=20,
    on_sequence_gap=lambda: print("book gap; waiting for refresh"),
    on_snapshot_refresh=lambda: print("book refreshed"),
)

async def consume_books() -> None:
    async with book_sub:
        async for book in book_sub:
            if not book.bids or not book.asks:
                continue
            book_state["best_bid"] = book.bids[0].price
            book_state["best_ask"] = book.asks[0].price
            book_state["book_seq"] = book.book_seq

Use the managed subscription instead of applying raw deltas yourself. It fetches an initial snapshot, detects sequence gaps, and refetches after reconnects. Pause quoting whenever the book is empty, crossed, stale, or awaiting refresh.

from polyester import format_ledger_u128

balances = await client.balances.list()
for balance in balances.balances:
    print(balance.asset_id, "available", format_ledger_u128(balance.available))

Balance components are raw ledger u128 strings at ledger scale 18. Format them once for display; keep the raw values for sizing and accounting.

Orders reserve trading balance, not funding balance. Size from each Asset's available field, which already accounts for active reservations, not raw trading. Missing or empty available means zero spendable headroom. Held amounts are each Asset's reserved. Cap each quote by all of:

• available trading balance,
• API-key policy maximum order size,
• strategy inventory and notional limits,
• pair minimum quantity/notional and step size,
• client.catalogs.order_limits_for_symbol(...).

A buy limit order that pays its fee in the quote Asset is sized with the reserve fee rate, or the post-only reserve rate for a post-only order; see Fees. Use integer or Decimal arithmetic, never binary floating point.

from uuid import uuid4

async def place_quote(side: str, price: str, qty: str) -> tuple[str, str]:
    client_order_id = f"trader-{side}-{uuid4().hex[:20]}"
    created = await client.orders.create(
        symbol="BTC-USDT",
        side=side,
        order_type="limit",
        tif="gtc",
        price=price,
        qty=qty,
        post_only=True,
        client_order_id=client_order_id,
    )
    # "accepted" is admission only; the read model may not show the order yet.
    return client_order_id, created.order_id

Keep the same ID if you retry the same logical quote after an ambiguous transport failure. Generate a new ID only for a new quote decision. A post_only rejection means the price would cross; recompute from a fresh book instead of retrying unchanged.

from uuid import uuid4

armed = await client.orders.cancel_all_after(
    timeout_sec=30,
    symbol="BTC-USDT",
    request_id=f"dms-{uuid4().hex[:20]}",
)
assert armed.status == "armed"

Refresh the switch on a cadence comfortably below its timeout. If refresh fails, stop creating orders and assume the backend will cancel them at expiry. Disable it only after targeted shutdown cleanup is confirmed.

batch_replace records admission, not a final execution outcome. An item that keeps the price, does not raise the total quantity and keeps the client order ID is amended in place (action_taken is "amended"): keep tracking old_order_id. Any other item is replaced (action_taken is "replaced"): on a successful receipt, its predecessor order and client IDs are stale. Persist the new client order ID and switch immediately to its replacement_order_id; a predecessor lookup may return not_found / ORDER_UNKNOWN, which is expected. An admitted item can still be refused when applied: it then reads rejected, the order keeps its previous price and quantity, and no successor exists. Use wait_batch_replace to poll through admitted, working, rejected, and terminal.

For a quote-refresh loop, use is_batch_replace_settled(status) only to decide that every item is working, rejected, or terminal. working means the successor, or the amended order, is live, not that execution is final. Persist and reuse the same request_id after an ambiguous retry. Do not send another replacement against a stale predecessor.

from polyester import PolyesterApiError, is_order_already_terminal
from polyester.models import ClientOrderId

async def bot_open_orders(prefix: str = "trader-"):
    page = await client.orders.list_open(limit=100)
    return [order for order in page.orders if order.client_order_id.startswith(prefix)]

async def cancel_bot_order(client_order_id: str) -> None:
    try:
        await client.orders.cancel(
            key=ClientOrderId(client_order_id),
            symbol="BTC-USDT",
        )
    except PolyesterApiError as exc:
        if not is_order_already_terminal(exc) and exc.code != "ERROR_CODE_ORDER_UNKNOWN":
            raise

After a timeout, reconnect, or process restart:

1. list open orders,
2. select only IDs owned by this bot,
3. compare them with persisted quote intent,
4. cancel stale quotes,
5. place only missing quotes.

Do not use account-wide cancel_all as bot-ownership cleanup. A targeted cleanup cancel refused with ERROR_CODE_ORDER_ALREADY_TERMINAL or ERROR_CODE_ORDER_UNKNOWN is idempotent success: the owned order may have filled or left the book after the snapshot. Every other cancel error remains an error. Do not assume a timeout means the create was unapplied.

Persist quote intent before sending mutations and install SIGINT / SIGTERM handlers. On shutdown:

1. stop the quote producer,
2. close the managed book and private subscriptions,
3. call bot_open_orders() and cancel_bot_order() for each owned ID,
4. confirm those IDs disappear from list_open,
5. close the client.

If cleanup cannot be confirmed, leave the dead-man switch armed and alert an operator.