Build Order

Build an EIP-712 order structure for a user to sign.

Usage

import { BuilderClient, OrderSide, OrderType } from '@opinion-labs/opinion-clob-sdk';

const builder = new BuilderClient({
  host: 'https://openapi.opinion.trade/openapi',
  builderApiKey: 'YOUR_BUILDER_KEY',
  chainId: 56,
});

const orderData = await builder.buildOrderForSigning({
  marketId: 123,
  tokenId: 'outcome_token_id',
  userWalletAddress: '0xSafeAddress...',   // User's Safe wallet (maker)
  side: OrderSide.BUY,
  orderType: OrderType.LIMIT_ORDER,
  amount: 10,
  price: '0.5',
  signerAddress: '0xEOAAddress...',        // User's EOA (signer)
});

console.log(orderData.order);            // Order struct (Record<string, string>)
console.log(orderData.structHash);       // Hash for signing
console.log(orderData.typedData);        // Full EIP-712 typed data
console.log(orderData.exchangeAddress);  // CTF Exchange address
console.log(orderData.currencyAddress);  // Quote token address
console.log(orderData.currencyDecimal);  // Token decimals

Parameters

Parameter	Type	Required	Description
marketId	number	Yes	Market ID (positive integer)
tokenId	string	Yes	Outcome token ID
userWalletAddress	string	Yes	User's Safe wallet address (maker)
side	OrderSide	Yes	OrderSide.BUY (0) or OrderSide.SELL (1)
orderType	OrderType	Yes	OrderType.LIMIT_ORDER (2) or OrderType.MARKET_ORDER (1)
amount	number	Yes	Amount in human-readable units (e.g., 10 for 10 USDC)
price	string	For limit	Price per outcome token (e.g., '0.5'). Required for limit orders.
amountType	string	No	'quote' (default) or 'base'. Quote = ERC20 amount, Base = token amount.
signerAddress	string	No	Signer's EOA address. If different from userWalletAddress, Safe mode (signatureType=2) is used.

Response

interface BuildOrderResult {
  order: Record<string, string>;    // Order struct fields
  structHash: string;               // EIP-712 struct hash for signing
  typedData: {                      // Full EIP-712 typed data
    types: Record<string, Array<{ name: string; type: string }>>;
    primaryType: string;
    domain: Record<string, unknown>;
    message: Record<string, unknown>;
  };
  domain: {
    name: string;                   // 'OPINION CTF Exchange'
    version: string;                // '1'
    chainId: number;
    verifyingContract: string;
  };
  exchangeAddress: string;
  currencyAddress: string;
  currencyDecimal: number;
  marketId: number;
  orderType: number;
  price: string;
}

Signing the Order

IMPORTANT: Order signing uses signHash(structHash), not signTypedData. This is different from Safe TX signing.

// User signs the struct hash directly
const signature = await user.signHash(orderData.structHash);

Test Helper

For testing, you can sign with a private key using the static helper:

const signature = await BuilderClient.signOrderWithPrivateKey(
  orderData.typedData,
  '0xPrivateKey...'
);

Production: Users sign with their own wallet (MetaMask, WalletConnect). The wallet should sign the structHash using personal_sign or equivalent.

Notes

• For limit orders, price is required. For market orders, price is ignored.

• Market BUY orders only accept amountType: 'quote' (how much to spend).

• Market SELL orders only accept amountType: 'base' (how many tokens to sell).

• When signerAddress differs from userWalletAddress, the SDK automatically sets signatureType to 2 (POLY_GNOSIS_SAFE).

• Orders expire 30 days from creation by default.