> ## Documentation Index
> Fetch the complete documentation index at: https://docs.predexon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Trades History
> Fetch historical trade data
Query historical trade data with flexible filtering by market, token, wallet, and time range. All filters are optional - omit them to browse the global trade feed.
All trades mode (no filters) only supports `order=desc` (newest first). Using `order=asc` without a market or wallet filter returns HTTP 400.
**Free & Unlimited.** This endpoint does not count toward your monthly usage limits on any plan.
### V2 fields
Every trade row now carries Polymarket exchange version metadata:
* `exchange_version` - `1` (V1 CTF/NegRiskCTF) or `2` (V2). Defaults to `1`.
* `builder` - V2 builder attribution tag (bytes32 hex). Empty for V1 fills or V2 fills with no builder.
* `metadata` - V2 opaque metadata tag (bytes32 hex). Empty for V1 fills or V2 fills with no metadata.
Use the `builder` query parameter to filter to fills attributed to a specific builder tag.
### Multi-wallet filtering
The `wallet` parameter accepts a single address or a comma-separated list of up to 50 addresses:
```
GET /v2/polymarket/trades?wallet=0xabc...,0xdef...,0x123...&limit=100
```
Returns one merged feed of all listed wallets' trades, time-ordered, with standard cursor pagination — designed for tracking a list of followed wallets. Address order doesn't matter and duplicates are ignored: the same list in any order returns identical results and pagination keys. Trades match on the maker side, same as the single-wallet filter, and the list combines with all other parameters.
### Point lookups by hash
Two optional parameters (each `0x` + 64 hex chars) support full-history point lookups, back to October 2022:
| Parameter | Returns |
| ------------ | ------------------------------------------------------------------------ |
| `tx_hash` | all fills executed in that transaction |
| `order_hash` | all fills of that order (an order can fill across multiple transactions) |
Usable standalone or combined with each other and with any wallet/market/time filters. Invalid hash format returns HTTP 400.
| Constraint | Value |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| `limit` | 1–500 (default 100) |
| `wallet` | up to 50 comma-separated addresses (>50 or any invalid address returns HTTP 400, identifying which one) |
## OpenAPI
````yaml GET /v2/polymarket/trades
openapi: 3.1.0
info:
title: Predexon API
description: Prediction market data aggregation and matching API
version: 2.0.0
servers:
- url: https://api.predexon.com
security:
- apiKey: []
paths:
/v2/polymarket/trades:
get:
tags:
- polymarket
summary: Get Trades
description: >-
Fetch historical trade data.
Returns trades from Polymarket with support for:
- Filtering by market_slug, condition_id, token_id, or wallet
- Multi-wallet filtering: wallet accepts a comma-separated list (max
50);
results are the merged time-ordered feed across all listed wallets
- Point lookups by order_hash or tx_hash
- Time range filtering (start_time, end_time)
- Minimum trade amount filtering (min_total)
- Cursor-based pagination
- Global "all trades" mode (no filters) - returns trades across all
markets
**All Trades Mode:**
When no market/wallet filter is provided, returns global trades
newest-first.
- Only DESC order is supported (returns 400 if order=asc)
- First page defaults to last 24 hours for fast queries
- Pagination automatically extends the time range as you page back
- Provide start_time or end_time to query specific time ranges
operationId: get_trades_v2_polymarket_trades_get
parameters:
- name: market_slug
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by market slug
title: Market Slug
description: Filter by market slug
- name: condition_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by condition ID
title: Condition Id
description: Filter by condition ID
- name: token_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by token ID
title: Token Id
description: Filter by token ID
- name: start_time
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Unix timestamp (seconds) for start
title: Start Time
description: Unix timestamp (seconds) for start
- name: end_time
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Unix timestamp (seconds) for end
title: End Time
description: Unix timestamp (seconds) for end
- name: min_total
in: query
required: false
schema:
anyOf:
- type: number
minimum: 0
- type: 'null'
description: Minimum trade amount in USD
title: Min Total
description: Minimum trade amount in USD
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
description: Number of trades to return
default: 100
title: Limit
description: Number of trades to return
- name: wallet
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter by wallet address(es) — single address or comma-separated
list (max 50)
title: Wallet
description: >-
Filter by wallet address(es) — single address or comma-separated
list (max 50)
- name: builder
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter by V2 builder attribution tag (bytes32 hex, 0x + 64 hex
chars)
title: Builder
description: >-
Filter by V2 builder attribution tag (bytes32 hex, 0x + 64 hex
chars)
- name: order_hash
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by order hash (bytes32 hex, 0x + 64 hex chars)
title: Order Hash
description: Filter by order hash (bytes32 hex, 0x + 64 hex chars)
- name: tx_hash
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by transaction hash (bytes32 hex, 0x + 64 hex chars)
title: Tx Hash
description: Filter by transaction hash (bytes32 hex, 0x + 64 hex chars)
- name: order
in: query
required: false
schema:
$ref: '#/components/schemas/OrderDirection'
description: 'Sort order: asc or desc'
default: desc
description: 'Sort order: asc or desc'
- name: pagination_key
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Cursor for pagination
title: Pagination Key
description: Cursor for pagination
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TradesResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Bad Request
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
components:
schemas:
OrderDirection:
type: string
enum:
- asc
- desc
title: OrderDirection
description: Sort order direction enum.
TradesResponse:
properties:
trades:
items:
$ref: '#/components/schemas/Trade'
type: array
title: Trades
pagination:
$ref: '#/components/schemas/CursorPagination'
type: object
required:
- trades
- pagination
title: TradesResponse
description: Trades endpoint response.
ErrorResponse:
properties:
error:
type: string
title: Error
message:
type: string
title: Message
type: object
required:
- error
- message
title: ErrorResponse
description: Standard error response.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Trade:
properties:
token_id:
type: string
title: Token Id
side:
$ref: '#/components/schemas/OrderSide'
market_slug:
type: string
title: Market Slug
condition_id:
type: string
title: Condition Id
shares:
type: integer
title: Shares
description: Shares (raw blockchain units)
shares_normalized:
type: number
title: Shares Normalized
description: Shares normalized (raw / 1000000)
price:
type: number
title: Price
description: Trade price (0-1 range)
amount_usd:
type: number
title: Amount Usd
description: Trade value in USD
tx_hash:
type: string
title: Tx Hash
title:
type: string
title: Title
timestamp:
type: integer
title: Timestamp
description: Unix timestamp in seconds
order_hash:
type: string
title: Order Hash
description: Order hash (same order can have multiple fills)
user:
type: string
title: User
description: Maker address
taker:
type: string
title: Taker
description: Taker address (counterparty)
is_yes_side:
type: boolean
title: Is Yes Side
description: True if trade is for YES token, False for NO token
outcome_label:
type: string
title: Outcome Label
description: Human-readable outcome label (e.g., 'Yes', 'No', 'Trump', 'Harris')
default: ''
fee_usd:
type: number
title: Fee Usd
description: Trading fee in USD
default: 0
exchange_version:
type: integer
title: Exchange Version
description: 'Exchange contract version: 1 = V1 (CTF/NegRiskCTF), 2 = V2'
default: 1
builder:
type: string
title: Builder
description: >-
V2 builder attribution tag (bytes32 hex). Empty for V1 fills or V2
fills with no builder.
default: ''
metadata:
type: string
title: Metadata
description: >-
V2 opaque metadata tag (bytes32 hex). Empty for V1 fills or V2 fills
with no metadata.
default: ''
type: object
required:
- token_id
- side
- market_slug
- condition_id
- shares
- shares_normalized
- price
- amount_usd
- tx_hash
- title
- timestamp
- order_hash
- user
- taker
- is_yes_side
title: Trade
description: Trade model for Polymarket trades.
CursorPagination:
properties:
limit:
type: integer
title: Limit
description: Requested limit
count:
type: integer
title: Count
description: Number of items in current response
pagination_key:
anyOf:
- type: string
- type: 'null'
title: Pagination Key
description: Base64-encoded cursor for next page
has_more:
type: boolean
title: Has More
description: Whether there are more items available
type: object
required:
- limit
- count
- has_more
title: CursorPagination
description: Cursor-based pagination for endpoints that don't support offset.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
OrderSide:
type: string
enum:
- BUY
- SELL
title: OrderSide
description: Order side enum.
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
````