Place Order

Submit a new order.

POST /orders

Auth: Authorization: Bearer <access_token> (see Authentication).

Request Body

Field	Type	Required	Description
`symbol`	string	Yes	Instrument id (e.g. `"BTC-USDC-PERP"`)
`side`	string	Yes	`"buy"` or `"sell"`
`type`	string	Yes	`"market"`, `"limit"`, or `"peg"`
`quantity`	number	Yes	Order size in base asset (must be > 0)
`price`	number	Conditional	Required for `limit`. Optional for `market` (acts as price cap). Omitted for `peg`.
`peg_reference`	string	Conditional	Required for `peg`: `"mid"`, `"bid"`, or `"ask"`.
`time_in_force`	string	Yes	`"GTC"`, `"GTT"`, `"IOC"`, or `"FOK"`
`expiry_time`	integer	For `GTT`	Nanosecond epoch timestamp at which a `GTT` order expires
`aon`	boolean	No	All-or-None. Default `false`. See Execution Attributes.
`min_fill_size`	number	No	Minimum per-execution fill size
`client_order_id`	string	No	Client-supplied idempotency key (≤64 chars). Duplicates return the existing order.

See Order Compatibility for which type × time_in_force × aon combinations are supported.

Example — Limit Order (GTC)

curl -X POST https://api.godarkdex.com/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "symbol": "BTC-USDC-PERP",
    "side": "buy",
    "type": "limit",
    "quantity": 0.1,
    "price": 95000,
    "time_in_force": "GTC",
    "client_order_id": "my-order-001"
  }'

Example — Market Order (IOC)

curl -X POST https://api.godarkdex.com/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "symbol": "BTC-USDC-PERP",
    "side": "buy",
    "type": "market",
    "quantity": 0.05,
    "time_in_force": "IOC"
  }'

Example — Peg to Mid (GTC)

curl -X POST https://api.godarkdex.com/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "symbol": "BTC-USDC-PERP",
    "side": "buy",
    "type": "peg",
    "peg_reference": "mid",
    "quantity": 0.1,
    "time_in_force": "GTC"
  }'

Success Response

{
  "code": 0,
  "data": {
    "order_id": "ord_01HXYZ12345",
    "client_order_id": "my-order-001",
    "status": "NEW"
  },
  "timestamp": "2026-04-20T10:30:00.123Z",
  "request_id": "req_01HXYZ..."
}

order_id is returned as a string to preserve precision. Use it on DELETE /orders/{orderId}, PATCH /orders/{orderId}, and GET /orders/{orderId}.

A 200 response means the order passed pre-trade risk checks and entered the book — not that it has filled. Track fills via GET /orders/{orderId} or the Orders Channel.

Idempotency

Supplying client_order_id makes POST /orders safely retryable:

First request with a given client_order_id: creates a new order.
Subsequent requests with the same client_order_id (within 24h): return the original order's current state. No duplicate is created.
After 24h, the key is released and reusable.

client_order_id also works as an identifier on DELETE /orders?client_order_id=... and GET /orders?client_order_id=....

Order Status Lifecycle

Status	Description
`NEW`	Order placed and acknowledged
`PARTIALLY_FILLED`	Partial fill received; remainder working
`FILLED`	Fully filled
`CANCELLED`	Cancelled (by user, by TIF expiry, or by system)
`REJECTED`	Rejected at risk check or by matching engine

Valid transitions: NEW → PARTIALLY_FILLED → FILLED | CANCELLED, or NEW → FILLED | CANCELLED | REJECTED directly.

Pre-Trade Risk Validation

Every order is risk-checked before it enters the book. A 200 success response means all checks passed. For the full margin model, health tiers, and liquidation ladder, see Margin & Liquidation.

Check	Error Code
Margin sufficiency	`1410`
Position limits	`1411`
Account in liquidation	`1412`
Leverage exceeds instrument max	`1413`

Risk Rejection Response

{
  "code": 1410,
  "message": "Margin insufficient: available 1200.00 USDC, required 5000.00 USDC",
  "timestamp": "2026-04-20T10:30:00.123Z",
  "request_id": "req_01HXYZ..."
}

For WebSocket placements (op: order.place), the rejection is returned as a rejected event on the orders channel with the matching reject_reason (see Rejection Reasons).