openfin-polymarket

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polymarket

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

通过OpenFinance实现Polymarket端到端操作手册——研究、定价、下单、授权及用户数据。

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.

用户已完成
```
openfin-setup
```
（API密钥 + EVM钱包委托）。
已完成授权——调用
```
GET /agent/polymarket/approvals
```
检查授权状态，调用
```
POST /agent/polymarket/approvals
```
设置缺失的授权。仅需一次性支付Gas费用。
钱包在Polygon网络中持有MATIC用于支付Gas费用，以及USDC.e（非原生USDC）用于交易。

Research endpoints (public, no auth)

研究类接口（公开，无需授权）

Events (Gamma API)

事件（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.

事件用于归类相关预测市场——例如，一个“2024年美国大选”事件包含多个独立的候选人市场。

GET /agent/polymarket/events
—— 浏览全球最大预测市场中的事件。返回包含元数据、结果、交易量及当前状态的列表。可选查询参数：
```
limit
```
、
```
offset
```
、
```
active
```
（进行中）、
```
closed
```
（已结束）、
```
archived
```
（历史）、
```
order
```
（例如
```
desc
```
）、
```
ascending
```
、
```
slug
```
、
```
tag_id
```
。适用于体育投注赔率（IPL、FIFA、NBA、NFL、F1、UFC、板球、足球）、政治预测（选举、政策、政府动态）、加密货币/金融预测、娱乐或任何热门现实事件。
GET /agent/polymarket/events/:eventId
—— 通过ID查询单个事件。返回元数据、市场信息、结果、交易量、流动性及当前概率。
GET /agent/polymarket/events/slug/:slug
—— 通过URL别名查询，功能与上述接口相同。
GET /agent/polymarket/events/:eventId/volume
—— 事件的实时交易量。用于衡量体育赛事、选举或热门话题的关注度/资金流向。

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

