feat: add limit order preparation workflow

Author: cesarenaldi

docs/sdk-direction.md

@@ -29,6 +29,7 @@ The first shipping target is `@polymarket/client`. Its job is to make Polymarket
 - Add a cache layer for `tickSize`, fee bps, and `negRisk` metadata.
 - Consider moving `SignedOrder` into `packages/client/src/types.ts` so it is easier to reuse across order actions and wallet helpers.
 - Revisit whether the Gamma `GET /markets` `active` flag should be modeled in the SDK, since it is accepted in practice but omitted from the current OpenAPI contract and current client request type.
+- Review `throw new Error` usage in `packages/client/src/actions/orders/market.ts` and decide whether those order-action failures should use a more specific SDK error shape.
 
 ## Package Direction
 

packages/bindings/src/clob/order-response.ts

@@ -7,7 +7,7 @@ export const OrderResponseSchema = z.object({
   status: z.string(),
   success: z.boolean(),
   takingAmount: z.string(),
-  transactionsHashes: z.array(z.string()),
+  transactionsHashes: z.array(z.string()).default([]),
 });
 
 export type OrderResponse = z.infer<typeof OrderResponseSchema>;

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

@@ -1,5 +1,9 @@
 import type { TickSizeValue } from '@polymarket/bindings';
+import type { EvmAddress } from '@polymarket/types';
 import { invariant } from '@polymarket/types';
