Skip to main content
Glama
polymarket-info

polymarket-info

by wtfsayo
README.md
# polymarket-info

Cursor / Agent Plugin for **Polymarket international** public market data:

- **Gamma** (`gamma-api.polymarket.com`) — events, markets, search, tags, series, sports
- **CLOB** (`clob.polymarket.com`) — books, mids, spreads, prices, batch quotes, tick/fee/neg-risk meta
- **Data API** (`data-api.polymarket.com`) — positions, activity, trades, holders, OI, live volume

Read-only. No API keys. No order placement / CLOB auth / Relayer / Bridge / WebSockets.

Docs: https://docs.polymarket.com/  
Marketing (no API catalog): https://institutional.polymarket.com/

**Not** Polymarket US (`docs.polymarket.us` / `*.polymarketexchange.com`).

## Domain types

| Type | Meaning |
| --- | --- |
| `Market` | Gamma market (question, slug, outcomes, `clobTokenIds`, volume, …) |
| `Event` | Gamma event with nested markets |
| `Tag` / `Series` / `Team` / `SportsMetadata` | Gamma discovery metadata |
| `PublicProfile` | Gamma public profile by wallet |
| `OrderBook` | CLOB L2 bids/asks for a `token_id` (prices 0–1 strings) |
| `MidPrice` / `Spread` / `LastTrade` / `Price` | CLOB quote helpers (single + batch) |
| `PriceHistory` | historical mid series |
| `ClobMarket` | CLOB-level market params by `condition_id` |
| `FeeRate` / `TickSize` / `NegRisk` | CLOB market meta |
| `Position` / `ClosedPosition` | Data API open / closed holdings |
| `Activity` / `Trade` | Data API wallet activity & fills |
| `Holder` / `OpenInterest` / `LiveVolume` / `Value` | Data API analytics |
| `LeaderboardEntry` | Trader leaderboard row |
| `GeoBlock` | Trading eligibility of this machine's IP: `{blocked, country}` (IP and region are dropped) |

Model: event → markets → YES/NO outcome tokens. Use `token_id` from Gamma `clobTokenIds` on CLOB. Prefer Gamma for discovery; CLOB for live book; Data API for wallet/market analytics (`user` = 0x address in query).

## Install (Cursor IDE)

Copy to `~/.cursor/plugins/local/polymarket-info` (real directory), Reload Window.

## Install (Claude Code)

Clone this repo, then start Claude Code with `claude --plugin-dir /path/to/polymarket-plugin`. `.claude-plugin/plugin.json` loads the skill and starts the MCP server with `node ${CLAUDE_PLUGIN_ROOT}/server/index.mjs`. The server has no dependencies, so it needs only Node on `PATH` and no `npm install`.

## Output

- Results are compact JSON text with no `structuredContent`.
- Lists return `{total, returned, offset, truncated, items}` with `next_offset` (or `next_cursor` for keyset/CLOB pages) when more remain. Default `limit` is 50 (10 for `list_events`, 20 for `list_holders`) and every response is capped at 40,000 characters.
- `list_markets`, `list_events`, `search`, `get_event` and `get_series` default to `response_format: "concise"` (about 12 market fields; events keep their top 5 markets). Pass `"detailed"` for every upstream field. `get_market` defaults to detailed.
- `list_markets` and `list_events` default to open markets ending after now, sorted by 24h volume.
- Upstream and validation errors come back as tool results with `isError: true`, the upstream reason, and a hint.
- Results with market copy or user profiles start with a one-line note that those fields are third-party text.

Env: `POLYMARKET_TIMEOUT_MS` (default 15000) bounds every upstream call. `POLYMARKET_GAMMA_URL`, `POLYMARKET_CLOB_URL`, `POLYMARKET_DATA_URL` and `POLYMARKET_GEOBLOCK_URL` override the hosts (the smoke test points them at a local mock).

## Test

`npm test` runs `test/smoke.mjs`; see `PROVE.md` for what it checks.

## MCP tools (43)

### Gamma

| Tool | Host |
| --- | --- |
| `list_markets` | `/markets/keyset` |
| `list_events` | `/events/keyset` |
| `search` | `/public-search` |
| `get_market` | `/markets/{id}` or `/markets/slug/{slug}` |
| `get_event` | `/events/{id}` or `/events/slug/{slug}` |
| `list_tags` / `get_tag` | `/tags`, `/tags/{id\|slug}` |
| `list_series` / `get_series` | `/series`, `/series/{id}` |
| `list_sports` / `get_sports_market_types` | `/sports`, `/sports/market-types` |
| `list_teams` | `/teams` |
| `get_public_profile` | `/public-profile?address=` |

### CLOB

| Tool | Host |
| --- | --- |
| `get_book` / `get_books` | `GET /book`, `POST /books` |
| `get_midpoint` / `get_midpoints` | `GET /midpoint`, `POST /midpoints` |
| `get_price` / `get_prices` | `GET /price`, `POST /prices` |
| `get_spread` / `get_spreads` | `GET /spread`, `POST /spreads` |
| `get_last_trade_price` / `get_last_trades_prices` | `GET /last-trade-price`, `POST /last-trades-prices` |
| `get_prices_history` | `/prices-history` |
| `get_time` | `/time` |
| `get_fee_rate` / `get_tick_size` / `get_neg_risk` | `/fee-rate`, `/tick-size`, `/neg-risk` |
| `get_clob_market` | `/clob-markets/{condition_id}` |
| `get_market_by_token` | `/markets-by-token/{token_id}` |
| `list_simplified_markets` / `list_sampling_markets` | `/simplified-markets`, `/sampling-markets` |

### Data API

| Tool | Host |
| --- | --- |
| `list_positions` | `/positions?user=` |
| `list_closed_positions` | `/closed-positions?user=` |
| `list_activity` | `/activity?user=` |
| `list_trades` | `/trades?user=` and/or `market=` |
| `get_value` | `/value?user=` |
| `list_holders` | `/holders?market=` (conditionId) |
| `get_oi` | `/oi` |
| `get_live_volume` | `/live-volume?id=` (event id) |
| `get_traded` | `/traded?user=` |
| `list_leaderboard` | `/v1/leaderboard` |

### Misc

| Tool | Host |
| --- | --- |
| `get_geoblock` | `polymarket.com/api/geoblock` |

## Licensing note

Capital-markets redistribution of Polymarket data may require Polymarket + ICE licensing. See institutional site / `data-licensing@polymarket.com`. This plugin is for personal agent tooling, not a data-feed substitute.

## License

MIT

## Repository

https://github.com/wtfsayo/polymarket-plugin