feat: add builder key auth actions

Author: cesarenaldi

packages/bindings/src/clob/api-key.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ApiKeySchema } from '../shared';
+import { ApiKeySchema, ISODateStringSchema } from '../shared';
 
 export const RawApiKeyCredsSchema = z.object({
   apiKey: ApiKeySchema,
@@ -20,3 +20,31 @@ export const ApiKeysResponseSchema = z.object({
 });
 
 export type ApiKeysResponse = z.infer<typeof ApiKeysResponseSchema>;
+
+export const BuilderApiKeyCredsSchema = z.object({
+  key: ApiKeySchema,
+  secret: z.string(),
+  passphrase: z.string(),
+});
+
+export type BuilderApiKeyCreds = z.infer<typeof BuilderApiKeyCredsSchema>;
+
+export const BuilderApiKeySchema = z.object({
+  key: ApiKeySchema,
+  createdAt: ISODateStringSchema.optional(),
+  revokedAt: ISODateStringSchema.nullable().optional(),
+});
+
+export type BuilderApiKey = z.infer<typeof BuilderApiKeySchema>;
+
+export const BuilderApiKeysResponseSchema = z
+  .array(
+    z.union([ApiKeySchema.transform((key) => ({ key })), BuilderApiKeySchema]),
+  )
+  .transform((apiKeys) =>
+    apiKeys.map((apiKey) => BuilderApiKeySchema.parse(apiKey)),
+  );
+
+export type BuilderApiKeysResponse = z.infer<
+  typeof BuilderApiKeysResponseSchema
+>;

packages/client/src/actions/auth.ts

@@ -1,8 +1,12 @@
+import type { ApiKey } from '@polymarket/bindings';
 import {
   type ApiKeyCreds,
   ApiKeyCredsSchema,
-  type ApiKeysResponse,
   ApiKeysResponseSchema,
+  type BuilderApiKey,
+  type BuilderApiKeyCreds,
+  BuilderApiKeyCredsSchema,
+  BuilderApiKeysResponseSchema,
 } from '@polymarket/bindings/clob';
 import { type EvmAddress, type Signature, unwrap } from '@polymarket/types';
 import { z } from 'zod';
@@ -145,9 +149,7 @@ export type FetchApiKeysError =
  * @throws {@link FetchApiKeysError}
  * Thrown when request signing fails, or the request is rejected, rate limited, interrupted by transport issues, or returns an unexpected response.
  */
-export async function fetchApiKeys(
-  client: SecureClient,
-): Promise<ApiKeysResponse['apiKeys']> {
+export async function fetchApiKeys(client: SecureClient): Promise<ApiKey[]> {
   const response = await unwrap(
     client.secureClob
       .get('/auth/api-keys')
@@ -171,7 +173,9 @@ export type DeleteApiKeyError =
  * This is a low-level auth action that most SDK consumers will not need.
  *
  * @example
- * 
+ * ```ts
+ * await deleteApiKey(client);
+ * ```
  *
  * @throws {@link DeleteApiKeyError}
  * Thrown when request signing fails, or the request is rejected, rate limited,
@@ -185,6 +189,100 @@ export async function deleteApiKey(client: SecureClient): Promise<void> {
   );
 }
 
+export type CreateBuilderApiKeyError =
+  | RateLimitError
+  | RequestRejectedError
+  | SigningError
+  | TransportError
+  | UnexpectedResponseError;
+
+/**
+ * Creates a new builder API key for the authenticated client.
+ *
+ * @remarks
+ * This is a low-level auth action that most SDK consumers will not need.
+ *
+ * @example
+ * ```ts
+ * const builderApiKey = await createBuilderApiKey(client);
+ * ```
+ *
+ * @throws {@link CreateBuilderApiKeyError}
+ * Thrown when request signing fails, or the request is rejected, rate limited,
+ * interrupted by transport issues, or returns an unexpected response.
+ */
+export async function createBuilderApiKey(
+  client: SecureClient,
+): Promise<BuilderApiKeyCreds> {
+  return unwrap(
+    client.secureClob
+      .post('/auth/builder-api-key')
+      .andThen(validateWith(BuilderApiKeyCredsSchema)),
+  );
+}
+
+export type FetchBuilderApiKeysError =
+  | RateLimitError
+  | RequestRejectedError
+  | SigningError
+  | TransportError
+  | UnexpectedResponseError;
+
+/**
+ * Fetches builder API keys associated with the authenticated client.
+ *
+ * @remarks
+ * This is a low-level auth action that most SDK consumers will not need.
+ *
+ * @example
+ * ```ts
+ * const builderApiKeys = await fetchBuilderApiKeys(client);
+ * ```
+ *
+ * @throws {@link FetchBuilderApiKeysError}
+ * Thrown when request signing fails, or the request is rejected, rate limited,
+ * interrupted by transport issues, or returns an unexpected response.
+ */
+export async function fetchBuilderApiKeys(
+  client: SecureClient,
+): Promise<BuilderApiKey[]> {
+  return unwrap(
+    client.secureClob
+      .get('/auth/builder-api-key')
+      .andThen(validateWith(BuilderApiKeysResponseSchema)),
+  );
+}
+
+export type RevokeBuilderApiKeyError =
+  | RateLimitError
+  | RequestRejectedError
+  | SigningError
+  | TransportError
+  | UnexpectedResponseError;
+
+/**
+ * Revokes a builder API key.
+ *
+ * @remarks
+ * This is a low-level auth action that most SDK consumers will not need.
+ *
+ * @example
+ * ```ts
+ * await revokeBuilderApiKey(client);
+ * ```
+ *
+ * @throws {@link RevokeBuilderApiKeyError}
+ * Thrown when request signing fails, or the request is rejected, rate limited,
+ * interrupted by transport issues, or returns an unexpected response.
+ */
+export async function revokeBuilderApiKey(client: Client): Promise<void> {
+  await unwrap(
+    client.clob
+      .del('/auth/builder-api-key')
+      .andThen(validateWith(z.literal('OK'))),
+  );
+}
+
 function toL1Headers(auth: ApiKeyAuthRequest): HeadersInit {
   return {
     POLY_ADDRESS: auth.address,

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

@@ -1,8 +1,9 @@
-import { OrderSide, OrderType } from '@polymarket/bindings';
 import {
   type AcceptedOrderResponse,
   OrderPostStatus,
   type OrderResponse,
+  OrderSide,
+  OrderType,
 } from '@polymarket/bindings/clob';
 import { expectPresent } from '@polymarket/types';
 import { describe, expect, it } from 'vitest';