API Docs

Appearance

Place limit order​

POST
/v1/orders/limit

Create a new limit order.

Parameter Description
side (required) BUY or SELL
quantity (required) Base amount (the amount submitted will be truncated to baseDecimalPlaces of the currency pair)
price (required) Price in quote Currency
pair (required) Can be any supported currency pair e.g. BTCUSDC, ETHUSDC or BTCUSDT
postOnly (optional) postOnly=true will place a Maker order and cause it to fail if matched immediately. Default value is false
customerOrderId (optional) Alphanumeric value. Must be unique across all open orders. Supports alphanumeric characters and dashes, 50-character limit.
timeInForce (optional) Can be GTC, FOK or IOC. Default value is GTC.
allowMargin (optional) true or false. Default value is false. Set to true for margin/leverage trades.
reduceOnly (optional) true or false. Default value is false. Set to true for Perpetual Futures orders that should only reduce a position.

Fee currency depends on maker/taker role and trade side:

Role BUY SELL
Maker Quote currency Base currency
Taker Base currency Quote currency

Failure reasons (delivered asynchronously via WebSocket):

  • Insufficient balance
  • Non-unique customerOrderId
  • postOnly order would have matched immediately
  • Self-trade prevention
  • Insufficient liquidity (FOK/IOC)

V1 order endpoints return 202 Accepted. Validation errors such as insufficient balance are delivered asynchronously via WebSocket, not as HTTP error responses. Use the Order Status REST API or WebSocket API to receive the status of this order.

Optional parameters: postOnly (true to place a Maker order that fails if matched immediately, default false), customerOrderId (alphanumeric value for tracking, must be unique across all open orders), timeInForce (GTC/FOK/IOC, default GTC), allowMargin (true/false for margin/leverage trades, default false), reduceOnly (true/false for orders that should only reduce a position, default false).

  • customerOrderId:
    Supports alphanumeric characters and dashes ("-"), with a 50-character limit. Must be unique across all open orders for a given account. Reusing an id from an active order will prevent the new order from being placed.

  • timeInForce:
    Defines how long an order remains active:

    • GTC (Good Till Cancelled): Remains active until fully filled or explicitly cancelled.
    • FOK (Fill or Kill): Must be fully filled immediately or cancelled entirely. No partial fills.
    • IOC (Immediate or Cancel): Fills as much as possible immediately; any unfilled portion is cancelled.

  • allowMargin:
    Set to true for margin/leverage trades. Only subaccounts can trade on margin, and each must be enabled individually via the account/status API.

  • reduceOnly:
    Set to true for Perpetual Futures orders that should only reduce an existing position, preventing the order from opening a new position or increasing the size of an existing one.

Authorizations​

apiKey

Your API key

Type
API Key (header: X-VALR-API-KEY)
+
apiSignature

HMAC SHA512 signature of the request (see Authentication section)

Type
API Key (header: X-VALR-SIGNATURE)
+
apiTimestamp

Request timestamp in milliseconds

Type
API Key (header: X-VALR-TIMESTAMP)

Request Body​

application/json
JSON
{
"side": "SELL",
"quantity": "0.020000",
"price": "62829",
"pair": "BTCUSDT",
"postOnly": false,
"customerOrderId": "LimitSell",
"timeInForce": "GTC",
"allowMargin": "false"
}

Responses​

Limit order accepted

application/json
JSON
{
"id": "14ed7fbc-272e-4bac-a4f9-7ec8df36df34"
}

Playground​

Authorization
Body

Samples​