> ## 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. # 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 ```bash theme={null} curl https://api.polynode.dev/v3/wallets/0xa9857c7bcb9bcfafd2c132ab053f34f678610058/trades?limit=1 ``` ```json theme={null} { "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 ```bash theme={null} curl https://api.polynode.dev/v3/wallets/0x.../trades?side=maker&limit=10 ``` ### Trades for a specific token ```bash theme={null} curl https://api.polynode.dev/v3/wallets/0x.../trades?token_id=75783394...&limit=10 ``` ### Trades in a time window ```bash theme={null} curl https://api.polynode.dev/v3/wallets/0x.../trades?after=1778000000&before=1778604000 ``` ### Include combo trades ```bash theme={null} 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. ```json theme={null} { "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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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. ```json theme={null} { "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\ | 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 ```bash theme={null} curl https://api.polynode.dev/v3/wallets/0xa9857c.../trades?condition_id=0x4f05dbc6... ``` ### Filter by market slug ```bash theme={null} curl https://api.polynode.dev/v3/wallets/0xa9857c.../trades?market_slug=dota2-aur1-liquid-2026-05-13 ```