GET /agent/polymarket/markets
—— 列出预测市场，包含当前价格（隐含概率）、交易量、流动性及结果详情。用于浏览体育、政治、加密货币、娱乐及热门事件相关市场。可选筛选条件：
```
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
—— 通过数字ID查询单个市场。返回价格、订单簿深度、交易量、流动性及结果详情。
GET /agent/polymarket/markets/slug/:slug
—— 通过URL别名查询，功能与上述接口相同。
GET /agent/polymarket/markets/cid/:conditionId
—— 通过链上CTF条件ID（bytes32十六进制）查询，功能与上述接口相同。当用户持仓中已有条件ID时，此接口非常实用。

所有市场响应包含以下字段：

```
condition_id
```
—— 链上CTF条件标识符
```
tokens
```
—— YES/NO结果代币及其
```
token_id
```
```
min_tick_size
```
—— 下单时所需的正确
```
tickSize
```
参数
```
neg_risk
```
—— 若为true，下单和授权时需传入
```
negRisk: true
```

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.

GET /agent/polymarket/public-search?q=<query>
—— 通过关键词搜索所有事件和市场。返回带有相关性评分的匹配条目。当用户提及特定主题（如“IPL冠军”“FIFA世界杯”“美国大选”“比特币价格”“特朗普”“莫迪”“欧冠联赛”）或任何热门事件时，可使用此接口查找现实结果的投注赔率和概率。

Pricing (CLOB API)

定价（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.

GET /agent/polymarket/orderbook/:tokenId
—— 特定结果代币的当前订单簿（买单和卖单）。返回不同价格水平的买卖订单数组，包含订单规模和深度。用于下单前查看市场流动性及可用价格。
POST /agent/polymarket/orderbooks
请求体
```
{tokenIds: [...]}
```
—— 功能与上述接口相同，但支持单次请求查询多个代币。返回tokenId → 订单簿的映射。比多次单独调用更高效。
GET /agent/polymarket/price/mid/:tokenId
—— 代币的中间价，代表市场隐含概率
```
(0, 1)
```
。用于查看“赔率是多少”或“结果发生的概率是多少”。
GET /agent/polymarket/price/:tokenId?side=BUY
—— 代币的最优买价或卖价。必须传入
```
side
```
查询参数：
```
BUY
```
或
```
SELL
```
。
GET /agent/polymarket/prices
—— 所有活跃结果代币的中间价。返回代币ID → 概率的映射。用于一次性扫描所有活跃市场的赔率。
GET /agent/polymarket/spread/:tokenId
—— 代币的买卖价差（最优卖价 − 最优买价）。价差小代表流动性好；价差大代表订单簿深度不足。

GET /agent/polymarket/last-trade-price/:tokenId
—— 代币最近一次成交的价格。

GET /agent/polymarket/trades/:marketSlug
(
```
?limit=50&offset=0
```
) —— 市场的近期交易记录（通过别名查询）。返回包含价格、规模、时间戳及方向（买/卖）的交易信息。用于分析投注活动及赔率变化趋势。

Market data (Data API)

市场数据（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).

GET /agent/polymarket/market/:conditionId/open-interest
—— 市场的总锁定价值。返回每个结果的投入资金及整体市场规模。
GET /agent/polymarket/market/:marketId/volume
—— 市场的历史及当前交易量统计数据。
GET /agent/polymarket/market/:marketId/liquidity
—— 市场的当前及历史流动性深度。
GET /agent/polymarket/market/:marketId/trades
(
```
?limit=50
```
) —— 详细的交易历史记录，包含元数据（比CLOB的
```
/trades
```
接口返回的信息更全面）。

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.

:address

= 用户的Polygon EVM地址（其Privy EVM钱包地址）。

GET /agent/polymarket/user/:address/positions
—— 用户持有的活跃持仓。返回结果代币、数量、入场价、当前价值及每个持仓的未实现盈亏。
GET /agent/polymarket/user/:address/trades
(
```
?limit=50&offset=0
```
) —— 用户的交易历史，包含价格、规模、时间戳、市场及结果。用于分析交易模式和表现。
GET /agent/polymarket/user/:address/portfolio
—— 完整的投资组合概览：总价值、所有持仓、已实现/未实现盈亏、胜率、绩效指标。
GET /agent/polymarket/user/:address/pnl
—— 独立的盈亏统计：已实现盈亏、未实现盈亏、总盈亏、历史表现。

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.

所有接口均需携带

x-api-key: open_…

签名采用EIP-712标准，调用者的Privy托管Polygon钱包完成签名；用户首次调用时，后端会派生并缓存Polymarket L2 API凭证。

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.

POST /agent/polymarket/order
—— 在Polymarket CLOB上下限价单（GTC或GTD）。请求体字段：

json

{
  "tokenID": "...",          // CLOB结果资产ID（非市场/条件ID）
  "price": 0.42,             // 概率值0.0–1.0
  "size": 10,                // 条件代币单位
  "side": "BUY",             // "BUY" | "SELL"
  "orderType": "GTC",        // 默认"GTC"；"GTD"需指定到期时间
  "tickSize": "0.01",        // 默认"0.01"；部分市场需要"0.001" / "0.0001"
  "negRisk": false,          // 多结果负风险市场需设为true
  "postOnly": false,         // 仅接受挂单（若订单可立即成交则拒绝）
  "expiration": 1735689600   // Unix时间戳，orderType为"GTD"时必填
}

返回订单ID及下单状态。适用于用户指令如“以0.42的价格买入10份”或“在X价位挂买单”。

POST /agent/polymarket/order/market
—— 下市价单（FOK或FAK）。买入时，

amount

为要花费的USDC金额；卖出时，

amount

为要卖出的份数。

json

{
  "tokenID": "...",
  "amount": 10,              // 买入：花费的USDC金额 · 卖出：卖出的份数
  "side": "BUY",
  "price": 0.42,             // 可选限价；省略则为纯市价单
  "orderType": "FOK",        // 默认"FOK"（全部成交否则取消） | "FAK"（能成交多少就成交多少，剩余取消）
  "tickSize": "0.01",
  "negRisk": false
}

适用于“立即买入”类指令。FOK模式下若无法完全成交则订单失败；FAK模式下会成交可成交部分，剩余订单取消。

POST /agent/polymarket/orders
—— 批量下多个限价单。每个订单会单独签名后一起提交。请求体：

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

。适用于阶梯报价。

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.

GET /agent/polymarket/order/:orderId
—— 通过ID查询单个订单。返回完整订单记录。
GET /agent/polymarket/orders
(
```
?id=&market=&asset_id=
```
) —— 查询已授权用户的所有未成交订单。可选筛选条件：
```
id
```
、
```
market
```
（condition_id）或
```
asset_id
```
（token_id）。
GET /agent/polymarket/order/:orderId/scoring
—— 检查订单当前是否符合Polymarket流动性奖励条件。返回奖励状态。

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).

DELETE /agent/polymarket/order/:orderId
—— 通过订单ID取消单个未成交订单。
DELETE /agent/polymarket/orders
请求体
```
{orderHashes: [...]}
```
—— 通过链上订单哈希批量取消多个订单。
DELETE /agent/polymarket/orders/all
—— 取消已授权用户的所有未成交订单（全部清空）。
DELETE /agent/polymarket/orders/market
请求体
```
{market, asset_id}
```
—— 取消指定市场（condition_id）或资产（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.

交易前，必须授权Polymarket合约使用USDC.e + CTF。后端会处理USDC.e（非pUSD/原生USDC）以及V1交易所和条件代币的授权方。

GET /agent/polymarket/approvals
(
```
?negRisk=true
```
) —— 查询Polymarket交易所合约的当前链上授权额度。交易前调用此接口确认钱包已授权USDC.e + CTF的转移权限。返回每个（代币，授权方）对的记录，包含
```
approved: boolean
```
。传入
```
negRisk=true
```
可同时查询NegRiskAdapter/NegRiskExchange的授权——交易多结果市场时必填。
POST /agent/polymarket/approvals
请求体
```
{negRisk?: boolean}
```
—— 提交授权交易以补充缺失的额度。接口具备幂等性——仅授权缺失的部分。返回每个条目的状态及新提交授权的交易哈希。用户钱包需在Polygon网络支付MATIC Gas费用。

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.

若后端环境变量中设置了

POLYMARKET_BUILDER_CODE

，订单会自动标记以获取费用归因。构建者注册需通过Polymarket的链下流程——仅在完成代码注册后才会产生费用流。在此之前，标记操作不会产生任何影响（但也无副作用）。

POST /agent/polymarket/builder/api-key
—— 创建与调用者钱包绑定的构建者API密钥。返回
```
key
```
/
```
secret
```
/
```
passphrase
```
，用于通过构建者代码获取订单归因费用。
GET /agent/polymarket/builder/api-keys
—— 列出调用者的所有构建者API密钥。
DELETE /agent/polymarket/builder/api-key
—— 撤销调用者的构建者API密钥。

GET /agent/polymarket/builder/trades
(

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

) —— 列出归因于后端配置的构建者代码的交易。需在服务器端设置

POLYMARKET_BUILDER_CODE

。

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

路由/类型	使用场景
`/order` (GTC)	“以Y价格买入X份”——限价挂单直至成交或取消
`/order` (GTD)	与GTC相同，但会在 `expiration` 时间自动取消
`/order/market` (FOK)	“立即买入”——全部成交否则取消
`/order/market` (FAK)	尽最大努力成交，剩余部分取消
`/orders` 批量	阶梯报价——一次性提交多个价格水平的订单

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.

参数	说明	注意事项
`tokenID`	CLOB结果资产ID	与市场/条件ID不同。每个YES/NO结果对应一个tokenID。需从市场的 `tokens` 数组中获取。
`price`	概率值（十进制 `0.0–1.0` ）	`0.42` 代表42美分。不可传入 `42` 或 `"42%"` 。
`size` （限价单）	条件代币单位	花费的USDC金额≈ `size * price` 。
`amount` （市价单）	随交易方向变化	买入：要花费的USDC金额。卖出：要卖出的份数。
`side`	`"BUY"` 或 `"SELL"`	区分大小写。
`tickSize`	最小价格变动单位	默认 `0.01` 。部分市场需要 `0.001` 或 `0.0001` 。传入错误值会返回400错误。
`negRisk`	多结果市场标记	需查看市场元数据；授权时也需传入 `{negRisk: true}` 。

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.

价格为概率值，范围
```
(0, 1)
```
。“YES价格23美分”对应
```
price: 0.23
```
。
YES和NO是独立代币。以0.23买入YES≈以0.77卖出NO。
最小价格变动单位限制精度。在最小变动单位为0.01的市场中，订单簿价格为
```
0.2300
```
时，
```
0.2305
```
的订单会被拒绝。
隐含收益：以0.23买入YES，若事件结果为YES则支付1美元→收益约4.3倍。
买卖价差反映流动性：低交易量下价差小代表做市商参与；价差大代表订单簿深度不足。

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

多结果事件中，结果概率总和≤100%（非精确100%）的市场使用负风险适配器。典型场景：有多候选人的选举。需查看市场元数据中的

neg_risk: true

标记。

若为负风险市场：

下单时需传入
```
negRisk: true
```
授权时需传入
```
{negRisk: true}
```
——适配器是独立的授权方

Size / notional minimums

规模/名义金额最小值

~$1 USDC minimum notional.

price=0.05, size=10

= $0.50 → rejected. Bump size so

price * size >= 1

名义金额最小值约为1 USDC。

price=0.05, size=10

=0.5美元→订单会被拒绝。需调整规模使

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

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

—— 查找事件

```
GET /agent/polymarket/events/:eventId
```
—— 选择事件中的某个市场
提取目标结果（YES/NO）的
```
token_id
```

GET /agent/polymarket/orderbook/:tokenId

—— 检查流动性+价差

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

—— 获取参考价格

记录市场元数据中的
```
min_tick_size
```
和
```
neg_risk
```
```
GET /agent/polymarket/approvals
```
—— 确认授权状态，补充缺失的授权

POST /agent/polymarket/order

（或

/order/market

）—— 下单

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.

不要向用户索要私钥或Privy凭证；签名通过后端的委托钱包完成。
不要在每次交易前调用
```
POST /approvals
```
——会产生Gas费用。仅在
```
GET /approvals
```
显示授权缺失时调用。
若滑点对投机入场很重要，不要使用市价单——使用跨越价差的激进限价单。
不要混淆市场ID（每个事件对应一个）和代币ID（每个结果对应一个）。下单需要
```
tokenID
```
。
不要默认多候选人市场的
```
negRisk: false
```
——需查看元数据。

MCP note

MCP说明

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.

接口→工具映射对应关系：

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

等。