Wallet Trades

Get all trades for a wallet with market context, computed price, direction, and order hash.

Returns fills where the wallet participated as maker, taker, or both. Each trade is enriched with market metadata, computed price/size in USD, buy/sell direction, and the order hash.

Request

GET /v3/wallets/{address}/trades

Query parameters

Parameter	Type	Default	Description
side	string	both	maker, taker, or both
token_id	string	—	Filter trades involving this token
condition_id	string	—	Filter by market condition ID (resolves to token IDs)
market_slug	string	—	Filter by market slug (resolves to token IDs)
min_amount	integer	—	Minimum maker_amount_filled (raw 6-decimal)
sort_by	string	—	order_hash groups fills by limit order visually (individual fill rows, sorted by most recent order)
group_by	string	—	user_trade returns Polymarket-style user-visible trade rows; transaction_hash is an alias; order_hash aggregates wallet-visible fills per order
after	integer	—	Start of time range (Unix timestamp)
before	integer	—	End of time range (Unix timestamp)
include_combos	boolean	false	Add combo trades in a separate combo_trades branch. If the wallet has no combo trades, the response remains 200 with an empty combo branch.
order	string	desc	asc or desc
limit	integer	100	Max 300
offset	integer	0	Pagination offset

Example

curl https://api.polynode.dev/v3/wallets/0xa9857c7bcb9bcfafd2c132ab053f34f678610058/trades?limit=1

{
  "address": "0xa9857c7bcb9bcfafd2c132ab053f34f678610058",
  "trades": [
    {
      "id": "0x284b61d18c8e0a60333bfe883288c7d9861c9c07a410050f537550940038a713_951",
      "maker": "0xa9857c7bcb9bcfafd2c132ab053f34f678610058",
      "taker": "0xe111180000d2663c0091e4f400237545b87b996b",
      "maker_asset_id": "0",
      "taker_asset_id": "75783394880030392863380883800697645018418815910449662777195626260206142035810",
      "maker_amount": 0.999999,
      "taker_amount": 1.694914,
      "fee": 0.01229,
      "price": 0.59,
      "size": 1.694914,
      "timestamp": "1778674056",
      "transaction_hash": "0x284b61d18c8e0a60333bfe883288c7d9861c9c07a410050f537550940038a713",
      "order_hash": "0x21245a1d81ff19d7effcdb7e3b78d5fe66098708a7dc7cad2267f81d237acc7f",
      "builder": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "side": 0,
      "role": "maker",
      "direction": "BUY",
      "market": "Dota 2: Aurora vs Team Liquid (BO3) - DreamLeague Group A",
      "slug": "dota2-aur1-liquid-2026-05-13",
      "outcome": "Aurora",
      "outcome_index": 0,
      "image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/dota2-7ffacddb21.jpg",
      "condition_id": "0x4f05dbc6273b89aed46bb79a961c1d8771c01925d92d439e9a81fa6241900661"
    }
  ],
  "rows_returned": 1,
  "has_more": true,
  "offset": 0,
  "limit": 1,
  "elapsed_ms": 40
}

Maker-only trades

curl https://api.polynode.dev/v3/wallets/0x.../trades?side=maker&limit=10

Trades for a specific token

curl https://api.polynode.dev/v3/wallets/0x.../trades?token_id=75783394...&limit=10

Trades in a time window

curl https://api.polynode.dev/v3/wallets/0x.../trades?after=1778000000&before=1778604000

Include combo trades

curl "https://api.polynode.dev/v3/wallets/0x63613e3b96f418332d43cd2af8dc321014d15907/trades?include_combos=true&limit=5"

Combo trades are returned in combo_trades so existing consumers of the standard trades array do not need to change parsing logic.

{
  "address": "0x63613e3b96f418332d43cd2af8dc321014d15907",
  "trades": [],
  "rows_returned": 0,
  "include_combos": true,
  "included_position_types": ["market", "combo"],
  "combo_trade_count": 5,
  "combo_has_more": true,
  "combo_source": "v3.wallet_combos.trades",
  "combo_trades": [
    {
      "position_type": "combo",
      "wallet_role": "maker",
      "wallet_address": "0x63613e3b96f418332d43cd2af8dc321014d15907",
      "counterparty_address": "0xe3333700ca9d93003f00f0f71f8515005f6c00aa",
      "combo_condition_id": "0x0310c8c1e924b0ddffd987430c42fc26e10000000000000000000000000000",
      "position_id": "1741334187009265192213210063949860811096650382021683265628751751539647840256",
      "side": "BUY",
      "price": "0.0197",
      "size": "0.050750",
      "fee": "0.000020",
      "tx_hash": "0xf3a8985f04bf869483ef4163a185f296c834eb827b5e5ae3db5bd44558121d51",
      "block_number": 88276713,
      "timestamp": 1781120055,
      "source": "v3.wallet_combos.trades"
    }
  ]
}

Response fields

Top-level combo fields

Field	Type	Description
include_combos	boolean	Present when include_combos=true was requested
included_position_types	array	Includes market and combo when combo inclusion was requested
combo_trades	array	Combo trade rows for the wallet
combo_trade_count	integer	Number of combo trade rows returned in this page
combo_has_more	boolean	Whether more combo trade rows are available
combo_source	string	Source label for the combo trade branch

