# Polymarket on Onekey

> 14 endpoints for Polymarket (14 stable, 0 beta), 1 to 5 credits each. Category: Finance & markets. One key, one JSON shape.

Base URL: https://api.onekey.dev
Auth: header `x-api-key: <key>`. Call shape: `GET /v1/{platform}/{endpoint}?{params}`.
Every response is `{success, data, metadata, error}`; check `success` first. Cost is in `metadata.credits_charged`. Free when served from cache (0.2 credit for a cached response over 100 KB). Failed and not-found calls are refunded.
Status: stable = verified against the live source; beta = not yet verified, fields may be missing.

Page: https://onekey.dev/platforms/polymarket
Reference (Markdown): https://onekey.dev/docs/api/polymarket.md
All docs: https://onekey.dev/llms.txt

## Canonical fields returned

Unified-schema fields (same names on every platform), with how many of the 14 mapped Polymarket endpoints return each:

- `entity.date` (ISO 8601 date): 9
- `entity.id` (string): 8
- `entity.name` (string): 7
- `entity.slug` (string): 7
- `entity.description` (string): 6
- `market.liquidity` (number): 6
- `market.price` (number): 6
- `market.volume` (number): 6
- `media.thumbnailUrl` (URL): 6
- `market.volume24h` (number): 5
- `engagement.comments` (integer): 4
- `market.openInterest` (number): 4
- `market.ask` (number): 3
- `market.bid` (number): 3
- `market.change24h` (number): 2
- `entity.category` (string): 1
- `event.endDate` (ISO 8601 date): 1
- `event.startDate` (ISO 8601 date): 1
- plus 14 platform-specific fields under `ext.`

## Endpoints

### polymarket.book

CLOB order book for an outcome token.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/polymarket/book?token_id=39223330966352513418907732239455948906399882924787587183466504819170775983376` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `token_id` (string, required): CLOB outcome token id (from a market's clobTokenIds)
- Fields returned: `entity.id`, `entity.date`, `market.price`, `market.bid`, `market.ask`, `ext.conditionId`, `ext.tickSize`, `ext.minOrderSize`, `ext.bestBidSize`, `ext.bestAskSize`, `ext.bids`, `ext.asks`
- Reference: https://onekey.dev/docs/api/polymarket/book.md

### polymarket.event

One prediction event by slug (Gamma).
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/polymarket/event?slug=presidential-election-winner-2028` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `slug` (string, required): Event slug
- Fields returned: `entity.id`, `entity.name`, `entity.slug`, `entity.description`, `media.thumbnailUrl`, `entity.date`, `market.volume`, `market.liquidity`, `market.openInterest`, `market.volume24h`, `engagement.comments`, `ext.active`, `ext.closed`
- Reference: https://onekey.dev/docs/api/polymarket/event.md

### polymarket.events

