Polymarket

End-to-end playbook for Polymarket through OpenFinance — research, pricing, order placement, approvals, and user data.

Prerequisite (for trading; data endpoints are public)

User completed
```
openfin-setup
```
(API key + EVM wallet delegation).
Approvals in place —
```
GET /agent/polymarket/approvals
```
to check,
```
POST /agent/polymarket/approvals
```
to set any missing. One-time gas cost.
Wallet holds MATIC on Polygon for gas and USDC.e (not native USDC) for trading.

Research endpoints (public, no auth)

Events (Gamma API)

Events group related prediction markets — e.g. one "2024 US Election" event contains separate candidate markets.

GET /agent/polymarket/events
— Browse events from the world's largest prediction market. Returns a list with metadata, outcomes, volumes, and current status. Optional query params:
```
limit
```
,
```
offset
```
,
```
active
```
(ongoing),
```
closed
```
(finished),
```
archived
```
(historical),
```
order
```
(e.g.
```
desc
```
),
```
ascending
```
,
```
slug
```
,
```
tag_id
```
. Use for sports betting odds (IPL, FIFA, NBA, NFL, F1, UFC, cricket, football), political predictions (elections, policy, government), crypto/finance forecasts, entertainment, or any trending real-world event.
GET /agent/polymarket/events/:eventId
— Single event by ID. Returns metadata, market information, outcomes, volume, liquidity, current probabilities.
GET /agent/polymarket/events/slug/:slug
— Same as above, looked up by URL slug.
GET /agent/polymarket/events/:eventId/volume
— Real-time trading volume for the event. Useful for gauging attention / money flow on a sports match, election, or trending topic.

Markets

GET /agent/polymarket/markets
— List prediction markets with current prices (implied probabilities), volumes, liquidity, and outcome details. Use to browse for sports, politics, crypto, entertainment, trending events. Optional filters:
```
limit
```
,
```
offset
```
,
```
active
```
,
```
closed
```
,
```
slug
```
,
```
market_id
```
,
```
token_id
```
,
```
condition_id
```
,
```
tag_id
```
,
```
liquidity_min
```
,
```
volume_min
```
,
```
start_date_min
```
,
```
start_date_max
```
,
```
end_date_min
```
,
```
end_date_max
```
.
GET /agent/polymarket/markets/:marketId
— Single market by numeric ID. Returns prices, orderbook depth, volume, liquidity, outcome details.

GET /agent/polymarket/markets/slug/:slug
— Same by URL slug.

GET /agent/polymarket/markets/cid/:conditionId
— Same by on-chain CTF condition ID (bytes32 hex). Useful when you already have the condition ID from a user's position.

Every market response contains:

```
condition_id
```
— on-chain CTF condition identifier
```
tokens
```
— YES/NO outcome tokens with their
```
token_id
```
s
```
min_tick_size
```
— required for correct
```
tickSize
```
on orders
```
neg_risk
```
— if true, pass
```
negRisk: true
```
on orders and approvals

Search

GET /agent/polymarket/public-search?q=<query>
— Search across all events and markets by keyword. Returns matching entries with relevance scoring. Use when the user names a topic — "IPL winner", "FIFA World Cup", "US elections", "Bitcoin price", "Trump", "Modi", "Champions League" — or any trending event, to find betting odds and probabilities on real-world outcomes.

Pricing (CLOB API)

GET /agent/polymarket/orderbook/:tokenId
— Current orderbook (bids and asks) for a specific outcome token. Returns arrays of buy and sell orders at different price levels with sizes and depths. Use to see market liquidity and available prices before placing an order.
POST /agent/polymarket/orderbooks
body
```
{tokenIds: [...]}
```
— Same as above but for multiple tokens in a single request. Returns a map of tokenId → orderbook. More efficient than many individual calls.
GET /agent/polymarket/price/mid/:tokenId
— Mid price for a token, representing the market-implied probability
```
(0, 1)
```
. Use to check "what are the odds" or "what is the probability" of an outcome.
GET /agent/polymarket/price/:tokenId?side=BUY
— Best BUY or SELL price for the token.
```
side
```
query param is required:
```
BUY
```
or
```
SELL
```
.
GET /agent/polymarket/prices
— Mid prices for every active outcome token. Returns a map of token ID → probability. Use for scanning odds across all active markets at once.
GET /agent/polymarket/spread/:tokenId
— Bid-ask spread for the token (best ask − best bid). Tight spread = good liquidity; wide = thin book.
GET /agent/polymarket/last-trade-price/:tokenId
— Price of the most recent executed trade for the token.
GET /agent/polymarket/trades/:marketSlug
(
```
?limit=50&offset=0
```
) — Recent trade tape for a market (by slug). Returns trades with prices, sizes, timestamps, and side (buy/sell). Use to analyze betting activity and see how odds are shifting.

Market data (Data API)