Trade data

Field	Type	Description
id	string	Unique fill ID (transaction_hash + log index)
maker	string	Maker wallet address
taker	string	Taker wallet address
maker_asset_id	string	Asset the maker provided (0 = USDC)
taker_asset_id	string	Asset the taker provided (0 = USDC)
maker_amount	number	USD amount the maker provided
taker_amount	number	USD amount the taker provided
fee	number	Fee charged (USD)
token_id	string	Outcome token ID for the visible trade leg
asset	string	Alias for token_id, included for Polymarket compatibility
amount	number	Alias for size, included for Polymarket compatibility
price	number	Computed price per outcome token (maker_amount / taker_amount or inverse)
size	number	Number of outcome tokens traded (USD)
timestamp	string	Unix timestamp
transaction_hash	string	On-chain transaction hash
order_hash	string	Unique order hash for this fill
builder	string	Builder attribution code (hex)
side	integer	Maker’s limit order direction: 0 = maker was buying tokens, 1 = maker was selling tokens, null for V1 trades. This is the maker’s side, not the queried wallet’s action. Use direction instead for the wallet’s perspective.
role	string	maker or taker — which side the queried wallet was on in this fill
direction	string	BUY or SELL — whether the queried wallet bought or sold outcome tokens. This is the field you want for understanding what the wallet did.

Market context

Field	Type	Description
market	string	Market question text
slug	string	Market URL slug
outcome	string	Outcome label (e.g. “Yes”, “Aurora”)
outcome_index	integer	Outcome position (0 or 1)
image	string	Market image URL
condition_id	string	Market condition ID

Sort fills by order hash

curl https://api.polynode.dev/v3/wallets/0xa9857c.../trades?sort_by=order_hash&limit=10

Groups all fills belonging to the same limit order together visually, sorted by most recent order first. Returns individual fill rows.

User-visible trades

curl https://api.polynode.dev/v3/wallets/0xa9857c.../trades?market_slug=dota2-aur1-liquid-2026-05-13&group_by=user_trade

Returns one row per user-visible trade, matching the Polymarket-style wallet trade feed. This removes complementary order-side rows that can appear in raw CTF fills and merges fills that represent the same user action. Use this grouping for UI trade history and user-facing volume math.

group_by=transaction_hash is accepted as an alias for this behavior.

Aggregate fills by order hash

curl https://api.polynode.dev/v3/wallets/0x61b0ea32aff59e9893e867a2ab196476ab22dd96/trades?group_by=order_hash

Returns one row per wallet-visible order with aggregated totals. Complementary order-side rows are collapsed from the queried wallet’s perspective before order aggregation, so UI volume and share counts do not double-count both sides of the same user action. Use group_by=user_trade when you want one row per user-visible fill without order-level rollup.

{
  "trades": [
    {
      "order_hash": "0xea91f0d67086be...",
      "fill_count": 5,
      "avg_price": 0.57,
      "total_amount_usd": 669.11,
      "total_usd": 669.11,
      "total_shares": 1173.88,
      "total_fee": 0.0,
      "total_maker_amount": 669.11,
      "total_taker_amount": 1173.88,
      "first_fill_at": 1778100000,
      "last_fill_at": 1778200000,
      "tx_hashes": ["0xabc...", "0xdef..."],
      "market": "MegaETH market cap (FDV) >$1.5B one day after TGE?",
      "slug": "megaeth-fdv-1-5b-one-day-after-tge",
      "outcome": "Yes",
      "direction": "BUY"
    }
  ],
  "rows_returned": 6,
  "grouped_by": "order_hash"
}

Grouped response fields

Field	Type	Description
order_hash	string	The limit order hash
fill_count	integer	Number of fills in this order
avg_price	number	Volume-weighted average price (total_amount_usd / total_shares)
total_amount_usd	number	Total USD value across all fills. Alias of total_usd, included for compatibility with grouped onchain trade responses.
total_usd	number	Total USD value across all fills
total_shares	number	Total outcome tokens across all fills
total_fee	number	Total fees (USD)
total_maker_amount	number	Raw sum of maker amounts (side-dependent)
total_taker_amount	number	Raw sum of taker amounts (side-dependent)
first_fill_at	integer	Earliest fill timestamp (Unix seconds)
last_fill_at	integer	Latest fill timestamp (Unix seconds)
timestamp	string	Same as last_fill_at but as a string. Present for consistency with ungrouped trade rows.
tx_hashes	array<string>	Unique transaction hashes contributing to this order
market	string | null	Market question
slug	string | null	Market slug
outcome	string | null	Outcome label
outcome_index	integer | null	Outcome position (0 or 1)
image	string | null	Market image URL
condition_id	string | null	Market condition ID
direction	string	BUY or SELL (queried wallet’s perspective)
role	string	maker or taker (which side the queried wallet was on)
side	integer | null	Maker’s limit-order direction (raw on-chain value). Use direction instead.
maker	string	Maker wallet address
taker	string	Taker wallet address

Filter by market condition

curl https://api.polynode.dev/v3/wallets/0xa9857c.../trades?condition_id=0x4f05dbc6...

Filter by market slug

curl https://api.polynode.dev/v3/wallets/0xa9857c.../trades?market_slug=dota2-aur1-liquid-2026-05-13