events.list(rail) returns a curated rail. events.search returns event references (slug, title,
startDate) and never markets; events.retrieve is the only complete catalog, merging the event’s
companion events and returning every active, unarchived, open market accepting orders. markets.retrieve resolves an outcome
asset under the same eligibility rule; prices.list({ asset }) returns pUSD history.
markets.screen ranks soon-resolving outcomes by executable buy price:
stakePusd: the book is walked to that size and pricePusd
is the resulting average, with fillableShares the shares it buys and quotedPricePusd the
top-of-book price before size, so their difference is the slippage at that stake. The band is applied once, to the achieved average, so a row quoted
inside the band with no depth behind the quote is excluded and a returned row is executable rather
than advertised. Rows also carry conditionId, volume24hPusd, sportsMarketType, line and
gameStartTime for ranking without a second call. Outcomes arrive grouped under their event: each
events[] entry carries the event slug (null for a market outside any event, which forms its
own group) and its outcomes. negRisk and groupItemTitle identify an outcome’s sibling legs,
and when negRisk is true exactly one of that event’s legs resolves YES, so a complete set costs
less than its guaranteed payout only when the legs’ asks sum below 1. orderBy ranks the scan; each
event is placed by its best-ranked outcome; sportsMarketTypes keeps only the sportsMarketType
values an event’s index names. tagSlug keeps only markets carrying that tag, and
excludeTagSlugs drops markets carrying any of those tags before their books are priced, so
excludeTagSlugs: ["sports"] returns the window without games. Every fillable outcome is returned;
scanned counts every market row the scan examined, readable or not, before any tag exclusion, and
truncated is true when the scan hit its page limit before the window ended, in which case an
exclusion only reaches the rows the scan reached.
Quote and create an order
spendPusd; a SELL uses shares, rounded down to venue precision. Quotes include fees and executable share rounding. Both require at least 1 pUSD of venue
value and should fit the session allocation. Results include the actual fill, price, collateral, and
settlement hashes. Writes use a run-scoped idempotency key and submit exactly once. Completed
trade and redemption links in Circuit activity and Terminal open Orbscan with the settlement hash.
orders.quote returns price, signedSharesChange, and expectedPusdAmount. Read the market’s question and outcomes[].name through markets.retrieve(asset).
Held positions expose conditionId through polymarketMetadata; redemption results also include it. Use position.size for session shares and nullable polymarketMetadata.entryPricePusd for session entry basis. Allocation metadata no longer contains duplicate contractAddress/decimals or wallet-wide shares, formattedShares, marketValuePusd, averagePricePusd, initialValuePusd, or P&L totals; existing agents using those fields must be updated.
Redeem positions
redeemed entries for both outcomes (including zero holdings), with asset, conditionId, shares, formattedShares, question, and outcome, plus transactionHashes. Unresolved or empty markets fail.
Allocation guidance
Invocation-start pUSD and outcome-token positions come fromagent.allocation. Size writes from it;
redemption uses pooled account inventory, so allocation is guidance there. Failures throw
ApiError with full engine evidence. See positions for the shape.