Fetching trades by builder code

Every CLOB v2 trade carries a builder_code and a builder_fee. The code identifies the app or integrator that routed the order, or the zero address (0x0000...) when the trade was placed directly through Polymarket. There is no dedicated “trades by builder” endpoint; instead, the standard trade endpoints accept a builder_codes filter (comma-separated, max 25) so you can scope any trade query to one or more builders, including the zero address for direct-Polymarket flow.

When to use this

Showing a builder’s recent fills inside a partner dashboard.
Comparing flow between two builder codes over a time window.
Building copy-trading or attribution views that need the originating builder for each trade.

For aggregated analytics (volume, fees, retention, top traders), use the dedicated Builders namespace instead. The guide below covers raw trade rows.

All trades for a builder

Use GET /v1/polymarket/market/trades with builder_codes. You can combine it with any other trade filter (trade_types, min_usd_amount, from, to, etc.).

const { data: trades } = await client.markets.getTrades({
  builder_codes: "0xBUILDER",
  trade_types: "OrderFilled,OrdersMatched",
  limit: 100,
});

Pass multiple codes as a comma-separated list:

?builder_codes=0xBUILDER_A,0xBUILDER_B

A specific trader’s trades for a builder

To intersect “trades by trader X” with “routed via builder Y”, use GET /v1/polymarket/trader/trades/{address} with the same builder_codes filter.

curl "https://api.struct.to/v1/polymarket/trader/trades/0xTRADER?builder_codes=0xBUILDER&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

Scoping to a market or time window

Builder filtering composes with the rest of the trade query parameters. A few common combinations:

Goal	Parameters
One builder, one market	`builder_codes=0xBUILDER&condition_ids=0xabc...`
One builder, last 24h of fills	`builder_codes=0xBUILDER&trade_types=OrderFilled,OrdersMatched&from={now-86400000}`
Whale flow per builder	`builder_codes=0xBUILDER&min_usd_amount=10000`
Buys only	`builder_codes=0xBUILDER&side=0`

Timestamps on /market/trades and /trader/trades are Unix milliseconds.

Paginating through results

The limit cap is 250 per page. For larger backfills, the SDK’s paginate helper streams every matching trade across pages without manual cursor handling:

import { paginate } from "@structbuild/sdk";

for await (const trade of paginate(
  (params) => client.markets.getTrades(params),
  { builder_codes: "0xBUILDER" },
  250,
)) {
  console.log(trade.trade_type, trade.usd_amount);
}

See Pagination for manual cursor handling and how offset and pagination_key interact.

Streaming new trades

The polymarket_trades websocket room accepts the same builder_codes filter, so you can push builder-attributed trades live instead of polling.

{
  "type": "room_message",
  "payload": {
    "room_id": "polymarket_trades",
    "message": {
      "action": "subscribe",
      "builder_codes": ["0xBUILDER"]
    }
  }
}

See WebSockets: trades room for the full subscribe / unsubscribe lifecycle.

Recipes

Documentation Index

​When to use this

​All trades for a builder

​A specific trader’s trades for a builder

​Scoping to a market or time window

​Paginating through results

​Streaming new trades