feat: add builder-authorized client support

Author: cesarenaldi

.env.example

@@ -1 +1,4 @@
 POLYMARKET_TEST_PRIVATE_KEY=0xYOUR_TEST_PRIVATE_KEY
+POLYMARKET_BUILDER_API_KEY=YOUR_BUILDER_API_KEY
+POLYMARKET_BUILDER_SECRET=YOUR_BUILDER_SECRET
+POLYMARKET_BUILDER_PASSPHRASE=YOUR_BUILDER_PASSPHRASE

.github/workflows/ci.yml

@@ -44,6 +44,9 @@ jobs:
       - name: Test
         run: pnpm test
         env:
+          POLYMARKET_BUILDER_API_KEY: ${{ secrets.POLYMARKET_BUILDER_API_KEY }}
+          POLYMARKET_BUILDER_PASSPHRASE: ${{ secrets.POLYMARKET_BUILDER_PASSPHRASE }}
+          POLYMARKET_BUILDER_SECRET: ${{ secrets.POLYMARKET_BUILDER_SECRET }}
           POLYMARKET_TEST_PRIVATE_KEY: ${{ secrets.POLYMARKET_TEST_PRIVATE_KEY }}
 
       - name: Build

env.d.ts

@@ -2,5 +2,8 @@ declare namespace NodeJS {
   interface ProcessEnv {
     CI: string | undefined;
     POLYMARKET_TEST_PRIVATE_KEY: string | undefined;
+    POLYMARKET_BUILDER_API_KEY: string | undefined;
+    POLYMARKET_BUILDER_SECRET: string | undefined;
+    POLYMARKET_BUILDER_PASSPHRASE: string | undefined;
   }
 }

packages/bindings/src/clob/builder.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { TokenIdSchema } from '../shared';
+import { OrderSideSchema } from './order';
+
+export const BuilderTradeSchema = z.looseObject({
+  id: z.string(),
+  tradeType: z.string(),
+  takerOrderHash: z.string(),
+  builder: z.string(),
+  market: z.string(),
+  assetId: TokenIdSchema,
+  side: OrderSideSchema,
+  size: z.string(),
+  sizeUsdc: z.string(),
+  price: z.string(),
+  status: z.string(),
+  outcome: z.string(),
+  outcomeIndex: z.number().int(),
+  owner: z.string(),
+  maker: z.string(),
+  transactionHash: z.string(),
+  matchTime: z.string(),
+  bucketIndex: z.number().int(),
+  fee: z.string(),
+  feeUsdc: z.string(),
+  err_msg: z.string().nullable().optional(),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional(),
+});
+export type BuilderTrade = z.infer<typeof BuilderTradeSchema>;
+
+export const PaginatedBuilderTradesSchema = z.object({
+  limit: z.number().int(),
+  count: z.number().int(),
+  next_cursor: z.string(),
+  data: z.array(BuilderTradeSchema),
+});
+export type PaginatedBuilderTrades = z.infer<
+  typeof PaginatedBuilderTradesSchema
+>;

packages/bindings/src/clob/index.ts

@@ -1,5 +1,6 @@
 export * from './account';
 export * from './api-key';
+export * from './builder';
 export * from './cancel';
 export * from './fee-rate';
 export * from './market-data';

packages/bindings/src/index.ts

@@ -1,2 +1 @@
-export * from './clob';
 export * from './shared';

packages/client/src/actions/builders.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+// biome-ignore lint/style/noRestrictedImports: intentional
+import { createPublicClient } from '../node';
+import { builderCredentials } from '../testing';
+import { listBuilderTrades } from './builders';
+
+describe('Builders', () => {
+  describe('listBuilderTrades', () => {
+    it('lists builder trades', async () => {
+      const client = createPublicClient({
+        builder: builderCredentials,
+      });
+
+      const result = await listBuilderTrades(client);
+
+      expect(Array.isArray(result)).toBe(true);
+    });
+  });
+});

packages/client/src/actions/builders.ts

@@ -0,0 +1,107 @@
+import {
+  type BuilderTrade,
+  PaginatedBuilderTradesSchema,
+} from '@polymarket/bindings/clob';
+import { unwrap } from '@polymarket/types';
+import { z } from 'zod';
+import type { Client } from '../clients';
+import type {
+  RateLimitError,
+  RequestRejectedError,
+  TransportError,
+  UnexpectedResponseError,
+  UserInputError,
+} from '../errors';
+import { parseUserInput } from '../input';
+import { validateWith } from '../response';
+import { toSearchParams } from './params';
+
+const ListBuilderTradesRequestSchema = z.object({
+  after: z.string().optional(),
+  before: z.string().optional(),
+  builder: z.string().optional(),
+  id: z.string().optional(),
+  market: z.string().optional(),
+  tokenId: z.string().optional(),
+});
+
+export type ListBuilderTradesRequest = z.input<
+  typeof ListBuilderTradesRequestSchema
+>;
+
+export type ListBuilderTradesError =
+  | RateLimitError
+  | RequestRejectedError
+  | TransportError
+  | UnexpectedResponseError
+  | UserInputError;
+
+/**
+ * Lists builder-attributed trades.
+ *
+ * @throws {@link ListBuilderTradesError}
+ * Thrown when the request is invalid, rejected, rate limited, interrupted by transport issues, or returns an unexpected response.
+ *
+ * @example
+ * ```ts
+ * const trades = await listBuilderTrades(client, {})
+ *
+ * // trades === BuilderTrade[]
+ * ```
+ */
+export async function listBuilderTrades(
+  client: Client,
+  request: ListBuilderTradesRequest = {},
+): Promise<BuilderTrade[]> {
+  const params = parseUserInput(request, ListBuilderTradesRequestSchema);
+
+  return listAllBuilderTradePages(async (nextCursor) => {
+    const requestPath = '/builder/trades';
+
+    return unwrap(
+      client.clob
+        .get(requestPath, {
+          params: toSearchParams(
+            {
+              after: params.after,
+              before: params.before,
+              builder: params.builder,
+              id: params.id,
+              market: params.market,
+              nextCursor,
+              tokenId: params.tokenId,
+            },
+            {
+              after: 'after',
+              before: 'before',
+              builder: 'builder',
+              id: 'id',
+              market: 'market',
+              nextCursor: 'next_cursor',
+              tokenId: 'asset_id',
+            },
+          ),
+        })
+        .andThen(validateWith(PaginatedBuilderTradesSchema)),
+    );
+  });
+}
+
+async function listAllBuilderTradePages(
+  fetchPage: (nextCursor: string) => Promise<{
+    data: BuilderTrade[];
+    next_cursor: string;
+  }>,
+): Promise<BuilderTrade[]> {
+  let nextCursor = 'MA==';
+  const results: BuilderTrade[] = [];
+
+  while (nextCursor !== 'LTE=') {
+    const response = await fetchPage(nextCursor);
+
+    results.push(...response.data);
+    nextCursor = response.next_cursor;
+  }
+
+  return results;
+}

packages/client/src/actions/index.ts

@@ -1,6 +1,7 @@
 export * from './account';
 export * from './activity';
 export * from './auth';
+export * from './builders';
 export * from './clob';
 export * from './comments';
 export * from './events';