+import type { SecureClient } from '../../clients';
+import { fetchFeeRate } from '../clob';
+import { fetchPublicProfile } from '../profiles';
 
 export type RoundingConfig = {
   amount: number;
@@ -21,3 +25,31 @@ export function resolveRoundingConfig(tickSize: TickSizeValue): RoundingConfig {
 
   invariant(false, `Unsupported tick size: ${tickSize}`);
 }
+
+export async function resolveFeeRateBps(
+  client: SecureClient,
+  tokenId: string,
+): Promise<number> {
+  return fetchFeeRate(client, {
+    tokenId,
+  });
+}
+
+export async function resolveFunderAddress(
+  client: SecureClient,
+): Promise<EvmAddress> {
+  const profile = await fetchPublicProfile(client, {
+    address: client.address,
+  });
+
+  return profile.proxyWallet ?? client.address;
+}
+
+export function resolveExchangeAddress(
+  client: SecureClient,
+  negRisk: boolean,
+): EvmAddress {
+  return negRisk
+    ? client.environment.negRiskExchange
+    : client.environment.standardExchange;
+}

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

@@ -1,7 +1,3 @@
-export * from './context';
-export * from './market';
-export * from './orders';
 export * from './post';
 export * from './prepare';
-export * from './typed-data';
 export * from './types';

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

@@ -0,0 +1,215 @@
+import { EvmAddressSchema, type TickSizeValue } from '@polymarket/bindings';
+import {
+  OrderSide,
+  OrderSideSchema,
+  OrderType,
+  type SignatureType,
+} from '@polymarket/bindings/clob';
+import type { EvmAddress } from '@polymarket/types';
+import { z } from 'zod';
+import type { SecureClient } from '../../clients';
+import { UserInputError } from '../../errors';
+import { fetchNegRisk, fetchTickSize } from '../clob';
+import {
+  resolveExchangeAddress,
+  resolveFeeRateBps,
+  resolveFunderAddress,
+  resolveRoundingConfig,
+} from './context';
+import {
+  decimalPlaces,
+  parseAmount,
+  roundDown,
+  roundNormal,
+  roundUp,
+} from './math';
+import type { OrderDraft, PrepareLimitOrderRequest } from './types';
+
+export const PrepareLimitOrderParamsSchema = z
+  .object({
+    tokenId: z.string(),
+    price: z.number().positive(),
+    size: z.number().positive(),
+    side: OrderSideSchema,
+    taker: EvmAddressSchema.optional(),
+    expiration: z.number().int().nonnegative().optional(),
+    orderType: z
+      .union([z.literal(OrderType.GTC), z.literal(OrderType.GTD)])
+      .default(OrderType.GTC),
+  })
+  .superRefine((params, context) => {
+    if (params.orderType === OrderType.GTD) {
+      if (params.expiration === undefined) {
+        context.addIssue({
+          code: 'custom',
+          message: 'GTD orders require an expiration timestamp.',
+          path: ['expiration'],
+        });
+        return;
+      }
+
+      const minimumExpiration = Math.floor(Date.now() / 1000) + 60;
+
+      if (params.expiration <= minimumExpiration) {
+        context.addIssue({
+          code: 'custom',
+          message: 'GTD expiration must be at least 60 seconds in the future.',
+          path: ['expiration'],
+        });
+      }
+
+      return;
+    }
+
+    if (params.expiration !== undefined) {
+      context.addIssue({
+        code: 'custom',
+        message: 'Expiration is only supported for GTD orders.',
+        path: ['expiration'],
+      });
+    }
+  }) satisfies z.ZodType<PrepareLimitOrderRequest>;
+
+export type PrepareLimitOrderDraftParams = z.output<
+  typeof PrepareLimitOrderParamsSchema
+>;
+
+type ResolveLimitOrderContextParams = {
+  price: number;
+  tokenId: string;
+};
+
+export async function prepareLimitOrderDraft(
+  client: SecureClient,
+  params: PrepareLimitOrderDraftParams,
+): Promise<OrderDraft> {
+  const context = await resolveLimitOrderContext(client, {
+    price: params.price,
+    tokenId: params.tokenId,
+  });
+  const amounts = computeLimitOrderAmounts({
+    price: context.price,
+    side: params.side,
+    size: params.size,
+    tickSize: context.tickSize,
+  });
+
+  return {
+    chainId: client.environment.chainId,
+    exchangeAddress: context.exchangeAddress,
+    expiration: params.expiration ?? 0,
+    feeRateBps: context.feeRateBps,
+    funderAddress: context.funderAddress,
+    offeredAmount: amounts.offeredAmount,
+    orderType: params.orderType,
+    side: params.side,
+    signatureType: context.signatureType,
+    signer: context.signerAddress,
+    allowedTaker: params.taker,
+    requestedAmount: amounts.requestedAmount,
+    tokenId: params.tokenId,
+  };
+}
+
+type LimitOrderContext = {
+  exchangeAddress: EvmAddress;
+  feeRateBps: number;
+  funderAddress: EvmAddress;
+  negRisk: boolean;
+  price: number;
+  signatureType: SignatureType;
+  signerAddress: EvmAddress;
+  tickSize: TickSizeValue;
+};
+
+async function resolveLimitOrderContext(
+  client: SecureClient,
+  params: ResolveLimitOrderContextParams,
+): Promise<LimitOrderContext> {
+  const signerAddress = client.address;
+  const signatureType = client.signatureType;
+  const funderAddress = await resolveFunderAddress(client);
+  const tickSize = await fetchTickSize(client, {
+    tokenId: params.tokenId,
+  });
+  const feeRateBps = await resolveFeeRateBps(client, params.tokenId);
+  const negRisk = await fetchNegRisk(client, {
+    tokenId: params.tokenId,
+  });
+
+  return {
+    exchangeAddress: resolveExchangeAddress(client, negRisk),
+    feeRateBps,
+    funderAddress,
+    negRisk,
+    price: resolvePrice(params.price, tickSize),
+    signatureType,
+    signerAddress,
+    tickSize,
+  };
+}
+
+function computeLimitOrderAmounts(params: {
+  price: number;
+  side: OrderSide;
+  size: number;
+  tickSize: TickSizeValue;
+}): {
+  offeredAmount: bigint;
+  requestedAmount: bigint;
+} {
+  const roundConfig = resolveRoundingConfig(params.tickSize);
+  const rawPrice = roundNormal(params.price, roundConfig.price);
+
+  if (params.side === OrderSide.BUY) {
+    const rawTakerAmount = roundDown(params.size, roundConfig.size);
+    let rawMakerAmount = rawTakerAmount * rawPrice;
+
+    if (decimalPlaces(rawMakerAmount) > roundConfig.amount) {
+      rawMakerAmount = roundUp(rawMakerAmount, roundConfig.amount + 4);
+
+      if (decimalPlaces(rawMakerAmount) > roundConfig.amount) {
+        rawMakerAmount = roundDown(rawMakerAmount, roundConfig.amount);
+      }
+    }
+
+    return {
+      offeredAmount: parseAmount(rawMakerAmount),
+      requestedAmount: parseAmount(rawTakerAmount),
+    };
+  }
+
+  const rawMakerAmount = roundDown(params.size, roundConfig.size);
+  let rawTakerAmount = rawMakerAmount * rawPrice;
+
+  if (decimalPlaces(rawTakerAmount) > roundConfig.amount) {
+    rawTakerAmount = roundUp(rawTakerAmount, roundConfig.amount + 4);
+
+    if (decimalPlaces(rawTakerAmount) > roundConfig.amount) {
+      rawTakerAmount = roundDown(rawTakerAmount, roundConfig.amount);
+    }
+  }
+
+  return {
+    offeredAmount: parseAmount(rawMakerAmount),
+    requestedAmount: parseAmount(rawTakerAmount),
+  };
+}
+
+function resolvePrice(price: number, tickSize: TickSizeValue): number {
+  const roundConfig = resolveRoundingConfig(tickSize);
+
+  if (price < tickSize || price > 1 - tickSize) {
+    throw new UserInputError(
+      `Price must be between ${tickSize} and ${1 - tickSize} for tick size ${tickSize}.`,
+    );
+  }
+
+  if (decimalPlaces(price) > roundConfig.price) {
+    throw new UserInputError(
+      `Price must conform to tick size ${tickSize} with at most ${roundConfig.price} decimal places.`,
+    );
+  }
+
+  return roundNormal(price, roundConfig.price);
+}