> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polynode.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Trade History (Wallet)
> Complete onchain trade fill history for any wallet. Every fill, every counterparty, every fee.
Returns every onchain trade fill for a wallet — both maker and taker sides, every fill, every counterparty, every fee. Pulled directly from onchain settlement data, never misses a fill. Each trade is enriched with market metadata (question, slug, outcome, image).
**Want the entire wallet's history in one call?** Use [Trade History (Wallet) — Bulk](/api-reference/onchain/wallet-trades-all) (Growth plan and above). Returns up to 250K trades in a single response, no pagination.
## Quick start — get the most recent 100 trades
```bash theme={null}
curl "https://api.polynode.dev/v2/onchain/wallets/{address}/trades?limit=100" \
-H "x-api-key: YOUR_KEY"
```
Default `limit=100`, max `limit=1000`. That's all most apps need.
## Get every trade for the wallet (full history)
To walk the entire history, add `?cursor=` (empty value) to the first request, then **for each next page, copy `pagination.cursor` from the response back into the URL**. Stop when `pagination.has_more` is `false`.
Three complete copy-paste scripts that walk an entire wallet:
```python Python theme={null}
import requests
API_KEY = "YOUR_KEY"
WALLET = "0xc944d399164b4460a4a79184fc6f419027891e0a"
def get_all_trades(wallet):
cursor = "" # empty string = first page
all_trades = []
while True:
r = requests.get(
f"https://api.polynode.dev/v2/onchain/wallets/{wallet}/trades",
params={"limit": 1000, "cursor": cursor},
headers={"x-api-key": API_KEY},
).json()
all_trades.extend(r["trades"])
if not r["pagination"]["has_more"]:
break
cursor = r["pagination"]["cursor"] # feed this into the next request
return all_trades
trades = get_all_trades(WALLET)
print(f"got {len(trades)} trades")
```
```javascript JavaScript theme={null}
const API_KEY = "YOUR_KEY";
const WALLET = "0xc944d399164b4460a4a79184fc6f419027891e0a";
async function getAllTrades(wallet) {
let cursor = ""; // empty string = first page
const allTrades = [];
while (true) {
const url = `https://api.polynode.dev/v2/onchain/wallets/${wallet}/trades`
+ `?limit=1000&cursor=${encodeURIComponent(cursor)}`;
const r = await fetch(url, { headers: { "x-api-key": API_KEY } }).then(r => r.json());
allTrades.push(...r.trades);
if (!r.pagination.has_more) break;
cursor = r.pagination.cursor; // feed this into the next request
}
return allTrades;
}
const trades = await getAllTrades(WALLET);
console.log(`got ${trades.length} trades`);
```
```bash bash theme={null}
KEY="YOUR_KEY"
WALLET="0xc944d399164b4460a4a79184fc6f419027891e0a"
CURSOR=""
TOTAL=0
while true; do
RESP=$(curl -s "https://api.polynode.dev/v2/onchain/wallets/$WALLET/trades?limit=1000&cursor=$CURSOR" \
-H "x-api-key: $KEY")
COUNT=$(echo "$RESP" | python3 -c "import json,sys;print(json.load(sys.stdin)['count'])")
HAS_MORE=$(echo "$RESP" | python3 -c "import json,sys;print(json.load(sys.stdin)['pagination']['has_more'])")
TOTAL=$((TOTAL + COUNT))
echo "got $COUNT trades, total: $TOTAL"
[ "$HAS_MORE" = "False" ] && break
CURSOR=$(echo "$RESP" | python3 -c "import json,sys;print(json.load(sys.stdin)['pagination']['cursor'])")
done
```
Each page takes \~1 second regardless of how many trades the wallet has. The loop just keeps running until `has_more` is `false`.
## Request
```
GET /v2/onchain/wallets/{address}/trades?limit=100
GET /v2/onchain/wallets/{address}/trades?limit=1000&cursor=
```
| Parameter | Type | Location | Description |
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address` | string | path | Wallet address (0x-prefixed, 40 hex chars) |
| `limit` | integer | query | Max results per page (default 100, max 1000) |
| `cursor` | string | query | Pass empty string `?cursor=` for first page, then echo back `pagination.cursor` from each response. Required to walk past the first page reliably on heavy wallets. |
| `offset` | integer | query | Alternative to cursor: skip first N. Fast for the first \~25K results then degrades. Use `cursor` for anything bigger. |
## Response
```json theme={null}
{
"wallet": "0xc944d399164b4460a4a79184fc6f419027891e0a",
"source": "onchain",
"count": 1,
"pagination": {
"limit": 1000,
"has_more": false
},
"trades": [
{
"tx_hash": "0x3611178d615caeab8f1fb32bc6232a32aaf93fc1e2f5bc5c9914ce2ddb9a13c3",
"order_hash": "0x8676e03168a3cbf39bc1c695e9419127605bd070ff26e7cd628b662c363a82b5",
"timestamp": 1777503244,
"maker": "0xc944d399164b4460a4a79184fc6f419027891e0a",
"taker": "0xe111180000d2663c0091e4f400237545b87b996b",
"maker_asset_id": "0",
"taker_asset_id": "110959653450933276250915064669875552310439627880508793089816880777942697720191",
"maker_amount": 4723.199764,
"taker_amount": 4737.412,
"fee": 0,
"side": "maker",
"direction": "BUY",
"market": "US x Iran ceasefire extended by April 22, 2026?",
"slug": "us-x-iran-ceasefire-extended-by-april-22-2026",
"outcome": "No",
"image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/us-x-iran-ceasefire-by-Cgmx3GCuOwjs.jpg"
}
]
}
```
When `pagination.has_more` is `true`, the response also includes a `pagination.cursor` string — pass that as `?cursor=` for the next request.
| Field | Type | Description |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `count` | integer | Number of trades in this response |
| `pagination.has_more` | boolean | `true` if more pages available — keep paginating |
| `pagination.cursor` | string | Pass back as `?cursor=` for the next page (only present when `has_more` is `true`) |
| `trades[].tx_hash` | string | Transaction hash |
| `trades[].timestamp` | number | Unix timestamp of the fill |
| `trades[].order_hash` | string | Order hash that was filled |
| `trades[].maker` | string | Maker wallet address |
| `trades[].taker` | string | Taker wallet address |
| `trades[].maker_asset_id` | string | Asset the maker provided (`"0"` = USDC) |
| `trades[].taker_asset_id` | string | Asset the taker provided (CTF token ID) |
| `trades[].maker_amount` | number | Amount maker provided (USDC) |
| `trades[].taker_amount` | number | Amount taker provided (tokens) |
| `trades[].fee` | number | Fee paid on this fill (USDC) |
| `trades[].side` | string | `"maker"` or `"taker"` relative to the queried wallet — exchange role on this fill |
| `trades[].direction` | string | `"BUY"` or `"SELL"` from the queried wallet's perspective. `BUY` = wallet contributed USDC and received outcome tokens. `SELL` = wallet contributed outcome tokens and received USDC. |
| `trades[].market` | string | Market question |
| `trades[].slug` | string | Market slug |
| `trades[].outcome` | string | Outcome label (e.g. "Yes", "Up", "Trump") |
| `trades[].image` | string | Market image URL |
## `side` vs `direction`
Both fields are populated on every row, and they answer different questions:
* **`side`** = was the wallet the **maker** (resting limit order) or **taker** (crossing the spread) on this fill?
* **`direction`** = did the wallet **BUY** outcome shares (gave USDC) or **SELL** them (received USDC)?
You'll see all four combinations in real wallets — a maker can be a buyer or seller depending on which side of the orderbook they posted to. Same for takers.
## OpenAPI
````yaml GET /v2/onchain/wallets/{address}/trades
openapi: 3.1.0
info:
title: PolyNode API
description: >-
Real-time Polymarket data API with decoded mempool settlements, OHLCV
candles, and full Polygon JSON-RPC proxy.
contact:
name: PolyNode
url: https://polynode.dev
license:
name: ''
version: 2.0.0
servers:
- url: https://api.polynode.dev
description: Production
security:
- api_key: []
paths:
/v2/onchain/wallets/{address}/trades:
get:
tags:
- Onchain
summary: Wallet trade history (onchain)
description: Complete onchain trade fill history for any wallet.
operationId: onchain_wallet_trades
parameters:
- name: address
in: path
required: true
schema:
type: string
description: Wallet address
- name: limit
in: query
schema:
type: integer
default: 100
description: Max results (max 1000)
- name: offset
in: query
schema:
type: integer
default: 0
description: Skip first N results
- name: cursor
in: query
schema:
type: string
description: >-
Cursor pagination. Pass empty string `?cursor=` for the first page,
then echo back `pagination.cursor` from each response. Format:
`:`. Each page loads at the same speed regardless of
depth — recommended over offset for paging beyond ~25K results.
responses:
'200':
description: Trade fills
'401':
description: Unauthorized
security:
- apiKey: []
components:
securitySchemes:
api_key:
type: apiKey
in: header
name: x-api-key
````