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.

Owner addresses. Pass an owner EOA as the wallet address and the response combines the EOA’s Polymarket wallets (Safe, proxy, deposit wallets) that have data for this endpoint. Passing a Safe, proxy or deposit wallet returns just that wallet, as before. Combined responses list the combined wallets in wallets. See Owner addresses.

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

Owner address fields

Present only when you pass an owner EOA. See Owner addresses.

Field	Type	Description
`wallets`	array	The combined wallets, in a fixed order, each `{wallet, type}` with `type` one of `eoa`, `safe`, `proxy`, or `deposit_wallet`
`trades[].wallet`	string	The wallet this row belongs to
`combo_trades[].wallet`	string	The wallet this row belongs to

role and direction are relative to the row’s wallet. A fill between two of the owner’s wallets appears once for each wallet, with the same id. With group_by, fills are grouped within each wallet, never across wallets, and each grouped row carries wallet.

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

​Owner address fields

​Sort fills by order hash

​User-visible trades

​Aggregate fills by order hash

​Grouped response fields

​Filter by market condition

​Filter by market slug

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

Owner address fields

Sort fills by order hash

User-visible trades

Aggregate fills by order hash

Grouped response fields

Filter by market condition

Filter by market slug