> ## Documentation Index
> Fetch the complete documentation index at: https://docs.struct.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetching trades by builder code

> Filter trades on a Polymarket builder code to surface order flow attributed to a specific app or integrator.

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](/api-reference/builders/list-builders-ranked-by-activity) 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.).

<CodeGroup>
  ```typescript SDK theme={null}
  const { data: trades } = await client.markets.getTrades({
    builder_codes: "0xBUILDER",
    trade_types: "OrderFilled,OrdersMatched",
    limit: 100,
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/market/trades?builder_codes=0xBUILDER&trade_types=OrderFilled,OrdersMatched&limit=100" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.struct.to/v1/polymarket/market/trades",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={
          "builder_codes": "0xBUILDER",
          "trade_types": "OrderFilled,OrdersMatched",
          "limit": 100,
      },
  )

  trades = response.json()["data"]
  ```
</CodeGroup>

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.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/trader/trades/0xTRADER?builder_codes=0xBUILDER&limit=100" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```typescript SDK theme={null}
  const { data: trades } = await client.trader.getTraderTrades({
    address: "0xTRADER",
    builder_codes: "0xBUILDER",
    limit: 100,
  });
  ```
</CodeGroup>

## 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:

```typescript theme={null}
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](/sdk/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.

```json theme={null}
{
  "type": "room_message",
  "payload": {
    "room_id": "polymarket_trades",
    "message": {
      "action": "subscribe",
      "builder_codes": ["0xBUILDER"]
    }
  }
}
```

See [WebSockets: trades room](/websockets/rooms/trades) for the full subscribe / unsubscribe lifecycle.