API Docs

Appearance

Place brokerage instruction​

POST
/v2/brokerage

Place a new brokerage instruction order.

This endpoint creates and immediately executes a brokerage instruction to convert one currency to another. The system places automated market orders to convert your specified pay amount from the pay currency into the receive currency, intelligently routing through available currency pairs if necessary.

Multi-Leg Conversions

  • Direct pair (e.g., BTC/ZAR): Single market order
  • Indirect pair (e.g., ZAR→XRP): Routed through intermediate currency (ZAR→USDT→XRP)
  • Each leg incurs separate trading fees in addition to the brokerage fee

Fee Structure

  • feeRate: Your brokerage fee percentage (0.0 to 0.999)
  • feeCurrency: Deducted in either pay or receive currency. If feeCurrency matches payCurrency, the fee is calculated from payAmount before the order. If it matches receiveCurrency, the fee is a percentage of the received amount.
  • feeAccountId: Account that receives the brokerage fee (cannot be the same as the trading account)
  • Each trade leg also incurs standard exchange trading fees

Important Notes

  • The account on which the trade is performed can be specified using the HTTP header. Please see our Subaccounts section for more information. Not including the header will result in the order being placed against your main account.
  • Executes immediately at market prices (no limit orders)
  • Subject to market slippage and liquidity
  • Cannot be cancelled once submitted
  • Requires API key with both trade and internal transfer permissions

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
{
"payAmount": "100",
"payCurrency": "ZAR",
"receiveCurrency": "XRP",
"feeRate": "0.01",
"feeCurrency": "XRP",
"feeAccountId": 1315586846625202200,
"customerOrderId": "brokerage-order-01"
}

Responses​

Brokerage instruction created and executed

application/json

Playground​

Authorization
Body

Samples​