Placing orders

POST /api/orders/place
X-Api-Key: ps_live_<keyId>_<secret>   # needs `orders:write` scope
Content-Type: application/json

interface PlaceOrderReq {
  marketId: string;          // app-level symbol, e.g. "NC26-BIN-83479265"
  side: 'buy' | 'sell';      // lowercase
  outcome: string;           // "0" = YES (first), "1" = NO (second)
  price: string;             // decimal USDC, e.g. "0.42"
  quantity: string;          // decimal outcome qty, e.g. "2"
  nonce: string;             // decimal-string of the salt used in the EIP-712 struct
  expiry: number;            // unix seconds (= Order.expiration); use 0 for no on-chain expiry
  maker: string;             // VAULT address (= VaultFactory.vaultOf(signer))
  signature: string;         // 0x-prefixed EIP-712 signature
  clientOrderId?: string;    // idempotency key (optional, scoped per associatedWallet)
  type?: 'limit' | 'market'; // default 'limit'
  timeInForce?: 'gtc' | 'ioc' | 'fok'; // default 'gtc' for limit, 'ioc' for market
}

import { Wallet, randomBytes, parseUnits } from 'ethers';

// 1. Resolve vault, outcome tokenId, AND the per-market taker fee
const vault    = await vaultFactory.vaultOf(wallet.address);
const market   = await fetch(`${BASE}/api/markets/NC26-BIN-83479265`).then(r => r.json());
const tokenId  = market.yesTokenId;       // outcome '0'
const feeBps   = BigInt(market.feeTakerBps);  // CRITICAL — see callout below

// 2. Build + sign EIP-712 (see /concepts/trading/eip712-signing)
const salt     = BigInt('0x' + randomBytes(32).toString('hex'));
const priceWei = parseUnits('0.42', 6);
const qtyWei   = parseUnits('2',    6);
// CEIL on BUY notional. FLOOR-signed BUY orders are rejected at
// placement (code: order_signed_with_floor_notional) because they
// overflow the matcher's per-fill CEIL math on the closing tail
// fill. See /concepts/trading/eip712-signing#rounding-rule-ceil-on-buy-floor-on-sell-notional
const notionalWei = (priceWei * qtyWei + 999_999n) / 1_000_000n;

const orderStruct = {
  salt, maker: vault, signer: wallet.address,
  taker: '0x0000000000000000000000000000000000000000',
  tokenId: BigInt(tokenId),
  makerAmount: notionalWei,        // BUY → USDC notional
  takerAmount: qtyWei,             // BUY → outcome qty
  expiration: 0n,
  feeRateBps: feeBps,              // MUST equal market.feeTakerBps
  side: 0, signatureType: 1,       // BUY, VAULT
};
const signature = await wallet.signTypedData(domain, types, orderStruct);

// 3. POST
const resp = await fetch(`${BASE}/api/orders/place`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Api-Key': process.env.PS_API_KEY! },
  body: JSON.stringify({
    marketId:      'NC26-BIN-83479265',
    side:          'buy',
    outcome:       '0',
    price:         '0.42',
    quantity:      '2',
    nonce:         salt.toString(),
    expiry:        0,
    maker:         vault,
    signature,
    clientOrderId: `mm-bot-${Date.now()}`,
    type:          'limit',
    timeInForce:   'gtc',
  }),
}).then(r => r.json());

interface PlaceOrderResp {
  orderId: string;             // server-issued UUID, '' when status=REJECTED
  status: 'PENDING' | 'OPEN' | 'FILLED' | 'CANCELLED' | 'REJECTED' | 'EXPIRED' | 'SETTLEMENT_FAILED';
  filledQty: string;           // cumulative fill at response time (decimal)
  remainingQty: string;        // quantity - filledQty
  trades: TradeFill[];         // synchronous fills produced by IOC/FOK or aggressive LIMIT
  code?: string;               // present when status=REJECTED (insufficient_funds, …)
  message?: string;            // human-readable explanation; pairs with code
  clientOrderId?: string;      // echoed from request when supplied
}