GET /agent/polymarket/market/:conditionId/open-interest
— Total value locked in the market. Returns capital committed to each outcome and overall market size.
GET /agent/polymarket/market/:marketId/volume
— Historical + current volume statistics for the market.

GET /agent/polymarket/market/:marketId/liquidity
— Current and historical liquidity depth.

GET /agent/polymarket/market/:marketId/trades
(
```
?limit=50
```
) — Detailed trade history with metadata (fuller shape than the CLOB
```
/trades
```
endpoint).

User data (public, address-scoped)

:address

= user's Polygon EVM address (their Privy EVM wallet address).

GET /agent/polymarket/user/:address/positions
— Active positions held by the user. Returns outcome tokens, quantities, entry prices, current values, and unrealized PnL per position.
GET /agent/polymarket/user/:address/trades
(
```
?limit=50&offset=0
```
) — Trade history with prices, sizes, timestamps, markets, outcomes. Use to analyze trading patterns and performance.
GET /agent/polymarket/user/:address/portfolio
— Full portfolio overview: total value, all positions, realized/unrealized PnL, win rate, performance metrics.
GET /agent/polymarket/user/:address/pnl
— Standalone PnL stats: realized, unrealized, total, historical performance.

Trading endpoints

All require

x-api-key: open_…

. Signing is EIP-712 with the caller's Privy-backed Polygon wallet; first call per user derives and caches the Polymarket L2 API credentials server-side.

Placing orders

POST /agent/polymarket/order
— Place a limit order (GTC or GTD) on the Polymarket CLOB. Body fields:

json

{
  "tokenID": "...",          // CLOB outcome asset ID (NOT market/condition ID)
  "price": 0.42,             // probability 0.0–1.0
  "size": 10,                // conditional token units
  "side": "BUY",             // "BUY" | "SELL"
  "orderType": "GTC",        // default "GTC"; "GTD" requires expiration
  "tickSize": "0.01",        // default "0.01"; some markets need "0.001" / "0.0001"
  "negRisk": false,          // true for multi-outcome neg-risk markets
  "postOnly": false,         // only accept if maker (reject if marketable)
  "expiration": 1735689600   // Unix seconds, required when orderType = "GTD"
}

Returns the order ID and posting status. Use for user prompts like "buy 10 shares at 0.42" or "place a resting bid at X".

POST /agent/polymarket/order/market
— Place a market order (FOK or FAK). For BUY,

amount

is USDC to spend; for SELL,

amount

is shares to sell.

json

{
  "tokenID": "...",
  "amount": 10,              // BUY: USDC to spend · SELL: shares to sell
  "side": "BUY",
  "price": 0.42,             // optional cap; omit for pure market
  "orderType": "FOK",        // default "FOK" (all-or-nothing) | "FAK" (fill-and-kill)
  "tickSize": "0.01",
  "negRisk": false
}

Use for "buy now" intents. FOK fails if full size can't fill; FAK fills what it can and cancels the rest.

POST /agent/polymarket/orders
— Post multiple limit orders in one batch. Each order is individually signed then posted together. Body:

{orders: [ { tokenID, price, size, side, orderType?, tickSize?, negRisk?, expiration? }, ... ], postOnly?: boolean}

. Use for ladder-quoting.

Reading orders

GET /agent/polymarket/order/:orderId
— Get a single order by ID. Returns full order record.
GET /agent/polymarket/orders
(
```
?id=&market=&asset_id=
```
) — Get all open orders for the authenticated user. Optional filter by
```
id
```
,
```
market
```
(condition_id), or
```
asset_id
```
(token_id).
GET /agent/polymarket/order/:orderId/scoring
— Check whether an order is currently scoring for Polymarket liquidity rewards. Returns scoring status.

Cancelling orders

DELETE /agent/polymarket/order/:orderId
— Cancel a single open order by order ID.
DELETE /agent/polymarket/orders
body
```
{orderHashes: [...]}
```
— Cancel multiple orders by their on-chain order hashes (batch).
DELETE /agent/polymarket/orders/all
— Cancel every open order for the authenticated user (nuke).
DELETE /agent/polymarket/orders/market
body
```
{market, asset_id}
```
— Cancel all open orders on a given market (condition_id) or asset (token_id).

Approvals (one-time, on-chain)

Before any trading, USDC.e + CTF must be approved to Polymarket contracts. The backend handles USDC.e (not pUSD/native USDC) and the V1 exchange + conditional tokens spenders.

GET /agent/polymarket/approvals
(
```
?negRisk=true
```
) — Read current on-chain allowances for Polymarket exchange contracts. Call before trading to confirm the wallet has approved USDC.e + CTF movement. Returns one entry per (token, spender) pair with
```
approved: boolean
```
. Pass
```
negRisk=true
```
to also include NegRiskAdapter/NegRiskExchange approvals — required if trading multi-outcome markets.
POST /agent/polymarket/approvals
body
```
{negRisk?: boolean}
```
— Submit approval transactions for any missing allowance. Idempotent — only approves what's missing. Returns per-entry status with tx hashes for newly-submitted approvals. User's wallet pays MATIC gas on Polygon.

