Trades (Global)

Every Polymarket CLOB v2 fill, joined to market metadata. Filter by wallet, market, token, builder, time range, or size.

Every v2 OrderFilled event as it lands on-chain, joined to the 860K-market metadata layer so every hex ID comes back with question, slug, event_title, image, and outcome inline. No cursor games — simple limit + offset.

Data appears within seconds of confirmation.

Request

GET /clobv2/trades

Authentication

Paid tier required. Pass your API key via x-api-key, Authorization: Bearer, or ?key=:

curl "https://api.polynode.dev/clobv2/trades?limit=10" \
  -H "x-api-key: pn_live_..."

Free-tier keys receive 402 Payment Required.

Query parameters

Parameter	Type	Required	Description
wallet	string	No	Filter by wallet address (0x + 40 hex). Matches both maker and taker sides.
builder	string	No	Filter by builder (0x + 64 hex — builders are 32-byte values, not addresses). Pull real values from /clobv2/builders.
token_id	string	No	Filter by outcome token ID (uint256 as decimal string). Matches either side.
condition_id	string	No	Filter by market condition_id (0x + 64 hex).
start / start_time	integer	No	Unix seconds — only return fills at or after this time.
end / end_time	integer	No	Unix seconds — only return fills at or before this time.
min_usd / min_total	number	No	Minimum maker_usdc size in dollars.
limit	integer	No	Results per page (1-500, default 100).
offset	integer	No	Skip this many results (0-10000000, default 0). Use with limit for pagination.
order	string	No	desc (newest first, default) or asc (oldest first).

All parameters are optional. Calling the endpoint with no filters returns the 100 newest fills.

Parameter validation

• wallet: regex ^0x[a-f0-9]{40}$ (case-insensitive, normalized to lowercase).
• condition_id, builder: regex ^0x[a-f0-9]{64}$.
• token_id: 1-78 digits, ^[0-9]+$.
• Timestamps: i64, must be ≥ 0.
• limit: 1-500. offset: 0-10000000.

Anything that fails a validator returns 400 Bad Request with {"error": "..."} before the backend is touched.

Response

{
  "count": 1,
  "source": "onchain-v2",
  "pagination": {
    "limit": 1,
    "offset": 0,
    "has_more": true
  },
  "trades": [
    {
      "ts": "2026-04-20T06:12:00+00:00",
      "ts_unix": 1776665520,
      "tx_hash": "0x7a78b781700f53136ca7a8ca62d31f7a11999e0c65a4d0a2c160cfc3315b170f",
      "order_hash": "0x8d102e0044dd5651c28b48068e8bb29c8f7ae33b1c58b2f48a36a248ff966064",

      "maker": "0xd663f0f56e5c80d4716d46c776fabb4ec4c66abc",
      "taker": "0xf86178a8e4b9e7c6a00200bf1ee5679383de462f",
      "side": "maker",

      "token_id": "32530407925029104312458780580530294728135746429755854137976885977399961033740",
      "amount_usd": "1.3440000000000000",
      "shares": "5.6000000000000000",
      "price": "0.24000000000000000000",
      "fee_usd": "0.000000000000000000000000",

      "maker_token_id": "0",
      "taker_token_id": "32530407925029104312458780580530294728135746429755854137976885977399961033740",
      "maker_usdc": "1.3440000000000000",
      "taker_usdc": "5.6000000000000000",
      "fee_usdc": "0.000000000000000000000000",

      "builder": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "question": "Solana Up or Down - April 20, 2:10AM-2:15AM ET",
      "slug": "sol-updown-5m-1776665400",
      "event_title": "Solana Up or Down - April 20, 2:10AM-2:15AM ET",
      "image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/SOL+fullsize.png",
      "condition_id": "0x1ee2fb3f919aa7c307565db03241926252666691aca6d7185af4654df603efdc",
      "outcome": "Up"
    }
  ]
}

Response fields — derived convenience (most users start here)

One row per fill. These fields collapse the two-sided fill into a familiar “buy/sell” shape:

Field	Type	Description
token_id	string	The outcome token ID traded on this fill (the non-USDC side). Decimal string. null only on pair-mint fills (both sides outcome tokens).
amount_usd	string (numeric)	The USDC notional that changed hands. null on pair-mint fills.
shares	string (numeric)	The outcome-token quantity that changed hands. null on pair-mint fills.
price	string (numeric)	amount_usd / shares — the implied price of the outcome token, 0.0–1.0. null on pair-mint fills.
fee_usd	string (numeric)	Fee in USDC. Alias of fee_usdc.
side	string | null	Only present when you pass wallet= — "maker" or "taker", describing the queried wallet’s role in this fill. Absent otherwise.

