Home/Exchange

Create Exchange Order

Last Updated: 2026-05-29

HTTP Request

POST/v1/exchange/order

Auth: Signed API key required

Permissions: Trade

Signed Location: JSON body

Content-Type: application/json

Convert one customer fiat balance into another fiat balance.

Headers

Parameter Name	Required	Type	Notes
X-MBX-APIKEY	true	string	Provisioned ACCESS_ID. `x-access-id` is also accepted by the backend, but `X-MBX-APIKEY` is recommended.

Request Body

Parameter Name	Required	Type	Notes
fund_password	false	string	Conditionally required when the customer account has a fund password configured.
base_currency	true	string	Source fiat currency.
quote_currency	true	string	Target fiat currency.
amount	true	string	Source amount.
money	true	string	Converted amount expected by the client.
price	true	string	Customer rate used by the client.
timestamp	true	int64	Request timestamp in milliseconds. Microseconds are also accepted and normalized by the server.
recvWindow	false	integer	Optional receive window. Default `5000`, maximum `60000`.
signature	true	string	HMAC-SHA256 signature of the signed payload. `signature` itself is not part of the payload string being signed.

Notes

price must match the current server-side customer rate.
money must match the converted amount derived by the backend.
Insufficient balance returns a business error from the backend.

Request Example

curl -X POST 'https://<host>/v1/exchange/order' \
  -H 'X-MBX-APIKEY: <ACCESS_ID>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fund_password":"<FUND_PASSWORD_IF_REQUIRED>",
    "base_currency":"NGN",
    "quote_currency":"GHS",
    "amount":"1000",
    "money":"650",
    "price":"0.65",
    "timestamp":1717200000000,
    "recvWindow":5000,
    "signature":"<SIGNATURE>"
  }'

Parameter Name

Required

Type

Notes

X-MBX-APIKEY

true

string

Provisioned ACCESS_ID. x-access-id is also accepted by the backend, but X-MBX-APIKEY is recommended.

Request Body

Parameter Name	Required	Type	Notes
fund_password	false	string	Conditionally required when the customer account has a fund password configured.
base_currency	true	string	Source fiat currency.
quote_currency	true	string	Target fiat currency.
amount	true	string	Source amount.
money	true	string	Converted amount expected by the client.
price	true	string	Customer rate used by the client.
timestamp	true	int64	Request timestamp in milliseconds. Microseconds are also accepted and normalized by the server.
recvWindow	false	integer	Optional receive window. Default `5000`, maximum `60000`.
signature	true	string	HMAC-SHA256 signature of the signed payload. `signature` itself is not part of the payload string being signed.

Request Example

curl -X POST 'https://<host>/v1/exchange/order' \
  -H 'X-MBX-APIKEY: <ACCESS_ID>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fund_password":"<FUND_PASSWORD_IF_REQUIRED>",
    "base_currency":"NGN",
    "quote_currency":"GHS",
    "amount":"1000",
    "money":"650",
    "price":"0.65",
    "timestamp":1717200000000,
    "recvWindow":5000,
    "signature":"<SIGNATURE>"
  }'