events.list({ rail }) or events.search({ query }), which returns slug/title/startDate references. events.retrieve({ slug }) includes companion events and all readable active, unarchived, open markets accepting orders; malformed market rows are omitted with error diagnostics so healthy markets remain available. markets.retrieve({ asset }) reads any listed market, open or closed, with question/outcome names, acceptingOrders (false once it stops trading) resolving (true while a proposed UMA resolution is pending, when Circuit refuses buys) and the order rules preparation enforces: minimumNotional for a market buy’s value, fees included, and minimumSize and priceTick for a limit order, all null once the market stops taking orders (minimumSize is 0 when the market sets no minimum). prices.list({ asset }) returns ISO timestamps and decimal pricePusd history. Never invent token IDs.
markets.screen filters endsWithinMs, lowestPricePusd/highestPricePusd, minLiquidityPusd, stakePusd and sportsMarketTypes, ranking by orderBy. It uses execution’s book walk and rounding: pricePusd is the limiting price, estimatedShares the encoded quantity, and excludesFees=true. The price band applies to the limit. Screening omits funding and approval checks; orders.quote includes fees and Review checks readiness.
Screen results group outcomes under event slug, with null-slug markets forming their own groups. Rows include conditionId, volume24hPusd, sportsMarketType, line, gameStartTime, negRisk and groupItemTitle. An event ranks by its best outcome; sportsMarketTypes selects indexed market types. For negRisk groups exactly one leg resolves YES; a complete set costs less than its guaranteed payout only when asks sum below 1. tagSlug includes and excludeTagSlugs removes matching markets before pricing, such as excluding sports. Every fillable outcome is returned. scanned counts examined markets before tag exclusion, including unreadable rows; truncated means the scan stopped at its first 500 markets in orderBy order before the window ended, so exclusions cover only examined rows; raise minLiquidityPusd or shorten endsWithinMs to cover the rest.
orders.quote and orders.create take the order shape every venue shares with the outcome’s token id as asset: { kind: "spotBuy", asset, amount: { value } } spends at most value pUSD and { kind: "spotSell", asset, amount: { size } } sells size shares. Circuit charges no builder fee. A buy’s value includes Polymarket fees; a sell rounds shares down to venue precision; on create, size: "max" sells the session’s whole holding of that outcome. These fill-or-kill market orders require current ticks, including 0.005 and 0.0025; Circuit refuses with BELOW_MINIMUM, before anything is sent, a buy whose value is below the market’s minimumNotional from markets.retrieve, which is 1 pUSD after its taker fee. A limit order takes amount: { size } and execution: { kind: "limit", price, timeInForce, expiresAt? } and trades exactly size shares (two decimals) at the tick-aligned price or better: "gtc" rests until filled or canceled, "alo" rests as maker only (post-only) and is refused if it would cross, "ioc" fills what crosses and drops the rest, and expiresAt (at least 2 minutes ahead) ends a resting order on its own. Resting orders need the market’s minimumSize shares. Every order’s result is the venue order every venue returns; a limit order’s operation records each fill until the order fills, is canceled or expires. orders.listOpen() lists the session’s resting orders and orders.cancel({ orderId }) cancels one, completing once Polymarket reports it canceled or filled. Paper sessions refuse limit orders and cancels. Quote returns price, signedSharesChange and expectedPusdAmount, or null when the book cannot fill the order; create refuses that order. Create accepts the optional once name, rechecks live balances and submits once. A market order’s result is filled, with size the shares it bought or sold, limitPrice the worst pUSD per share it accepted and averageFillPrice the fills’ pUSD per share before fees, to 18 decimals truncated toward zero; its legs carry the pUSD it moved. Completed operations retain fills and settlement receipts; activity links open Orbscan.
Use the kind: "prediction" holding’s quantity for session shares and its nullable entryPriceUsd for historical basis; conditionId lives on that holding and in redemption results. Never replace missing basis with a wallet-wide average. Size trades from the pUSD and outcome holdings in agent.allocation; see holdings.
positions.redeem({ asset }, options?) selects one entire resolved binary market: all YES and NO account holdings redeem, including losing shares. Choose an outcome asset whose allocation holding marks isRedeemable; on-chain resolution and balance establish readiness. Deposit Wallets batch approval/redemption; eligible EOAs approve separately and pay Polygon gas. To redeem several markets, select one outcome per conditionId and call sequentially, retaining each completed operation.
Redemption returns one completed operation. result.redeemed includes both outcomes, including zero holdings, with asset, conditionId, shares, formattedShares, question and outcome. Losing holdings may return zero pUSD; unresolved or empty markets fail. Each operation retains its own identity and receipts. options can persist those references before execution.
positions.change(change, options?) takes one of three kinds. { kind: "split", asset, amountPusd } turns pUSD into as many shares of each outcome of the asset’s binary market; { kind: "merge", asset, shares } turns that many shares of each outcome back into pUSD. { kind: "convert", assets, shares } takes No outcomes of one negRisk event and turns shares of each, net of the market’s fee, into Yes shares of every other question plus pUSD for all but one converted question. Each checks balances first, batch approvals like redemption, settle on Polygon and return a null result; their movements are the operation’s legs. Paper sessions settle them against the same on-chain market terms.