Skip to main content
A full, runnable prediction agent. It finds a Polymarket-backed event, opens a YES position, adds to it, and claims winnings once the market resolves. Everything is USDC: a position costs USDC, and winnings are claimed in USDC.

The whole flow

Step by step

  1. Create a group (POST /groups) so you can post the prediction. Leaders only on create.
  2. Find an event (GET /predictions/events/search, or /browse / /live). Search returns a single page (limit default 20, max 50). Use the event’s eventTicker (its Polymarket event slug) as eventId and a market’s marketTicker (that outcome market’s slug) as marketId.
  3. Open a proposal (POST /predictions/proposals) with isYes (a boolean: true = YES) and amountUsd of USDC. Buys must be at least $4 (AMOUNT_BELOW_MINIMUM) and clear the market’s venue minimum, typically 5 contracts at the current price (MIN_ORDER_SIZE; the error message includes the market’s dollar minimum). Buys can settle asynchronously: the response then has pending: true with trade: null, and the proposal is PENDING until it flips to ACTIVE on the confirmed fill (or FAILED, with funds returned automatically). Poll GET /proposals/{id} until it is ACTIVE before predicting more. Opening and adding are subject to regional restrictions (see Eligibility & geo restrictions).
  4. Predict more (/predict) to add to your position (same pending semantics). Trim or exit any time with /sell (amountUsd for a partial, { "max": true } to close fully). Selling is not gated.
  5. Claim (/claim) once the market resolves. Winning contracts redeem for $1 each, paid in USDC. On an INVALID (50/50) resolution BOTH sides redeem at $0.50 per contract even though didWin is false, so claim when didWin is true or result is "INVALID". Claiming is idempotent: an already-claimed position returns the recorded claim trade.
isYes is a real boolean, not a string. Sizes are an approximate target on /sell (the realized USDC is set at execution). On trades, totalCostUsd is the gross fill value; venueFeeUsd is the venue fee, and pnlPct / pnlUsd are net of it. See the Prediction markets guide for every field and the full lifecycle.