Wallet Trades - PolyNode

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)
`event_slug`	string	—	Filter by event slug (resolves to token IDs across all of the event’s markets)
`event_id`	integer	—	Filter by numeric event ID (same scope as `event_slug`)
`order_hash`	string	—	Return only fills for one exact order hash (`0x` + 64 hex characters)
`min_amount_usd`	number	—	Minimum trade size in dollars, matching the `amount_usd` response field. Decimals allowed, e.g. `99.5`
`min_amount`	integer	—	Minimum `maker_amount_filled` (raw 6-decimal). Prefer `min_amount_usd`
`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

order_hash is applied in the database before pagination. Combine it with any other wallet-trade filter; all supplied filters are intersected. Hex characters are case-insensitive and the response uses the normalized lowercase hash. A well-formed hash with no matching fills returns 200 with an empty trades array. An empty or malformed hash returns 400. Combo trades do not expose a Polymarket order hash, so order_hash cannot be combined with include_combos=true; that combination returns 400.

Example

List every fill where one wallet participated in a specific order:

curl -H "x-api-key: pn_live_YOUR_KEY" \
  "https://api.polynode.dev/v3/wallets/0xa9857c7bcb9bcfafd2c132ab053f34f678610058/trades?order_hash=0x9ed363e9c05368fba5c717b8bee355d60a579f599cb7c007d90974203896a95c"

Add filters normally—for example, maker fills for that order inside one market and time window:

curl -H "x-api-key: pn_live_YOUR_KEY" \
  "https://api.polynode.dev/v3/wallets/0xa9857c7bcb9bcfafd2c132ab053f34f678610058/trades?order_hash=0x9ed363e9c05368fba5c717b8bee355d60a579f599cb7c007d90974203896a95c&side=maker&market_slug=nba-det-cle-2026-05-15&after=1778000000&order=asc"

The unfiltered wallet feed has the same response shape:

curl -H "x-api-key: pn_live_YOUR_KEY" "https://api.polynode.dev/v3/wallets/0xa9857c7bcb9bcfafd2c132ab053f34f678610058/trades?limit=1"

{
  "address": "0xa9857c7bcb9bcfafd2c132ab053f34f678610058",
  "elapsed_ms": 3,
  "has_more": true,
  "limit": 1,
  "offset": 0,
  "rows_returned": 1,
  "trades": [
    {
      "amount": 8.19,
      "amount_usd": 4.914,
      "asset": "31336121594291014914271611062289284423554618020629759821503694496084098706290",
      "builder": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "condition_id": "0x7b461ba0d582c03577966cfdf0da2a5cb9696a26b954b5ed1890f82d6f2a3c88",
      "direction": "SELL",
      "event_id": 465162,
      "event_slug": "nba-det-cle-2026-05-15",
      "fee": 0.05896,
      "id": "0xedcfd55321a267c7a200cac4069e4134d85d538e4c245fe3bf1e59ad3188acd8_0x9ed363e9c05368fba5c717b8bee355d60a579f599cb7c007d90974203896a95c_1168",
      "image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/super+cool+basketball+in+red+and+blue+wow.png",
      "maker": "0xa9857c7bcb9bcfafd2c132ab053f34f678610058",
      "maker_amount": 8.19,
      "maker_asset_id": "31336121594291014914271611062289284423554618020629759821503694496084098706290",
      "market": "Pistons vs. Cavaliers",
      "order_hash": "0x9ed363e9c05368fba5c717b8bee355d60a579f599cb7c007d90974203896a95c",
      "outcome": "Cavaliers",
      "outcome_index": 1,
      "price": 0.6,
      "role": "maker",
      "side": 1,
      "size": 8.19,
      "slug": "nba-det-cle-2026-05-15",
      "taker": "0xe111180000d2663c0091e4f400237545b87b996b",
      "taker_amount": 4.914,
      "taker_asset_id": "0",
      "timestamp": "1778754419",
      "token_id": "31336121594291014914271611062289284423554618020629759821503694496084098706290",
      "transaction_hash": "0xedcfd55321a267c7a200cac4069e4134d85d538e4c245fe3bf1e59ad3188acd8"
    }
  ]
}

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	Amount the maker provided, normalized: outcome tokens, or USD when `maker_asset_id` is `0`
`taker_amount`	number	Amount the taker provided, normalized: outcome tokens, or USD when `taker_asset_id` is `0`
`amount_usd`	number	USD value of the fill (the USDC side of the trade). This is the value the `min_amount_usd` filter compares against
`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
`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
`event_slug`	string \| null	Slug of the Polymarket event this market belongs to
`event_id`	integer \| null	Numeric ID of that event. Both are null for old markets no longer in Polymarket’s catalog

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

​Request

​Query parameters

​Example

​Maker-only trades

​Trades for a specific token

​Trades in a time window

​Include combo trades

​Response fields

​Top-level combo fields

​Trade data

​Market context

​Sort fills by order hash

​User-visible trades

​Aggregate fills by order hash

​Grouped response fields

​Filter by market condition

​Filter by market slug