Top active prediction events by 24h volume (Gamma).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/polymarket/events?limit=5` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `limit` (string, optional, default 10): Rows (1-20)
- Fields returned: `entity.id`, `entity.name`, `entity.slug`, `entity.description`, `media.thumbnailUrl`, `entity.date`, `market.volume`, `market.liquidity`, `market.openInterest`, `market.volume24h`, `engagement.comments`, `ext.active`, `ext.closed`
- Reference: https://onekey.dev/docs/api/polymarket/events.md

### polymarket.last_trade

Last trade price and side for an outcome token.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/polymarket/last_trade?token_id=39223330966352513418907732239455948906399882924787587183466504819170775983376` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `token_id` (string, required): CLOB outcome token id (from a market's clobTokenIds)
- Fields returned: `market.price`, `entity.category`
- Reference: https://onekey.dev/docs/api/polymarket/last_trade.md

### polymarket.market

One prediction market by slug (Gamma).
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/polymarket/market?slug=will-lebron-james-win-the-2028-us-presidential-election` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `slug` (string, required): Market slug
- Fields returned: `entity.id`, `entity.name`, `entity.slug`, `entity.description`, `media.thumbnailUrl`, `entity.date`, `market.volume`, `market.liquidity`, `market.volume24h`, `market.price`, `market.bid`, `market.ask`, `market.change24h`, `ext.outcomes`, `ext.outcomePrices`, `ext.tokenIds`, `ext.conditionId`, `ext.active`, `ext.closed`
- Reference: https://onekey.dev/docs/api/polymarket/market.md

### polymarket.markets

Top active prediction markets by 24h volume (Gamma).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/polymarket/markets?limit=5` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `limit` (string, optional, default 20): Rows (1-100)
- Fields returned: `entity.id`, `entity.name`, `entity.slug`, `entity.description`, `media.thumbnailUrl`, `entity.date`, `market.volume`, `market.liquidity`, `market.volume24h`, `market.price`, `market.bid`, `market.ask`, `market.change24h`, `ext.outcomes`, `ext.outcomePrices`, `ext.tokenIds`, `ext.conditionId`, `ext.active`, `ext.closed`
- Reference: https://onekey.dev/docs/api/polymarket/markets.md

### polymarket.midpoint

CLOB midpoint price for an outcome token.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/polymarket/midpoint?token_id=39223330966352513418907732239455948906399882924787587183466504819170775983376` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `token_id` (string, required): CLOB outcome token id (from a market's clobTokenIds)
- Fields returned: `ext.midpoint`
- Reference: https://onekey.dev/docs/api/polymarket/midpoint.md

### polymarket.price

CLOB best buy price for an outcome token.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/polymarket/price?token_id=39223330966352513418907732239455948906399882924787587183466504819170775983376` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `token_id` (string, required): CLOB outcome token id (from a market's clobTokenIds)
- Fields returned: `market.price`
- Reference: https://onekey.dev/docs/api/polymarket/price.md

### polymarket.price_history

Price history for an outcome token (interval + fidelity in minutes).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/polymarket/price_history?token_id=39223330966352513418907732239455948906399882924787587183466504819170775983376` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `token_id` (string, required): CLOB outcome token id (from a market's clobTokenIds)
  - `interval` (string, optional, default 1w): Range
  - `fidelity` (string, optional, default 60): Minutes per point
- Fields returned: `entity.date`, `market.price`
- Reference: https://onekey.dev/docs/api/polymarket/price_history.md

### polymarket.research

Research a topic across Polymarket: matching prediction-market events with volume, liquidity and dates.
- Price: 1 credit per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/polymarket/research?query=bitcoin` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `query` (string, required): Research topic, free text (e.g. bitcoin halving)
- Fields returned: `entity.id`, `entity.name`, `entity.slug`, `entity.description`, `market.volume`, `market.liquidity`, `market.openInterest`, `event.endDate`, `event.startDate`, `media.thumbnailUrl`, `engagement.comments`
- Reference: https://onekey.dev/docs/api/polymarket/research.md

### polymarket.search

Search Polymarket events.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/polymarket/search?q=election&limit=5` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search text
  - `limit` (string, optional, default 10): Rows per type (1-20)
- Fields returned: `entity.id`, `entity.name`, `entity.slug`, `entity.description`, `media.thumbnailUrl`, `entity.date`, `market.volume`, `market.liquidity`, `market.openInterest`, `market.volume24h`, `engagement.comments`, `ext.active`, `ext.closed`
- Reference: https://onekey.dev/docs/api/polymarket/search.md

### polymarket.server_time

Polymarket CLOB server time.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/polymarket/server_time` with header `x-api-key: YOUR_API_KEY`
- Parameters: none
- Fields returned: `entity.date`
- Reference: https://onekey.dev/docs/api/polymarket/server_time.md

### polymarket.spread

CLOB bid/ask spread for an outcome token.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/polymarket/spread?token_id=39223330966352513418907732239455948906399882924787587183466504819170775983376` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `token_id` (string, required): CLOB outcome token id (from a market's clobTokenIds)
- Fields returned: `ext.spread`
- Reference: https://onekey.dev/docs/api/polymarket/spread.md

### polymarket.tags

Polymarket topic tags.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/polymarket/tags?limit=5` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `limit` (string, optional, default 50): Rows (1-100)
- Fields returned: `entity.id`, `entity.name`, `entity.slug`, `entity.date`
- Reference: https://onekey.dev/docs/api/polymarket/tags.md

## Sample request

```bash
curl "https://api.onekey.dev/v1/polymarket/book?token_id=39223330966352513418907732239455948906399882924787587183466504819170775983376" \
  -H "x-api-key: YOUR_API_KEY"
```