Skip to main content
POST
/
order
Place Order
curl --request POST \
  --url https://api.example.com/order \
  --header 'Content-Type: application/json' \
  --data '
{
  "order": {
    "order.salt": "<string>",
    "order.maker": "<string>",
    "order.signer": "<string>",
    "order.taker": "<string>",
    "order.conditionId": "<string>",
    "order.tokenId": "<string>",
    "order.makerAmount": "<string>",
    "order.takerAmount": "<string>",
    "order.expiration": "<string>",
    "order.nonce": "<string>",
    "order.feeRateBps": "<string>",
    "order.side": "<string>",
    "order.signatureType": 123,
    "order.signature": "<string>"
  },
  "orderType": "<string>",
  "owner": "<string>"
}
'
{
  "orderID": "<string>",
  "success": true,
  "error": "<string>"
}

​
Overview

The Place Order endpoint allows authenticated users to submit trading orders for prediction market outcomes. Orders can be market orders (immediate execution) or limit orders (executed at specific price levels).

​
Authentication

This endpoint requires CLOB authentication with HMAC signature verification. Required Headers:
  • KUEST_ADDRESS - User’s wallet address
  • KUEST_API_KEY - API key from trading auth credentials
  • KUEST_PASSPHRASE - Passphrase from trading auth credentials
  • KUEST_TIMESTAMP - Current Unix timestamp (seconds)
  • KUEST_SIGNATURE - HMAC signature of the request
  • Content-Type: application/json
  • Accept: application/json

​
Request Body

​
order
object
required
The order object containing all order parameters
​
order.salt
string
required
Random salt value to ensure order uniqueness (bigint as string)
​
order.maker
string
required
Maker address (proxy wallet address)
​
order.signer
string
required
Signer address (user’s wallet address)
​
order.taker
string
required
Taker address (typically zero address for open orders)
​
order.conditionId
string
required
Market condition ID
​
order.tokenId
string
required
Outcome token ID (bigint as string)
​
order.makerAmount
string
required
Amount provided by maker in micro units (bigint as string)
​
order.takerAmount
string
required
Amount provided by taker in micro units (bigint as string)
​
order.expiration
string
required
Order expiration timestamp in seconds (0 for no expiration)
​
order.nonce
string
required
Order nonce (typically 0)
​
order.feeRateBps
string
required
Fee rate in basis points (e.g., “200” for 2%)
​
order.side
string
required
Order side: BUY or SELL
​
order.signatureType
number
required
Signature type (typically 0 for EIP-712)
​
order.signature
string
required
EIP-712 signature of the order
​
orderType
string
required
Type of order execution:
  • GTC - Good Till Cancelled (limit order, default)
  • GTD - Good Till Date (limit order with expiration)
  • FOK - Fill Or Kill (must be fully filled immediately)
  • FAK - Fill And Kill (fill partially, cancel remainder)
​
owner
string
required
Owner API key (from CLOB auth credentials)

​
Response

​
orderID
string
Unique identifier for the created order
​
success
boolean
Indicates if the order was successfully placed

​
Order Amount Calculation

​
Buy Orders

  • makerAmount = price × shares (in micro units)
  • takerAmount = shares (in micro units)

​
Sell Orders

  • makerAmount = shares (in micro units)
  • takerAmount = price × shares (in micro units)
Micro Units: All amounts are in micro units (1 unit = 1,000,000 micro units)

​
Order Validation

Before placing an order, the system validates:
  1. User Authentication - Valid user session and trading auth
  2. Proxy Wallet - User has deployed proxy wallet
  3. Maker Address - Matches user’s proxy wallet address
  4. Balance Check - For buy orders: sufficient collateral balance
  5. Shares Check - For sell orders: sufficient outcome token balance
  6. Signature - Valid EIP-712 signature
  7. Market Status - Market is active and tradable

​
Error Handling

Common error responses:
​
error
string
Error message describing what went wrong

​
Common Errors

  • condition_paused - Trading is paused for this market
  • system_paused - Trading is temporarily paused system-wide
  • not enough balance / allowance - Insufficient available balance
  • order expired - Order expiration timestamp is in the past
  • invalid order signature - Signature verification failed
  • order is invalid. duplicated. - Identical order already exists
  • order couldn't be fully filled, fok orders are fully filled/killed - FOK order cannot be filled
  • not enough unlocked balance - Insufficient unlocked collateral
  • postonly would cross the best bid/ask - Post-only order would execute immediately

​
Example Request

cURL
curl -X POST 'https://api.kuest.io/order' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'KUEST_ADDRESS: 0x1234...' \
  -H 'KUEST_API_KEY: your-api-key' \
  -H 'KUEST_PASSPHRASE: your-passphrase' \
  -H 'KUEST_TIMESTAMP: 1709467200' \
  -H 'KUEST_SIGNATURE: computed-hmac-signature' \
  -d '{
    "order": {
      "salt": "12345678901234567890",
      "maker": "0xproxy...",
      "signer": "0xuser...",
      "taker": "0x0000000000000000000000000000000000000000",
      "conditionId": "0xcondition...",
      "tokenId": "123456789",
      "makerAmount": "500000000",
      "takerAmount": "1000000000",
      "expiration": "0",
      "nonce": "0",
      "feeRateBps": "200",
      "side": "BUY",
      "signatureType": 0,
      "signature": "0xsignature..."
    },
    "orderType": "GTC",
    "owner": "your-api-key"
  }'
```bash

## Example Response

```json
{
  "orderID": "ord_abc123xyz789",
  "success": true
}
```bash

## Order Types Explained

### GTC (Good Till Cancelled)
Limit order that remains active until:
- Fully filled
- Manually cancelled
- Market resolves

### GTD (Good Till Date)
Limit order with expiration timestamp. Automatically cancelled if not filled by expiration time.

### FOK (Fill Or Kill)
Must be fully filled immediately or rejected entirely. Used for market orders when full execution is required.

### FAK (Fill And Kill)
Executes immediately for available liquidity, cancels unfilled portion. Default for market orders.

## See Also

- [Cancel Order](/api/trading/cancel-order) - Cancel an existing order
- [Get Orders](/api/trading/get-orders) - Retrieve user's orders
- [Orderbook](/api/trading/orderbook) - View market orderbook

Build docs developers (and LLMs) love

Get started for freeTalk to us