feat: add authenticated account actions

Author: cesarenaldi

docs/api-boundary-notes.md

@@ -1 +1,3 @@
 # API Boundary Notes
+
+- `GET /balance-allowance` currently returns `{ balance, allowances }`, where `allowances` is keyed by spender address. `clob-client` still models a single `allowance` string.

docs/open-questions.md

@@ -9,3 +9,4 @@ Use this document to capture unresolved SDK questions that should be revisited l
 - CLOB docs say: "All query endpoints require L2 authentication. Builder-authenticated clients can also query orders attributed to their builder account using the same methods." Does builder authentication alone suffice for any standard private query endpoints, or is it only additive to L2 auth? Current backend and `clob-client` behavior appear to require L2 first.
 - What are the intended use cases for deriving or creating more than one API key per wallet? Current docs and `clob-client` guidance seem to suggest repeated key creation should generally not be needed.
 - How many existing builders or integrators rely on `clob-client` with `throwOnError: true`, given that it changes the effective behavior of helpers like `createOrDeriveApiKey()`?
+- What are the intended product and SDK use cases for readonly user API keys, and should they be part of the first `@polymarket/client` release at all?

docs/sdk-direction.md

@@ -17,6 +17,16 @@ The first shipping target is `@polymarket/client`. Its job is to make Polymarket
 - The SDK should feel pragmatic and typed, staying close to real integration needs without forcing consumers to understand how current services are divided.
 - The SDK can still expose lower-level controls when they are useful, but the default experience should feel unified.
 
+## Current Decisions
+
+- Omit readonly API key management from the first `@polymarket/client` surface for now.
+- Keep phase 2 focused on standard authenticated account reads that are clearly part of the primary trading workflow.
+- Revisit readonly API keys later if there is a concrete SDK use case and clearer public documentation.
+
+## TODO
+
+- In this case, make CLOB responses use camelCased fields.
+
 ## Package Direction
 
 - `@polymarket/client` is the main near-term package.