Builder attribution (optional)

POLYMARKET_BUILDER_CODE

is set in backend env, orders are auto-tagged for fee attribution. Builder registration is an off-chain onboarding with Polymarket — fees only flow once they've onboarded your code. Until then, tagging is a no-op (but harmless).

POST /agent/polymarket/builder/api-key
— Create a builder API key tied to the caller's wallet. Returns
```
key
```
/
```
secret
```
/
```
passphrase
```
used to earn attribution fees on orders posted with your builder code.
GET /agent/polymarket/builder/api-keys
— List the caller's builder API keys.

DELETE /agent/polymarket/builder/api-key
— Revoke the caller's builder API key.

GET /agent/polymarket/builder/trades
(

?taker=&maker=&market=&asset_id=&next_cursor=

) — List trades attributed to this backend's configured builder code. Requires

POLYMARKET_BUILDER_CODE

set server-side.

Pick the right order type

Route / type	When to use
`/order` (GTC)	"Buy X shares at Y" — resting limit until fill or cancel
`/order` (GTD)	Same but auto-cancels at `expiration`
`/order/market` (FOK)	"Buy now" all-or-nothing fill
`/order/market` (FAK)	Best-effort fill, cancel rest
`/orders` batch	Ladder quoting — multiple price levels atomically

Required parameters

Param	What	Gotchas
`tokenID`	CLOB outcome asset ID	Different from market/condition ID. One per YES/NO side. Read from market's `tokens` array.
`price`	Probability as decimal `0.0–1.0`	`0.42` = 42¢. NOT `42` or `"42%"` .
`size` (limit)	Conditional token units	USDC spend ≈ `size * price` .
`amount` (market)	Side-dependent	BUY: USDC to spend. SELL: shares.
`side`	`"BUY"` or `"SELL"`	Case-sensitive.
`tickSize`	Min price increment	Default `0.01` . Some markets need `0.001` or `0.0001` . Wrong tick → 400.
`negRisk`	Multi-outcome market flag	Check market metadata; also set `{negRisk: true}` on approvals.

Pricing conventions

Prices are probabilities, range
```
(0, 1)
```
. "YES at 23¢" →
```
price: 0.23
```
.
YES and NO are separate tokens. Buying YES at
```
0.23
```
≈ selling NO at
```
0.77
```
.
Min tick caps precision. Book at
```
0.2300
```
on a 0.01-tick market rejects
```
0.2305
```
.
Implied payoff: BUY YES at 0.23 pays $1 if event resolves YES → ~4.3x.
Bid/ask spread signals liquidity: tight on low-volume means market makers; wide means thin book.

Neg-risk markets

Multi-outcome events where outcomes sum to ≤ 100% (not exactly 100%) use the neg-risk adapter. Typical: elections with multiple candidates. Check

neg_risk: true

on the market metadata.

If neg-risk:

Pass
```
negRisk: true
```
in order calls
Set approvals with
```
{negRisk: true}
```
— the adapter is a separate spender

Size / notional minimums

~$1 USDC minimum notional.

price=0.05, size=10

= $0.50 → rejected. Bump size so

price * size >= 1

Research → trade workflow

GET /agent/polymarket/public-search?q=<topic>

— find events

```
GET /agent/polymarket/events/:eventId
```
— pick a market within the event
Extract
```
token_id
```
for the outcome (YES/NO) you want

GET /agent/polymarket/orderbook/:tokenId

— check liquidity + spread

GET /agent/polymarket/price/mid/:tokenId

— reference price

Note
```
min_tick_size
```
and
```
neg_risk
```
from market metadata
```
GET /agent/polymarket/approvals
```
— confirm approvals, set if missing

POST /agent/polymarket/order

(or

/order/market

) — place

Don't

Don't ask the user for their private key or Privy credentials; signing is server-side via the delegated wallet.
Don't call
```
POST /approvals
```
before every trade — it's gas. Only after
```
GET /approvals
```
shows missing entries.
Don't use market orders for speculative entries where slippage matters — use an aggressive limit across the spread.
Don't confuse market ID (one per event) with token ID (one per outcome). Orders need
```
tokenID
```
.
Don't assume
```
negRisk: false
```
for markets with multiple candidates — check metadata.

MCP note

Same endpoint → tool mapping:

polymarket_get_events

polymarket_get_markets

polymarket_search

polymarket_get_orderbook

polymarket_get_user_portfolio

polymarket_place_order

polymarket_place_market_order

polymarket_cancel_order

polymarket_set_approvals

, etc.

openfin-polymarket

NPX Install

Tags

SKILL.md Content