Response fields — raw two-sided (full precision, for advanced users)

Same fill, served raw so you can see exactly what’s on-chain:

Field	Type	Description
maker / taker	string	20-byte addresses.
maker_token_id / taker_token_id	string	uint256 token IDs as decimal strings. "0" means the USDC (collateral) side.
maker_usdc / taker_usdc	string (numeric)	Both sides’ amounts, already scaled /1e6. The name usdc is from the shared decimal convention — on the outcome-token side this is the share count (same 6-decimal scaling).
fee_usdc	string (numeric)	Fee in USDC.

Response fields — market metadata (all enriched via the 860K-market layer)

Field	Type	Description
question	string | null	Market question (e.g. "Will Donald Trump win the 2024 US Presidential Election?"). null only if metadata is briefly unavailable.
slug	string | null	Polymarket URL slug.
event_title	string | null	Parent event title (neg-risk markets share an event).
image	string | null	CDN URL of the market icon.
outcome	string	Outcome label (e.g. "Yes", "No", "Up", "Matt Fitzpatrick").
condition_id	string	32-byte condition_id of the market for the outcome-token side.
builder	string	32-byte builder tag. Zero (0x000…000) means no builder attribution.

Response fields — envelope

Field	Type	Description
count	integer	Number of trades in this page.
source	string	Always "onchain-v2".
pagination.limit	integer	Limit in effect.
pagination.offset	integer	Offset used.
pagination.has_more	boolean	true if more results exist past this page.
trades[].ts	string	ISO-8601 UTC timestamp.
trades[].ts_unix	integer	Unix-seconds timestamp.
trades[].tx_hash	string	Transaction hash on Polygon.
trades[].order_hash	string	Unique order hash (same order can appear across multiple fills on partial fills).

Rate-limit headers

Every response includes:

x-ratelimit-limit: 100000
x-ratelimit-remaining: 99997
x-ratelimit-reset: 1776665478

Examples

cURL

# Latest 5 fills globally
curl "https://api.polynode.dev/clobv2/trades?limit=5" \
  -H "x-api-key: pn_live_..."

# A specific wallet's last 100 fills
curl "https://api.polynode.dev/clobv2/trades?wallet=0xd663f0f56e5c80d4716d46c776fabb4ec4c66abc&limit=100" \
  -H "x-api-key: pn_live_..."

# Only fills ≥ $10 in a 24h window
curl "https://api.polynode.dev/clobv2/trades?start=1776578000&end=1776664400&min_usd=10" \
  -H "x-api-key: pn_live_..."

# All fills for one market
curl "https://api.polynode.dev/clobv2/trades?condition_id=0xacb78c48e74576d39862560c32c91db35d642f31b24fdf56a99aa0f57ed062b4" \
  -H "x-api-key: pn_live_..."

# Fills attributed to one builder
curl "https://api.polynode.dev/clobv2/trades?builder=0x950f0672f032daa0ae4e0f94920cf6fa567cc597685622a609d97c872190d6d4" \
  -H "x-api-key: pn_live_..."

# Pagination: first page, then next page
curl "https://api.polynode.dev/clobv2/trades?limit=100&offset=0"   -H "x-api-key: pn_live_..."
curl "https://api.polynode.dev/clobv2/trades?limit=100&offset=100" -H "x-api-key: pn_live_..."

Error responses

Status	Body	When
400	{"error": "invalid wallet address ..."}	Parameter validation failed (bad hex, bad enum, out-of-range int).
401	{"error": "missing API key ..."} or {"error": "invalid or revoked API key"}	No key, malformed key, or revoked.
402	{"error": "paid plan required ...", "tier": "free", "upgrade_url": "https://polynode.dev"}	Valid key but tier = "free".
429	{"error": "rate limit exceeded", "reset_at": <unix>}	Per-key sliding-window rate limit hit.
5xx	{"error": "temporary_data_provider_error", "detail": "..."}	Temporary data provider issue. Retry with backoff.

Notes

• maker_token_id = "0" (or taker_token_id = "0") means that side of the fill is USDC collateral. The non-zero side is the outcome token.
• Numeric fields come back as strings (e.g. "2.9500000000000000") to avoid float precision loss. Parse with Decimal/BigNumber before math.
• builder = "0x000...000" means the order did not carry a builder tag.
• question, slug, image, event_title, outcome may be null briefly on newly seen markets. Market metadata usually appears within 30 seconds.
• Pagination is offset-based. If new fills arrive between pages, the same fill may be seen twice or skipped — for historical dumps, filter by end=<snapshot_ts> to get a stable window.