packages/bindings/src/clob/account.ts

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+
+function createCursorPageSchema<TItem extends z.ZodTypeAny>(item: TItem) {
+  return z.object({
+    count: z.number(),
+    data: z.array(item),
+    limit: z.number(),
+    next_cursor: z.string(),
+  });
+}
+
+export const ClosedOnlyModeSchema = z.object({
+  closed_only: z.boolean(),
+});
+
+export type ClosedOnlyMode = z.infer<typeof ClosedOnlyModeSchema>;
+
+export const OpenOrderSchema = z.object({
+  asset_id: z.string(),
+  associate_trades: z.array(z.string()),
+  created_at: z.number(),
+  expiration: z.string(),
+  id: z.string(),
+  maker_address: z.string(),
+  market: z.string(),
+  order_type: z.string(),
+  original_size: z.string(),
+  outcome: z.string(),
+  owner: z.string(),
+  price: z.string(),
+  side: z.string(),
+  size_matched: z.string(),
+  status: z.string(),
+});
+
+export type OpenOrder = z.infer<typeof OpenOrderSchema>;
+
+export const OpenOrdersPageSchema = createCursorPageSchema(OpenOrderSchema);
+
+export type OpenOrdersPage = z.infer<typeof OpenOrdersPageSchema>;
+
+export const MakerOrderSchema = z.object({
+  asset_id: z.string(),
+  fee_rate_bps: z.string(),
+  maker_address: z.string(),
+  matched_amount: z.string(),
+  order_id: z.string(),
+  outcome: z.string(),
+  owner: z.string(),
+  price: z.string(),
+  side: z.string(),
+});
+
+export const ClobTradeSchema = z.object({
+  asset_id: z.string(),
+  bucket_index: z.number(),
+  fee_rate_bps: z.string(),
+  id: z.string(),
+  last_update: z.string(),
+  maker_address: z.string(),
+  maker_orders: z.array(MakerOrderSchema),
+  market: z.string(),
+  match_time: z.string(),
+  outcome: z.string(),
+  owner: z.string(),
+  price: z.string(),
+  side: z.string(),
+  size: z.string(),
+  status: z.string(),
+  taker_order_id: z.string(),
+  trader_side: z.enum(['TAKER', 'MAKER']),
+  transaction_hash: z.string(),
+});
+
+export type ClobTrade = z.infer<typeof ClobTradeSchema>;
+
+export const ClobTradesPageSchema = createCursorPageSchema(ClobTradeSchema);
+
+export type ClobTradesPage = z.infer<typeof ClobTradesPageSchema>;
+
+export const NotificationSchema = z.object({
+  owner: z.string(),
+  payload: z.unknown(),
+  type: z.number(),
+});
+
+export type Notification = z.infer<typeof NotificationSchema>;
+
+export const NotificationsResponseSchema = z.array(NotificationSchema);
+
+export type NotificationsResponse = z.infer<typeof NotificationsResponseSchema>;
+
+export enum AssetType {
+  COLLATERAL = 'COLLATERAL',
+  CONDITIONAL = 'CONDITIONAL',
+}
+
+export const AssetTypeSchema = z.nativeEnum(AssetType);
+
+export const BalanceAllowanceResponseSchema = z.object({
+  allowances: z.record(z.string(), z.string()),
+  balance: z.string(),
+});
+
+export type BalanceAllowanceResponse = z.infer<
+  typeof BalanceAllowanceResponseSchema
+>;
+
+export const OrderScoringResponseSchema = z.object({
+  scoring: z.boolean(),
+});
+
+export type OrderScoringResponse = z.infer<typeof OrderScoringResponseSchema>;
+
+export const OrdersScoringResponseSchema = z.record(z.string(), z.boolean());
+
+export type OrdersScoringResponse = z.infer<typeof OrdersScoringResponseSchema>;
+
+export const UserEarningSchema = z.object({
+  asset_address: z.string(),
+  asset_rate: z.number(),
+  condition_id: z.string(),
+  date: z.string(),
+  earnings: z.number(),
+  maker_address: z.string(),
+});
+
+export type UserEarning = z.infer<typeof UserEarningSchema>;
+
+export const UserEarningsPageSchema = createCursorPageSchema(UserEarningSchema);
+
+export type UserEarningsPage = z.infer<typeof UserEarningsPageSchema>;
+
+export const TotalUserEarningSchema = z.object({
+  asset_address: z.string(),
+  asset_rate: z.number(),
+  date: z.string(),
+  earnings: z.number(),
+  maker_address: z.string(),
+});
+
+export type TotalUserEarning = z.infer<typeof TotalUserEarningSchema>;
+
+export const TotalUserEarningsResponseSchema = z.array(TotalUserEarningSchema);
+
+export type TotalUserEarningsResponse = z.infer<
+  typeof TotalUserEarningsResponseSchema
+>;
+
+export const RewardsPercentagesSchema = z.record(z.string(), z.number());
+
+export type RewardsPercentages = z.infer<typeof RewardsPercentagesSchema>;
+
+export const TokenSchema = z.object({
+  outcome: z.string(),
+  price: z.number(),
+  token_id: z.string(),
+});
+
+export const RewardsConfigSchema = z.object({
+  asset_address: z.string(),
+  end_date: z.string(),
+  rate_per_day: z.number(),
+  start_date: z.string(),
+  total_rewards: z.number(),
+});
+
+export const EarningSchema = z.object({
+  asset_address: z.string(),
+  asset_rate: z.number(),
+  earnings: z.number(),
+});
+
+export const UserRewardsEarningSchema = z.object({
+  condition_id: z.string(),
+  earning_percentage: z.number(),
+  earnings: z.array(EarningSchema),
+  event_slug: z.string(),
+  image: z.string(),
+  maker_address: z.string(),
+  market_competitiveness: z.number(),
+  market_slug: z.string(),
+  question: z.string(),
+  rewards_config: z.array(RewardsConfigSchema),
+  rewards_max_spread: z.number(),
+  rewards_min_size: z.number(),
+  tokens: z.array(TokenSchema),
+});
+
+export type UserRewardsEarning = z.infer<typeof UserRewardsEarningSchema>;
+
+export const UserRewardsEarningsPageSchema = createCursorPageSchema(
+  UserRewardsEarningSchema,
+);
+
+export type UserRewardsEarningsPage = z.infer<
+  typeof UserRewardsEarningsPageSchema
+>;

