Tools: Prediction Markets

Prediction market tools interact with Polymarket's CLOB (Central Limit Order Book) on Polygon. Read tools are keyless; write tools require policy approval.

search_prediction_markets

Search Polymarket events/markets via the Polymarket Gamma API (keyless). Returns outcomes and CLOB token_id(s) for trading.

Parameters

Response

{
  "events": [
    {
      "title": "2025 US Presidential Election",
      "markets": [
        {
          "question": "Will the Republican nominee win?",
          "outcomes": [
            { "name": "Yes", "token_id": "1234567890", "price": 0.55 },
            { "name": "No", "token_id": "9876543210", "price": 0.45 }
          ]
        }
      ]
    }
  ],
  "count": 1
}

Response shape is representative; actual fields may vary.

Example

{
  "query": "bitcoin price",
  "limit": 5,
  "include_closed": false
}

Notes

• The token_id returned for each outcome can be passed to get_prediction_orderbook or place_prediction.
• Uses the Polymarket Gamma API (no API key required).

get_prediction_orderbook

Fetch Polymarket CLOB orderbook for a specific outcome token_id (keyless read).

Parameters

Response

{
  "token_id": "1234567890",
  "bids": [
    { "price": 0.54, "size": 1000.0 },
    { "price": 0.53, "size": 2500.0 }
  ],
  "asks": [
    { "price": 0.56, "size": 800.0 },
    { "price": 0.57, "size": 1500.0 }
  ],
  "mid_price": 0.55
}

Response shape is representative; actual fields may vary.

Example

{
  "token_id": "1234567890"
}

Notes

• Use search_prediction_markets first to discover token_id values for outcomes you want to inspect.

get_prediction_positions

Read-only Polymarket positions. Uses the Polymarket Data API (keyless read).

Parameters

Response

{
  "positions": [
    {
      "market": "Will BTC exceed $100k by March 2025?",
      "outcome": "Yes",
      "shares": "50.0",
      "avg_price": 0.65,
      "current_price": 0.72,
      "pnl_usd": 3.5
    }
  ]
}

Response shape is representative; actual fields may vary.

Example

{
  "chain": "polygon"
}

Notes

• Positions are fetched from the Polymarket Data API, which does not require an API key.
• Only Polygon is supported for Polymarket positions.

place_prediction

Place a Polymarket CLOB order. Order is constructed and signed locally; execution is via the Polymarket CLOB API. Requires policy approval.

Parameters

Examples

{
  "chain": "polygon",
  "token_id": "1234567890",
  "side": "buy",
  "order_kind": "limit",
  "price": "0.55",
  "size": "100",
  "time_in_force": "gtc"
}

{
  "chain": "polygon",
  "token_id": "1234567890",
  "side": "buy",
  "order_kind": "market",
  "amount_usdc": "50"
}

Response

{
  "order_id": "0xabcdef...",
  "status": "placed",
  "filled_size": "0",
  "avg_fill_price": null
}

Response shape is representative; actual fields may vary.

Notes

• Uses Polymarket CLOB API (requires HTTPS or localhost).
• polygon-amoy is supported for testing.
• Limit orders require both price and size; market orders require amount_usdc.
• See also: Policy and Approvals.

close_prediction

Cancel an existing Polymarket CLOB order by order_id. Requires policy approval.

Parameters

Response

{
  "order_id": "0xabcdef...",
  "status": "canceled"
}

Response shape is representative; actual fields may vary.

Example

{
  "chain": "polygon",
  "order_id": "0xabcdef123456"
}

Notes

• The order_id is returned from place_prediction when an order is placed.
• See also: Policy and Approvals.