Trading

The Trading API handles order placement, preview, status checking, and cancellation. All trading endpoints require authentication. Orders are routed through a smart router that selects the appropriate exchange (Polymarket or Kalshi) based on the market.

Endpoints

Method	Path	Auth	Description
POST	`/api/v1/orders`	Bearer	Place an order (or preview)
POST	`/api/v1/orders/batch`	Bearer	Place multiple orders at once
GET	`/api/v1/orders/:id`	Bearer	Get order status and details
DELETE	`/api/v1/orders/:id`	Bearer	Cancel an open order
POST	`/api/v1/orders/:id/tp-sl`	Bearer	Set take-profit/stop-loss for an order

Place Order

Submit a new order to buy or sell shares in a prediction market. Set preview: true to get an estimated execution price and fee breakdown without actually placing the order.

Request Body:

Field	Type	Required	Description
`marketId`	string (UUID)	Yes	Market identifier
`side`	string	Yes	`yes` or `no`
`type`	string	Yes	`market` or `limit`
`action`	string	No	`buy` or `sell` (defaults to `buy`)
`amount`	number	Yes	Order amount in USD (min 0.01)
`price`	number	No	Limit price (required for limit orders, 0-1)
`preview`	boolean	No	If `true`, returns a preview without executing
`takeProfit`	number	No	Take-profit price threshold (0-1)
`stopLoss`	number	No	Stop-loss price threshold (0-1)

// POST /api/v1/orders
{
  "marketId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "side": "yes",
  "type": "market",
  "amount": 50
}

// Response 201
{
  "id": "order-uuid-123",
  "marketId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "side": "yes",
  "type": "market",
  "amount": 50.00,
  "price": 0.63,
  "shares": 79.37,
  "fee": 0.50,
  "status": "filled",
  "source": "polymarket",
  "createdAt": "2026-03-27T12:00:00.000Z"
}

Order Preview

Use the same POST /api/v1/orders endpoint with preview: true to get estimated execution details without submitting the order.

// POST /api/v1/orders
{
  "marketId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "side": "yes",
  "type": "market",
  "amount": 50,
  "preview": true
}

// Response 200
{
  "preview": true,
  "side": "yes",
  "type": "market",
  "amount": 50,
  "estimatedPrice": 0.63,
  "estimatedShares": 79.37,
  "fee": 0.50,
  "feeRate": 0.01,
  "total": 50.50,
  "source": "polymarket",
  "chain": "polygon",
  "sufficientBalance": true,
  "availableBalance": 250.00
}

Cancel Order

Cancel an open or pending order. Only non-terminal orders can be cancelled.

// DELETE /api/v1/orders/order-uuid-123

// Response 200
{
  "id": "order-uuid-123",
  "status": "cancelled"
}

Order States

Orders follow a state machine with these transitions:

created -- initial state when order is submitted
pending -- order sent to exchange
partial -- partially filled
filled -- fully executed (terminal)
cancelled -- user-cancelled (terminal)
failed -- execution error (terminal)

Notes

Prices are decimal values between 0 and 1, representing the cost per share (equivalent to the probability)
The smart router automatically selects the exchange based on the market's source
Financial values use Decimal precision -- never floating-point approximations
Take-profit and stop-loss can be set at order time or added later via the TP/SL endpoint