The APIVex Polymarket API lets you discover public markets and retrieve outcome prices, order books, price history, and activity as JSON. This tutorial connects a market-list result to the order book for one of its outcomes.
APIVex is a third-party data service. The routes here read public information and do not place or cancel orders. You need an APIVex key from the dashboard.
Keep the three market identifiers separate
A market slug, outcome token ID, and condition ID are not interchangeable:
| Identifier | Purpose |
|---|---|
slug | Retrieve a market by its human-readable URL name |
Outcome token_id | Retrieve that outcome’s order book or price history |
condition_id | Identify the market for applicable activity routes |
In the captured market-list response, data was an array of markets, each with an outcomes array. Each outcome contained name, price, and token_id. Keep token IDs as strings: they can be much larger than JavaScript’s safe integer range.
Find active markets
Use the APIVex base URL https://api.apivex.com/polymarket and the x-apivex-key header:
curl --get 'https://api.apivex.com/polymarket/api/markets/list' \
--header "x-apivex-key: $APIVEX_API_KEY" \
--data-urlencode 'active=true' \
--data-urlencode 'closed=false' \
--data-urlencode 'limit=2'You can narrow discovery using the documented tag, volume, liquidity, and end-date filters. The list uses limit and offset, rather than a cursor. When collecting several pages, preserve your filters and deduplicate by market ID: a changing sort order can move a market between pages.
Do not assume an event has only one market, or that an event slug is always the market slug. For a specific question, select the actual market record and retain its identifiers.
Request an outcome’s order book
The following Node.js example selects the first returned market and its first outcome. In a user-facing application, let the reader choose the market and outcome explicitly. Save it as polymarket-book.mjs and run it with Node.js 20 or newer after setting APIVEX_API_KEY.
const key = process.env.APIVEX_API_KEY;
if (!key) throw new Error('Set APIVEX_API_KEY first');
const base = 'https://api.apivex.com/polymarket';
// Demonstration pacing; use the request rate allowed by your plan.
const pause = () => new Promise(resolve => setTimeout(resolve, 2500));
async function get(path, params) {
const url = new URL(base + path);
url.search = new URLSearchParams(params).toString();
const response = await fetch(url, {
headers: {'x-apivex-key': key},
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error('HTTP ' + response.status);
const body = await response.json();
if (body.status !== true) throw new Error(body.message || 'API request failed');
return body.data;
}
const markets = await get('/api/markets/list', {active: true, closed: false, limit: 2});
const market = markets[0];
const outcome = market?.outcomes?.[0];
if (!outcome?.token_id) throw new Error('No outcome token in this market page');
console.log({market: market.slug, outcome: outcome.name});
await pause();
const book = await get('/api/prices/book', {token_id: outcome.token_id, depth: 5});
console.log(JSON.stringify(book, null, 2));The order-book response contains bids and asks, with price and size on each level. It also includes fields such as tick_size, min_order_size, token_id, and timestamp. Store the selected outcome name alongside the token ID so a chart clearly states which outcome it represents.
Market-list prices, last-trade prices, and order-book levels are different observations. They may come from different snapshots; do not assume they are equal or replace a missing value with zero. Display a retrieval time and distinguish a stale snapshot from a successful refresh.
Extend the workflow to price history
Pass the same outcome token ID to /api/prices/history. For a rolling window, use interval, such as 1d or 1w; fidelity controls sampling resolution in minutes.
For an explicit range, use start_ts and end_ts in Unix seconds. The documented behavior gives start_ts precedence over interval, so choose one approach rather than sending conflicting range settings. Keep your chart’s timestamps and timezone handling consistent.
This is a price-history route for one outcome. It is not a way to obtain every outcome’s history with a market slug in a single request.
Make a small, reliable market monitor
Discover and save the market and outcome identifiers first. Refresh only the records your application needs, using a schedule appropriate to your APIVex plan. Preserve the last successful response if a later request fails, but label it with its original retrieval time.
The example stops on an HTTP error or an unsuccessful API response. A production worker should distinguish an invalid identifier from a temporary failure and use bounded retries with backoff, rather than an unlimited retry loop.
Try the workflow in the Polymarket documentation. If you also ingest Kalshi data, the Kalshi guide explains its event, market, and series tickers; keep the two platforms’ identifiers in separate fields.
