Retrieve recent Polymarket prediction market trades decoded from on-chain OrderFilled events on Polygon.
What it does
This endpoint returns recent trades for a specific Polymarket prediction market. Trades are decoded from on-chain OrderFilled events on Polygon and joined with market metadata. You can query by market_id and optionally filter by date range, with pagination and sorting support.
The endpoint is part of Nansen's broader Prediction Markets API suite, which covers Polymarket analytics including OHLCV candles, orderbooks, top holders, PnL leaderboards, and event/market screeners. The trades-by-market endpoint specifically answers questions like: what are the most recent trades in a market, who is buying and selling at what prices, and what is the trade size distribution. Each trade record includes timestamp, buyer/seller addresses, taker action (buy/sell), outcome side (Yes/No), size, price, USDC value, and transaction hash.
Pricing is $0.01 per call via the x402 protocol, or 10 credits (free tier) / 1 credit (pro tier) when using a Nansen API key. The endpoint accepts POST requests with a JSON body. Rate limits are enforced per-second and per-minute, reported via response headers.
Capabilities
Use cases
- —Retrieve recent buy/sell trades for a specific Polymarket prediction market
- —Analyze trade size distribution and price levels for a prediction market outcome
- —Monitor who is buying and selling in a Polymarket market in real time
- —Build trading dashboards showing Polymarket activity by market ID
- —Backtest prediction market strategies using historical trade data
Fit
Best for
- —Agents or apps that need granular Polymarket trade-level data
- —Researchers analyzing prediction market microstructure
- —Dashboards displaying real-time Polymarket trading activity
Not for
- —Non-Polymarket prediction platforms (only Polymarket/Polygon is supported)
- —Users needing aggregated volume summaries rather than individual trades (use market-screener or who-bought-sold instead)
- —Free-form natural language research questions (use the Nansen Agent endpoints instead)
Quick start
curl -X POST https://api.nansen.ai/api/v1/prediction-market/trades-by-market \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{"market_id": "654412", "pagination": {"page": 1, "per_page": 10}}'Example
Request
{
"date": {
"to": "2024-11-30T23:59:59Z",
"from": "2024-11-01T00:00:00Z"
},
"order_by": [
{
"field": "timestamp",
"direction": "DESC"
}
],
"market_id": "654412",
"pagination": {
"page": 1,
"per_page": 10
}
}Response
{
"data": [
{
"side": "Yes",
"size": 1000,
"buyer": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
"price": 0.52,
"seller": "0x1234567890abcdef1234567890abcdef12345678",
"tx_hash": "0xabc123def456",
"market_id": "654412",
"timestamp": "2024-11-15T14:32:00",
"usdc_value": 520,
"taker_action": "buy",
"outcome_index": 1
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear endpoint description, x-payment-info and x-credit-cost metadata, and a confirmed 402 MPP challenge indicating the endpoint is live. Minor deductions because no actual response sample was captured from the probe and crawl docs were minimal (only root health check returned).
Warnings
- —No live response body was captured during probing; the example response is constructed from the OpenAPI schema.
- —Crawled documentation pages returned 404s; all information is derived from the OpenAPI spec.
Citations
- —Trades are decoded from on-chain OrderFilled events on Polygon, joined with market metadata.https://api.nansen.ai
- —Pricing is $0.01 per call via x402; credit cost is 10 (free) / 1 (pro).https://api.nansen.ai
- —The endpoint is POST /api/v1/prediction-market/trades-by-market with TradesByMarketRequest schema.https://api.nansen.ai
- —The endpoint returned HTTP 402 on HEAD probe, confirming it is live via MPP protocol.https://api.nansen.ai/api/v1/prediction-market/trades-by-market