packages/bindings/src/clob/index.ts

@@ -1,4 +1,7 @@
+export * from './account';
 export * from './api-key';
 export * from './fee-rate';
 export * from './neg-risk';
+export * from './pagination';
+export * from './signature-type';
 export * from './tick-size';

packages/bindings/src/clob/pagination.ts

@@ -0,0 +1,2 @@
+export const INITIAL_CURSOR = 'MA==';
+export const END_CURSOR = 'LTE=';

packages/bindings/src/clob/signature-type.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+
+export enum SignatureType {
+  EOA = 0,
+  POLY_PROXY = 1,
+  POLY_GNOSIS_SAFE = 2,
+}
+
+export const SignatureTypeSchema = z.enum(SignatureType);

packages/bindings/src/gamma/market.ts

@@ -11,6 +11,11 @@ import {
   TagReferenceSchema,
 } from './common';
 
+const TwoStringTupleSchema = z
+  .string()
+  .transform((val) => JSON.parse(val))
+  .pipe(z.tuple([z.string(), z.string()]));
+
 export const MarketSchema = z.looseObject({
   id: MarketIdSchema,
   question: z.string().nullish(),
@@ -34,8 +39,8 @@ export const MarketSchema = z.looseObject({
   lowerBound: z.string().nullish(),
   upperBound: z.string().nullish(),
   description: z.string().nullish(),
-  outcomes: z.string().nullish(),
-  outcomePrices: z.string().nullish(),
+  outcomes: TwoStringTupleSchema.nullish(),
+  outcomePrices: TwoStringTupleSchema.nullish(),
   volume: z.string().nullish(),
   active: z.boolean().nullish(),
   marketType: z.string().nullish(),
@@ -87,7 +92,7 @@ export const MarketSchema = z.looseObject({
   volume1yr: z.number().nullish(),
   gameStartTime: z.string().nullish(),
   secondsDelay: z.number().int().nullish(),
-  clobTokenIds: z.string().nullish(),
+  clobTokenIds: TwoStringTupleSchema.nullish(),
   disqusThread: z.string().nullish(),
   shortOutcomes: z.string().nullish(),
   teamAID: z.string().nullish(),

packages/bindings/src/gamma/wallet.ts

@@ -1,14 +1,12 @@
 import { z } from 'zod';
 
-export enum WalletTypeKind {
+export enum WalletType {
   EOA = 0,
   POLY_PROXY = 1,
   POLY_GNOSIS_SAFE = 2,
 }
 
 export const WalletTypeSchema = z.object({
-  type: z.enum(WalletTypeKind),
+  type: z.enum(WalletType),
   typeName: z.enum(['EOA', 'POLY_PROXY', 'POLY_GNOSIS_SAFE']),
 });
-
-export type WalletType = z.infer<typeof WalletTypeSchema>;

packages/client/src/ServiceClient.ts

@@ -34,7 +34,7 @@ export class ServiceClient {
     RateLimitError | RequestRejectedError | TransportError
   > {
     return this.#toResult(
-      this.#client.get(path, {
+      this.#client.get(this.#normalizePath(path), {
         headers: options.headers,
         searchParams: options.params,
       }),
@@ -49,7 +49,7 @@ export class ServiceClient {
     RateLimitError | RequestRejectedError | TransportError
   > {
     return this.#toResult(
-      this.#client.post(path, {
+      this.#client.post(this.#normalizePath(path), {
         headers: options.headers,
         json: options.json,
       }),
@@ -60,6 +60,10 @@ export class ServiceClient {
     return never('ServiceClient.del is not implemented yet');
   }
 
+  #normalizePath(path: string) {
+    return path.startsWith('/') ? path.slice(1) : path;
+  }
+
   #toResult(
     promise: Promise<Response>,
   ): ResultAsync<