Skip to main content
POST
/
order
Create a new order
curl --request POST \
  --url https://clob.kuest.com/order \
  --header 'Content-Type: application/json' \
  --header 'KUEST_ADDRESS: <kuest_address>' \
  --header 'KUEST_API_KEY: <kuest_api_key>' \
  --header 'KUEST_PASSPHRASE: <kuest_passphrase>' \
  --header 'KUEST_SIGNATURE: <kuest_signature>' \
  --header 'KUEST_TIMESTAMP: <kuest_timestamp>' \
  --data '
{
  "order": {
    "tokenId": "<string>",
    "conditionId": "<string>",
    "maker": "<string>",
    "signer": "<string>",
    "taker": "<string>",
    "makerAmount": "<string>",
    "takerAmount": "<string>",
    "side": "BUY",
    "nonce": "<string>",
    "feeRateBps": "<string>",
    "salt": "<string>",
    "signatureType": 0,
    "signature": "<string>",
    "expiration": "<string>",
    "metadata": {}
  },
  "orderType": "FOK",
  "owner": "<string>",
  "postOnly": false
}
'
{
  "success": true,
  "errorMsg": "<string>",
  "orderID": "<string>",
  "takingAmount": "<string>",
  "makingAmount": "<string>",
  "status": "<string>"
}
Submit a new order to the Kuest central limit order book. Orders are accepted for matching immediately; validation happens synchronously and the response tells you whether the request was persisted.
All order placement calls require the L2 authentication headers: KUEST_ADDRESS, KUEST_SIGNATURE, KUEST_TIMESTAMP, KUEST_API_KEY, and KUEST_PASSPHRASE. Review how to obtain them in the Authentication overview or use the managed console at auth.kuest.com.
When the global circuit breaker is enabled, this endpoint returns 409 with {"error":"system_paused"}. Individually paused books still reply with 409 and {"error":"condition_paused"}. Make sure the owner field matches the KUEST_ADDRESS header; otherwise the API returns 400 and {"error":"owner_address_mismatch"}.

​
Placement status

Order submissions respond with a status field:
StatusMeaning
liveOrder accepted and resting on the book.
errorOrder rejected; see errorMsg for details.

​
Request body

​
Root fields

FieldTypeRequiredDescription
ownerstringYesPolygon address that owns the API key. Must match the KUEST_ADDRESS header.
orderTypestringYesTime-in-force policy for the order (FOK, FAK, GTC, GTD).
postOnlybooleanNoWhen true, the order must rest on the book (GTC/GTD only).
orderobjectYesFull order payload described below.
For GTD orders you must supply an order.expiration in the future. GTC, FAK, and FOK may omit expiration; the engine simply ignores the value when it is not needed.

​
order object

FieldTypeRequiredDescription
tokenIdstringYesIdentifier of the token/outcome being traded.
conditionIdstringYesMarket condition identifier tied to the token.
expirationstringConditionalUnix timestamp (seconds) when the order becomes invalid. Required for GTD, optional otherwise.
makerstringYesAddress that holds the asset being offered.
signerstringYesAddress that produced the signature authorizing the order.
takerstringYesCounterparty address. Use the zero address for open orders.
makerAmountstringYesQuantity provided by the maker, denominated with fixed precision.
takerAmountstringYesQuantity expected from the taker. Must stay within allowed tick sizes.
sidestringYesEither BUY or SELL.
metadataobject|nullNoOptional JSON metadata stored with the order.
noncestringYesMonotonic value chosen by the maker to guard against reuse.
feeRateBpsstringYesMaker fee rate in basis points.
saltstringYesUnique entropy for replay protection. Reuse causes duplicate rejection.
signatureTypenumberYes0 = EOA, 1 = proxy signer, 2 = Gnosis Safe signer.
signaturestringYesHex-encoded signature produced over the order payload.
When the exchange enforces a minimum fee, feeRateBps must be greater than or equal to the base fee returned by GET /fee-rate for the same tokenId.
All fixed-precision numeric values (makerAmount, takerAmount, nonce, feeRateBps, expiration) must be sent as strings to avoid precision issues during parsing. side must be the uppercase string BUY or SELL. owner must match the KUEST_ADDRESS header supplied with the request.

​
Order types

TypePartial fills?Rests on the book?Auto expiration?
FOK (Fill-Or-Kill)❌ No❌ No✅ Immediately if not 100% filled
FAK (Fill-And-Kill / IOC)✅ Yes❌ No✅ Any remaining size cancels right away
GTC (Good-Til-Cancelled)✅ Yes✅ Yes, until cancelled❌ No
GTD (Good-Til-Date)✅ Yes✅ Yes, until the given timestamp✅ At the specified expiration time
For GTD, the engine enforces a one-minute safety buffer. If you need the order to expire in 90 seconds, set expiration = now + 90 + 60.

​
Execution and follow-up

  • A successful placement returns 200 OK with success: true.
  • orderID is the order identifier for tracking. Use GET /data/order/{id} to check final status and filled amounts.
  • Need to retire a resting order? Call DELETE /order.
Order status values returned by GET /data/order/{id} are:
StatusMeaning
openOrder is resting on the book.
partially_filledOrder remains on the book with some fills.
filledOrder fully executed.
cancelledOrder removed. For IOC/FAK, partial fills still return cancelled with non-zero filled amounts.

Headers

​
KUEST_ADDRESS
string
required

Checksummed wallet address performing the request.

​
KUEST_API_KEY
string<uuid>
required

API key obtained from the L1 derivation endpoint.

​
KUEST_PASSPHRASE
string
required

64 character hexadecimal passphrase associated with the API key.

​
KUEST_TIMESTAMP
string
required

Millisecond epoch timestamp (string) used for freshness checks.

​
KUEST_SIGNATURE
string
required

Hex-encoded HMAC-SHA256 signature built from the L2 signing string.

Body

application/json
​
order
object
required
​
orderType
enum<string>
required

Time-in-force policy for the order.

Available options:
FOK,
FAK,
GTC,
GTD
​
owner
string
required

API key owner issuing the request.

​
postOnly
boolean
default:false

When true, the order must rest on the book (GTC/GTD only).

Response

Order placement result

​
success
boolean
required

Indicates whether the order was accepted.

​
errorMsg
string
required

Human-readable status for the placement.

​
orderID
string
required

Order identifier when accepted.

​
takingAmount
string
required

Taker amount reported by the placement engine (empty when not provided).

​
makingAmount
string
required

Maker amount reported by the placement engine (empty when not provided).

​
status
string
required

Placement status (e.g. live or error).