ABOUT Mandala Exchange API

Mandala Exchange REST & Streaming API version 3.0 provides programmatic access to Mandala Exchange’s next generation trading engine.

We strongly recommend that our new customers use API version 3.0 to get the best trading experience. We also recommend that our current traders switch to the newest version 3.0.

API version 2.0 is still available. For detailed description refer to API v2.

By using the Mandala Exchange API you confirm that you have read and accepted the API License Agreement.

DEVELOPMENT GUIDE

API URLs


REST	`https://api.trade.mandala.exchange/api/3`
Streaming Market Data	`wss://api.trade.mandala.exchange/api/3/ws/public`
Streaming Trading	`wss://api.trade.mandala.exchange/api/3/ws/trading`
Streaming Wallet	`wss://api.trade.mandala.exchange/api/3/ws/wallet`

API Explorer

You can explore the API using Swagger UI including methods requiring authorization.

DateTime Format

All timestamps are returned in ISO 8601 format or UNIX timestamp in milliseconds (UTC).

Example: "2024-04-03T10:20:49.315Z" or "1614815872000".

Date Format

Some timestamps are returned in ISO 8601 format which includes a calendar date only.

Example: "2024-04-03".

Number Format

All finance data, e.g., price, quantity, fee, etc., should be arbitrary precision numbers and have a string representation.

Example: "10.2000058".

Custom Formats

In nested JSON objects, child objects have custom formats which are described in tables below a place of the first occurrence.

Pagination

Parameter	Description
`limit`	Number of results per call.
`offset`	Number of results offset.
`sort`	Sort direction. Accepted values: `ASC` (ascending order), `DESC` (descending order)
`by`	Filter type. Accepted values: `id`, `timestamp`
`from`	Interval initial value. If filter by `timestamp` is used, then parameter type is `DateTime`; otherwise — `Number`.
`till`	Interval end value. If filter by `timestamp` is used, then parameter type is `DateTime`; otherwise — `Number`.

RATE LIMITS

The maximum number requests per second (RPS) for specific calls can be limited by a rate limit and a burst limit.

The server will process a number of requests that do not exceed the sum of the rate limit and the burst limit within the 1-second sliding window.

If both limits in total are exceeded, an HTTP 429 response is returned.

Requests are being counted per call (REST endpoint or WebSocket message) and:

per IP address — requests arrived from the same IP address regardless of the identity;
per account — requests sent under the same identity regardless of an API key, session, connection or IP address.

Per IP Address

REST API

Path	Rate limit	Burst limit
`/*` (default)	`20`	`30`
`/public/*`	`30`	`50`
`/wallet/*`	`10`	`10`
`/buy-crypto/provider/*`	`10`	`10`
`/buy-crypto/fiat2crypto/*`	`10`	`10`
`/spot/order/*`	`300`	`450`
`/margin/order/`, `/margin/account/`, `/margin/position/*`	`300`	`450`
`/futures/order/`, `/futures/account/`, `/futures/position/*`	`300`	`450`
`/transfer-convert/config`	`10`	`10`

Socket API

Path	Rate limit	Burst limit
`/ws/public`	`10`	`10`
`/ws/trading`	`10`	`10`
`/ws/wallet`	`10`	`10`

Per Account

REST API

Path	Rate limit	Burst limit
`/wallet/*`, `/transfer-convert/config`	`20`	`30`
`/buy-crypto/*`	`20`	`30`

Socket API

/ws/trading:

Method	Rate limit	Burst limit
`login`	`5`	—
`spot_subscribe`, `spot_unsubscribe`, `spot_balance_subscribe`, `spot_balance_unsubscribe`	`5`	—
`margin_subscribe`, `margin_unsubscribe`	`5`	—
`futures_subscribe`, `futures_unsubscribe`, `futures_balance`	`5`	—
`spot_balances`, `spot_fee`	`20`	`10`
`margin_get_accounts`	`20`	`10`
`futures_get_accounts`, `futures_balances`, `futures_fee`	`20`	`10`
`spot_new_order`, `spot_new_order_list`, `spot_replace_order`	`300`	`200`
`margin_new_order`, `margin_new_order_list`, `margin_replace_order`	`300`	`200`
`futures_new_order`, `futures_new_order_list`, `futures_replace_order`	`300`	`200`

/ws/wallet:

Method	Rate limit	Burst limit
`login`	`2`	`10`
`subscribe_transactions`, `unsubscribe_transactions`, `subscribe_wallet_balances`, `unsubscribe_wallet_balances`, `wallet_balances`, `wallet_balance`, `transactions`	`5`	`10`

CHANGELOG

22.10.2024

Added endpoint:
- GET /api/3/wallet/crypto/address/white-list.

02.10.2024

Added the ability to specify stop_price while replacing an order.

04.09.2024

Added endpoints:
- GET /api/3/wallet/crypto/fee/withdraw/hash.

16.07.2024

Added idempotency_key parameter in: * POST /api/3/wallet/swap/transaction/market; * POST /api/3/wallet/swap/transaction/fixed.

17.05.2024

Added endpoints:
- POST /api/3/wallet/crypto/fee/estimate/bulk.

15.05.2024

Added last_activity_at field in the transaction model.
Added sorting transaction history by last_activity_at.

10.05.2024

Added fee_cumulative field in the position model and history.
Added close_position parameter in new order requests and responses.

19.04.2024

Added optional product parameter in wallet/swap/* endpoints.

05.03.2024

Changed access permissions in swap calls.
Added new 20018 error code.

05.02.2024

GET /buy-crypto/provider/{provider_id}/order:

from and till filters are optional now;
added new filters: order_by and sort.

01.02.2024

Changed the way of calculating rates returned by the GET /api/3/public/price/rate call.
Added new GET /api/3/public/converted/candles and GET /api/3/public/converted/candles/{symbol} endpoints which return candles converted to the given currency.
Changed the way of calculating rates published by the /price/rate feed.
Added a new converted/candles/{period} feed which returns candles converted to the given currency.
Added a new asset_id field in the network object that contains unique arbitrary data identifying the coin.

02.11.2023

Added support of multichain that allows specifying a combination of a currency and a base blockchain:

GET /api/3/public/currency:
- added preferred_network request parameter;
- added contract_address response field;
- added networks response field;
- properties of blockchain networks moved to items in networks.
POST /api/3/wallet/crypto/withdraw:
- added network_code request body field.
GET /api/3/wallet/transactions:
- added networks request parameter;
- added network_code response field in native object;
- added protocol_code response field in native object.
GET /api/3/wallet/crypto/address:
- added network_code request parameter;
- added network_code response field.
POST /api/3/wallet/crypto/address:
- added network_code request body field;
- added network_code response field.
GET /api/3/wallet/crypto/address/recent-deposit:
- added network_code request parameter;
- added network_code response field.
GET /api/3/wallet/crypto/address/recent-withdraw:
- added network_code request parameter;
- added network_code response field.
GET /api/3/wallet/crypto/fee/estimate:
- added network_code request parameter.
GET /api/3/wallet/crypto/fee/levels:
- added network_code request parameter.
GET /api/3/buy-crypto/provider/{provider_id}/order:
- added network_code request body field.
POST /api/3/buy-crypto/provider/{provider_id}/order:
- added target_network_code request parameter.
POST /api/3/wallet/crypto/fees/estimate:
- added network_code request body field;
- added networkCode response field.

09.10.2023

Added the commit risk score in the transaction history for deposits.

25.09.2023

Added a new operation_type field in the transaction history.

25.07.2023

Changed default TIF instructions for new orders.

07.07.2023

A new GET /api/3/wallet/crypto/fees/estimate endpoint.

22.06.2023

Cross-margin accounts.

16.06.2023

OTC trades.

31.05.2023

A new preferred_network filter in the GET /api/3/public/currency endpoint.

19.05.2023

WebSocket price/rate/ feeds.

15.11.2022

WebSocket balance feed.

28.07.2022

One-Triggers-Other (OTO) order lists.

30.03.2022

Swaps.

16.03.2022

All-Or-None (AON), One-Cancels-Other (OCO), and One-Triggers-One-Cancels-Other (OTOCO) order lists.
Positions history endpoint.
Clearing details endpoint.

12.01.2022

Cash-settled futures.

27.12.2021

Take-profit orders.

23.12.2021

Reduce-only orders.

08.12.2021

Margin parameters.

23.11.2021

Amount locks.

19.11.2021

Increased rate limits up to 300 requests per second.

10.11.2021

The WebSocket request to get a single–currency trading balance.
Allowed to view and get trading history for disabled symbols.
Allowed to get trading history by several comma-separated symbols.

25.08.2021

Airdrops section.

24.08.2021

Added ability to request Wallet and Trading balance for a single currency.
subscribe_balance method replaced by subscribe_wallet_balances. Response was changed. Changes are backward compatible.
Eased key permissions for GET /api/3/margin/account, /api/3/margin/account/isolated/{symbol} and socket margin_get_accounts from "Place/cancel orders" to "Orderbook, History, Trading balance".
Eased key permissions for GET /api/3/futures/account, /api/3/futures/account/isolated/{symbol} and socket futures_get_accounts from "Place/cancel orders" to "Orderbook, History, Trading balance".
Added taker field to trade execution reports both for REST and WS.
Fixed market data subscription acknowledgment wasn't returned in some cases.
Fixed unsubscribe methods on trading subscriptions.

30.07.2021

New endpoints for futures:
- GET /api/3/public/futures/candles/open_interest to query open interest candles.
- GET /api/3/public/futures/history/funding to query perpetual contracts funding history.

28.07.2021

API v3 initial release.

BEST PRACTICES

The Mandala Exchange API development team strives to bring the best trading experience to API users. This manual contains a set of best practices for using the API as efficiently as possible.

Request Parameters

Pass a request payload (body) in POST requests and query parameters — in GET requests.

Passing parameters in a way different from the documentation is not supported.

HTTP Persistent Connection

The underlying TCP connection is kept active for multiple requests/responses. Subsequent requests will result in reduced latency as the TCP handshaking process is no longer required.

If you use the HTTP 1.0 client, please ensure it supports the Keep-Alive directive and submit the "Connection: Keep-Alive" header with a request.

Keep-Alive is a part of the HTTP/1.1 or HTTP/2 protocol and enabled by default on compliant clients. However, you will have to ensure your implementation does not set other values as the connection header.

Retrieving and Updating Account State

Use the Streaming API for real-time updates of orders, trades, and any transaction changes.

REST API REFERENCE

HTTP Status Codes

200 OK. Successful request
400 Bad Request. Returns JSON with the error message
401 Unauthorized. Authorization is required or has been failed
403 Forbidden. Action is forbidden
404 Not Found. Data requested cannot be found
429 Too Many Requests. Your connection has been rate limited
500 Internal Server. Internal Server Error
503 Service Unavailable. Service is down for maintenance
504 Gateway Timeout. Request timeout expired

Error Response

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

All error responses have error code and human-readable message fields. Some errors contain an additional description field.

Market Data

Currencies

Get Currencies

curl "https://api.trade.mandala.exchange/api/3/public/currency"

Response:

{
  "BTC":
  {
    "full_name": "test",
    "crypto": true,
    "payin_enabled": true,
    "payout_enabled": true,
    "transfer_enabled": true,
    "sign": "฿",
    "qr_prefix": "bitcointestnet:",
    "crypto_payment_id_name": "",
    "crypto_explorer": "https://blockchain.info/tx/{tx}",
    "precision_transfer": "1",
    "delisted": false,
    "networks": [
      {
        "code": "test123",
        "network": "test",
        "protocol": "test123",
        "default": true,
        "is_ens_available": true,
        "payin_enabled": true,
        "payout_enabled": true,
        "precision_payout": "1",
        "payout_fee": "0.000000000000",
        "payout_is_payment_id": false,
        "payin_payment_id": false,
        "payin_confirmations": 3
      }
    ]
  },
  "ETH":
  {
    "full_name": "Ethereum TST",
    "crypto": true,
    "payin_enabled": true,
    "payout_enabled": true,
    "transfer_enabled": true,
    "sign": "E",
    "qr_prefix": "ethereum:",
    "crypto_payment_id_name": "",
    "crypto_explorer": "https://www.etherchain.org/tx/{tx}",
    "precision_transfer": "0.000000000001",
    "delisted": false,
    "networks": [
      {
        "code": "ETHTEST",
        "network_name": "ETHTEST",
        "network": "ETHTEST",
        "protocol": "",
        "default": true,
        "is_ens_available": true,
        "payin_enabled": true,
        "payout_enabled": true,
        "precision_payout": "0.000000000000000001",
        "payout_fee": "0.000000000000",
        "payout_is_payment_id": false,
        "payin_payment_id": false,
        "payin_confirmations": 2,
        "is_multichain": false
      }
    ]
  }
}

GET /api/3/public/currency

Returns the actual list of available currencies, tokens, etc.

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`currencies`	String	Optional. Comma-separated list of currency codes.
`preferred_network`	String	Optional. Code of the default network for currencies.

Response:

Name	Type	Description
`full_name`	String	Currency full name (e.g., `"Bitcoin"`).
`crypto`	Boolean	Flag indicating whether the currency is a cryptocurrency.
`payin_enabled`	Boolean	Flag indicating whether generating deposit addresses is allowed for the currency.
`payout_enabled`	Boolean	Flag indicating whether withdrawals are allowed for the currency.
`transfer_enabled`	Boolean	Flag indicating whether transfers between the bank and the exchange accounts are allowed for the network (may be disabled on maintenance).
`sign`	String	Currency sign.
`crypto_payment_id_name`	String	The name of an additional account identifier used for the protocol.
`crypto_explorer`	String	The link to the currency explorer with "{tx}" placeholder instead of a hash.
`precision_transfer`	Number	The minimum amount of a transfer.
`account_top_order`	Number	Optional. The absolute position of the currency in the currency list.
`qr_prefix`	String	The QR prefix used for indication of the currency in a deposit address.
`delisted`	Boolean	Flag indicating whether the currency has been delisted.
`networks`	[]Network	Networks that may host operations on the currency.

Network model consists of:

Name	Type	Description
`code`	String	Currency code.
`network_name`	String	Full network name.
`network`	String	Code of the currency of the hosting network.
`is_ens_available`	Boolean	Flag indicating whether the network supports ENS (Ethereum Name Service).
`protocol`	String	Optional. The standard or protocol underlying network operations or smart contracts. If equals `code`, the currency is the network native currency. If `"TOKEN"`, the currency is a token build on top of this layer-2 network. Example: `"ERC20"`
`default`	Boolean	Flag indicating whether the network is the default for the currency.
`payin_enabled`	Boolean	Flag indicating whether generating deposit addresses is allowed for the network.
`payout_enabled`	Boolean	Flag indicating whether withdrawals are allowed for the network.
`precision_payout`	Number	The minimum amount of a withdrawal.
`payout_fee`	Number	Optional. The minimal possible fee value constituted of the network fee charged by a blockchain and the maintenance fee charged by the exchange.
`payout_is_payment_id`	Boolean	Flag indicating whether providing additional information for withdrawals is needed.
`payin_payment_id`	Boolean	Flag indicating whether providing additional information for deposits is needed.
`payin_confirmations`	Number	The number of confirmation needed for a transaction to be accepted in the network.
`address_regex`	String	Optional. Regular expression to a deposit address.
`payment_id_regex`	String	Optional. Regular expression for a payment identifier.
`low_processing_time`	Number	Optional. The lowest processing time in seconds for a withdrawal.
`high_processing_time`	Number	Optional. The highest processing time in seconds for a withdrawal.
`avg_processing_time`	Number	Optional. The average processing time in seconds for a withdrawal.
`crypto_payment_id_name`	String	Optional. Transaction identifier, e.g., comment, message, memo, attachment, etc.
`crypto_explorer`	String	Optional. The link to the network explorer with "{tx}" placeholder instead of a hash.
`contract_address`	String	Token contract address.
`is_multichain`	Boolean	Flag indicating whether multichain is active for the network.
`asset_id`	JSON	Optional. A unique arbitrary object that identifies a coin. Each network has its own set of properties returned inside the object.

Get Currency

curl "https://api.trade.mandala.exchange/api/3/public/currency/BTC"

Response:

{
  "full_name": "test",
  "crypto": true,
  "payin_enabled": true,
  "payout_enabled": true,
  "transfer_enabled": true,
  "sign": "฿",
  "qr_prefix": "bitcointestnet:",
  "crypto_payment_id_name": "",
  "crypto_explorer": "https://blockchain.info/tx/{tx}",
  "precision_transfer": "1",
  "delisted": false,
  "networks": [
    {
      "code": "test123",
      "network_name": "test123",
      "network": "test",
      "protocol": "test123",
      "default": true,
      "is_ens_available": true,
      "payin_enabled": true,
      "payout_enabled": true,
      "precision_payout": "1",
      "payout_fee": "0.000000000000",
      "payout_is_payment_id": false,
      "payin_payment_id": false,
      "payin_confirmations": 3,
      "is_multichain": false
    }
  ]
}

GET /api/3/public/currency/{currency}

Returns the data for a certain currency.

Requires no API key Access Rights.

Response:

Name	Type	Description
`full_name`	String	Currency full name (e.g., `"Bitcoin"`).
`crypto`	Boolean	Flag indicating whether the currency is a cryptocurrency.
`payin_enabled`	Boolean	Flag indicating whether generating deposit addresses is allowed for the currency.
`payout_enabled`	Boolean	Flag indicating whether withdrawals are allowed for the currency.
`transfer_enabled`	Boolean	Flag indicating whether transfers between the bank and the exchange accounts are allowed for the network (may be disabled on maintenance).
`sign`	String	Currency sign.
`crypto_payment_id_name`	String	The name of an additional account identifier used for the protocol.
`crypto_explorer`	String	The link to the currency explorer with "{tx}" placeholder instead of a hash.
`precision_transfer`	Number	The minimum amount of a transfer.
`account_top_order`	Number	Optional. The absolute position of the currency in the currency list.
`qr_prefix`	String	The QR prefix used for indication of the currency in a deposit address.
`delisted`	Boolean	Flag indicating whether the currency has been delisted.
`networks`	[]Network	Networks that may host operations on the currency.

Symbols

Get Symbols

curl "https://api.trade.mandala.exchange/api/3/public/symbol"

Response:

{
  "ETHBTC": {
    "type": "spot",
    "base_currency": "ETH",
    "quote_currency": "BTC",
    "status": "working",
    "quantity_increment": "0.001",
    "tick_size": "0.000001",
    "take_rate": "0.001",
    "make_rate": "-0.0001",
    "fee_currency": "BTC",
    "margin_trading": true,
    "max_initial_leverage": "10.00"
  }
}

GET /api/3/public/symbol

Returns the actual list of currency symbols (currency pairs) traded on exchange. The first listed currency of a symbol is called the base currency, and the second currency is called the quote currency.

The currency pair indicates how much of the quote currency is needed to purchase one unit of the base currency.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`symbols`	String	Comma-separated list of symbol codes.

Response:

Name	Type	Description
`type`	String	Symbol type. Possible values: `spot`, `futures`
`contract_type`	String	Contract type. Possible values: `perpetual`, `cash_settled`
`expiry`	DateTime or null	Futures expiration date. `null` for perpetual contracts.
`underlying`	String	Futures contract underlying asset.
`base_currency`	String or null	Name (code) of base currency, (e.g., `"ETH"`). For futures contracts is `null`.
`quote_currency`	String	Name (code) of quote currency.
`status`	String	Exchange status. Possible values: `working`, `suspended`, `clearing`
`quantity_increment`	Number	Symbol quantity should be divided by this value with no remainder.
`tick_size`	Number	Symbol price should be divided by this value with no remainder.
`take_rate`	Number	Default fee rate.
`make_rate`	Number	Default fee rate for market making trades.
`fee_currency`	String	Currency in which fees are determined.
`margin_trading`	Boolean	Whether margin trading is available.
`max_initial_leverage`	Number	Optional. Maximum leverage that the user can use for margin trading. Shown only if `margin_trading` is `true`.

Get Symbol

curl "https://api.trade.mandala.exchange/api/3/public/symbol/ETHBTC"

Response:

{
  "type": "spot",
  "base_currency": "ETH",
  "quote_currency": "BTC",
  "status": "working",
  "quantity_increment": "0.0001",
  "tick_size": "0.000001",
  "take_rate": "0.002",
  "make_rate": "0.001",
  "fee_currency": "BTC",
  "margin_trading": true,
  "max_initial_leverage": "10.00"
}

GET /api/3/public/symbol/{symbol}

Returns the data for a certain symbol.

Requires no API key Access Rights.

Response:

Name	Type	Description
`type`	String	Symbol type. Possible values: `spot`, `futures`
`contract_type`	String	Contract type. Possible values: `perpetual`, `cash_settled`
`expiry`	DateTime or null	Futures expiration date. `null` for perpetual contracts.
`underlying`	String	Futures contract underlying asset.
`base_currency`	String or null	Name (code) of base currency, (e.g., `"ETH"`). For futures contracts is `null`.
`quote_currency`	String	Name (code) of quote currency.
`status`	String	Exchange status. Possible values: `working`, `suspended`, `clearing`
`quantity_increment`	Number	Symbol quantity should be divided by this value with no remainder.
`tick_size`	Number	Symbol price should be divided by this value with no remainder.
`take_rate`	Number	Default fee rate.
`make_rate`	Number	Default fee rate for market making trades.
`fee_currency`	String	Currency in which fees are determined.
`margin_trading`	Boolean	Whether margin trading is available.
`max_initial_leverage`	Number	Optional. Maximum leverage that the user can use for margin trading. Shown only if `margin_trading` is `true`.

Tickers

Get Tickers

curl "https://api.trade.mandala.exchange/api/3/public/ticker"

Response:

{
  "ETHBTC": {
    "ask": "0.050043",
    "bid": "0.050042",
    "last": "0.050042",
    "low": "0.047052",
    "high": "0.051679",
    "open": "0.047800",
    "volume": "36456.720",
    "volume_quote": "1782.625000",
    "timestamp": "2024-04-12T14:57:19.999Z"
  }
}

GET /api/3/public/ticker

Returns ticker information.

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`symbols`	String	Optional. Comma-separated list of symbol codes.

Response:

Name	Type	Description
`ask`	Number or null	Best ask price. Can return `null` if no data.
`bid`	Number or null	Best bid price. Can return `null` if no data.
`last`	Number or null	Last trade price. Can return `null` if no data.
`low`	Number	The lowest trade price within 24 hours.
`high`	Number	The highest trade price within 24 hours.
`open`	Number or null	Last trade price 24 hours ago. Can return `null` if no data.
`volume`	Number	Total trading amount within 24 hours in base currency.
`volume_quote`	Number	Total trading amount within 24 hours in quote currency.
`timestamp`	DateTime	Last update or refresh ticker timestamp.

Get Ticker by Symbol

curl "https://api.trade.mandala.exchange/api/3/public/ticker/ETHBTC"

Response:

{
  "ask": "0.020572",
  "bid": "0.020566",
  "last": "0.020574",
  "low": "0.020388",
  "high": "0.021084",
  "open": "0.020913",
  "volume": "138444.3666",
  "volume_quote": "2853.6874972480",
  "timestamp": "2024-04-02T17:52:36.731Z"
}

GET /api/3/public/ticker/{symbol}

Returns the ticker for a certain symbol.

Requires no API key Access Rights.

Response:

Name	Type	Description
`ask`	Number or null	Best ask price. Can return `null` if no data.
`bid`	Number or null	Best bid price. Can return `null` if no data.
`last`	Number or null	Last trade price. Can return `null` if no data.
`low`	Number	The lowest trade price within 24 hours.
`high`	Number	The highest trade price within 24 hours.
`open`	Number or null	Last trade price 24 hours ago. Can return `null` if no data.
`volume`	Number	Total trading amount within 24 hours in base currency.
`volume_quote`	Number	Total trading amount within 24 hours in quote currency.
`timestamp`	DateTime	Last update or refresh ticker timestamp.

Prices

Get Prices

curl "https://api.trade.mandala.exchange/api/3/public/price/rate?from=ETH&to=BTC"

Response:

{
  "ETH":{
    "currency": "BTC",
    "price": "0.021084",
    "timestamp": "2024-04-02T17:52:36.731Z"
  }
}

GET /api/3/public/price/rate

Returns the mean of "best" bid price and "best" ask price in the order book.

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`from`	String	Source currency code.
`to`	String	Target currency code.

Response:

Name	Type	Description
`currency`	String	Quote currency code.
`price`	Number	Quotation price.
`timestamp`	DateTime	Last update or refresh price timestamp.

Get Prices History

curl "https://api.trade.mandala.exchange/api/3/public/price/history?from=ETH&to=BTC"

Response:

{
  "ETH":{
    "currency": "BTC",
    "history": [
    {
      "timestamp": "2021-07-01T20:00:00.000Z",
      "open": "0.063420",
      "close": "0.063767",
      "min": "0.063403",
      "max": "0.063782"
    }
  ]
}

GET /api/3/public/price/history

Returns quotation prices history.

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`from`	String	Source currency code.
`to`	String	Target currency code.
`until`	DateTime	Optional. Interval end value.
`since`	DateTime	Optional. Interval initial value.
`limit`	Number	Optional Default value: `1` Accepted values: `1` – `1000`
`period`	String	Optional. Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`sort`	String	Optional. Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`

Response:

Name	Type	Description
`currency`	String	Quote currency code.
`history`	History	Quotation price history entry.

History model consists of:

Name	Type	Description
`timestamp`	DateTime	Last update or refresh price timestamp.
`open`	Number	Open price.
`close`	Number	Closing price.
`min`	Number	The lowest price for the period.
`max`	Number	The highest price for the period.

Get Ticker Last Prices

curl "https://api.trade.mandala.exchange/api/3/public/price/ticker"

Response:

{
  "ETHBTC": {
    "price": "0.050042",
    "timestamp": "2024-04-12T14:57:19.999Z"
  }
}

GET /api/3/public/price/ticker

Returns tickers' last prices for all symbols.

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`symbols`	String	Optional. Comma-separated list of symbol codes.

Response:

Name	Type	Description
`price`	Number	Ticker last price.
`timestamp`	DateTime	Last update or refresh ticker timestamp.

Get Ticker Last Price by Symbol

curl "https://api.trade.mandala.exchange/api/3/public/price/ticker/ETHBTC"

Response:

{
  "price": "0.021084",
  "timestamp": "2024-04-02T17:52:36.731Z"
}

GET /api/3/public/price/ticker/{symbol}

Returns the ticker last price for a certain symbol.

Requires no API key Access Rights.

Response:

Name	Type	Description
`price`	Number	Ticker last price.
`timestamp`	DateTime	Last update or refresh ticker timestamp.

Trades

Get Trades

curl "https://api.trade.mandala.exchange/api/3/public/trades"

Response:

{
  "BTCUSDT":[
    {
      "id":3494,
      "price":"9793.94",
      "qty":"0.21469",
      "side":"sell",
      "timestamp":"2024-04-24T12:54:41.972Z"
    }
  ],
  "ETHBTC":[
    {
      "id":3495,
      "price":"0.027668",
      "qty":"0.069",
      "side":"buy",
      "timestamp":"2024-04-24T12:54:32.843Z"
    }
  ]
}

GET /api/3/public/trades

Returns trades information for all or multiple symbols.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`symbols`	String	Comma-separated list of symbol codes.
`by`	String	Filter type. Accepted values: `id`, `timestamp` Default value: `timestamp`
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`from`	DateTime or Number	Interval initial value. If sorting by `timestamp` is used, then `DateTime`; otherwise — `Number`.
`till`	DateTime or Number	Interval end value. If sorting by `timestamp` is used, then `DateTime`; otherwise — `Number`.
`limit`	Number	Default value: `10` Accepted values: `1` – `1000`

Response:

Name	Type	Description
`id`	Number	Trade identifier.
`price`	Number	Trade price.
`qty`	Number	Trade quantity.
`side`	String	Trade side. Accepted values: `sell`, `buy`
`timestamp`	DateTime	Trade timestamp.

Get Trades by Symbol

curl "https://api.trade.mandala.exchange/api/3/public/trades/ETHBTC?sort=DESC"

Response:

[
  {
    "id": 9533117,
    "price": "0.046001",
    "qty": "0.220",
    "side": "sell",
    "timestamp": "2024-04-14T12:18:40.426Z"
  },
  {
    "id": 9533116,
    "price": "0.046002",
    "qty": "0.022",
    "side": "buy",
    "timestamp": "2024-04-14T11:56:37.027Z"
  }
]

GET /api/3/public/trades/{symbol}

Returns trades information for a certain symbol.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`by`	String	Filter type. Accepted values: `id`, `timestamp` Default value: `timestamp`
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`from`	DateTime or Number	Optional. Interval initial value. If sorting by `timestamp` is used, then `DateTime`; otherwise — `Number`.
`till`	DateTime or Number	Optional. Interval end value. If sorting by `timestamp` is used, then `DateTime`; otherwise — `Number`.
`limit`	Number	Default value: `100` Accepted values: `1` – `1000`
`offset`	Number	Default value: `0` Accepted values: `0` – `100000`

Response:

Name	Type	Description
`id`	Number	Trade identifier.
`price`	Number	Trade price.
`qty`	Number	Trade quantity.
`side`	String	Trade side. Possible values: `sell`, `buy`
`timestamp`	DateTime	Trade timestamp.

Order Books

Get Order Books

curl "https://api.trade.mandala.exchange/api/3/public/orderbook"

Response:

{
  "BTCUSDT": {
    "timestamp": "2024-04-11T11:18:03.857366871Z",
    "ask": [
      [
        "9777.51",                       // Price
        "4.50579"                        // Amount
      ],
      [
        "9777.52",
        "5.79832"
      ]
    ],
    "bid": [
      [
        "9777.5",
        "0.00002"
      ],
      [
        "9776.26",
        "0.0001"
      ]
    ]
  },
  "ETHBTC": {
    "timestamp": "2024-04-11T11:18:03.790858502Z",
    "ask": [
      [
        "0.022626",
        "0.0057"
      ],
      [
        "0.022628",
        "1.4259"
      ]
    ],
    "bid": [
      [
        "0.022624",
        "0.5748"
      ],
      [
        "0.022623",
        "26.5"
      ]
    ]
  }
}

GET /api/3/public/orderbook

An Order Book is a list of buy and sell orders for a specific symbol, structured by price level.

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`depth`	Number	Optional. Order Book depth. Default value: `10` Set to `0` to view the full Order Book.
`symbols`	String	Optional. Comma-separated list of symbol codes.

Response:

Name	Type	Description
`timestamp`	DateTime	Publication timestamp.
`ask`	[]String	Ask side array of levels.
`bid`	[]String	Bid side array of levels.

Get Order Book by Symbol

curl "https://api.trade.mandala.exchange/api/3/public/orderbook/ETHBTC?volume=0.5"

Response:

{
  "timestamp": "2024-04-11T11:30:38.597950917Z",
  "ask": [
     [
        "9779.68",                       // Price
        "2.497"                          // Quantity
      ]
    ],
  "bid": [
    [
      "9779.67",
      "0.03719"
    ],
    [
      "9779.29",
      "0.171"
    ],
    [
      "9779.27",
      "0.171"
    ],
    [
      "9779.21",
      "0.171"
    ]
  ]
}

GET /api/3/public/orderbook/{symbol}

The request returns an Order Book for a certain symbol.

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`depth`	Number	Optional. Order Book depth. Default value: `100` Set to `0` to view the full Order Book.
`volume`	Number	Optional. Desired volume for market depth search.

Please note that if the volume is specified, the depth will be ignored.

Response:

Name	Type	Description
`timestamp`	DateTime	Publication timestamp.
`ask`	[]String	Ask side array of levels.
`bid`	[]String	Bid side array of levels.

Candles

Get Candles

curl "https://api.trade.mandala.exchange/api/3/public/candles"

Response:

{
  "BTCUSDT":[
    {
      "timestamp": "2021-07-01T20:00:00.000Z",
      "open": "33079.93",
      "close": "33236.53",
      "min": "33079.93",
      "max": "33295.73",
      "volume": "146.86223",
      "volume_quote": "4877838.3025063"
    }
  ],
  "ETHBTC":[
    {
      "timestamp": "2021-07-01T20:00:00.000Z",
      "open": "0.063420",
      "close": "0.063767",
      "min": "0.063403",
      "max": "0.063782",
      "volume": "866.6776",
      "volume_quote": "55.2132903904"
    }
  ]
}

GET /api/3/public/candles

Candles are used for the representation of a specific symbol as an OHLC chart.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`symbols`	String	Comma-separated list of symbol codes.
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `10` Accepted values: `1` – `1000`

Response:

Name	Type	Description
`timestamp`	DateTime	Candle timestamp.
`open`	Number	Open price.
`close`	Number	Closing price.
`min`	Number	The lowest price for the period.
`max`	Number	The highest price for the period.
`volume`	Number	Volume in base currency.
`volume_quote`	Number	Volume in quote currency.

Get Candles by Symbol

curl "https://api.trade.mandala.exchange/api/3/public/candles/ETHBTC"

Response:

[
  {
    "timestamp": "2024-04-20T20:00:00.000Z",
    "open": "0.050459",
    "close": "0.050087",
    "min": "0.050000",
    "max": "0.050511",
    "volume": "1326.628",
    "volume_quote": "66.555987736"
  },
  {
    "timestamp": "2024-04-20T20:30:00.000Z",
    "open": "0.050108",
    "close": "0.050139",
    "min": "0.050068",
    "max": "0.050223",
    "volume": "87.515",
    "volume_quote": "4.386062831"
  }
]

GET /api/3/public/candles/{symbol}

Returns candles for a certain symbol.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `100` Accepted values: `1` – `1000`
`offset`	Number	Default value: `0` Accepted values: `0` – `100000`

Response:

Name	Type	Description
`timestamp`	DateTime	Candle timestamp.
`open`	Number	Open price.
`close`	Number	Closing price.
`min`	Number	The lowest price for the period.
`max`	Number	The highest price for the period.
`volume`	Number	Volume in base currency.
`volume_quote`	Number	Volume in quote currency.

Get Converted Candles

curl "https://api.trade.mandala.exchange/api/3/public/converted/candles?target_currency=USDT"

Response:

{
  "target_currency": "USDT",
  "data": {
    "BTCUSDT": [
      {
        "timestamp": "2024-02-01T10:30:00.000Z",
        "open": "42265.17",
        "close": "42196.10",
        "min": "42182.49",
        "max": "42269.15",
        "volume": "60.88187",
        "volume_quote": "2569178.2573316"
      }
    ],
    "ETHBTC": [
      {
        "timestamp": "2024-02-01T10:30:00.000Z",
        "open": "2270.91293888",
        "close": "2268.00140384",
        "min": "2267.70603072",
        "max": "2271.50368512",
        "volume": "13.6669",
        "volume_quote": "31032.101773456736"
      }
    ]
  }
}

GET /api/3/public/converted/candles

Returns OHLCV data regarding the last price converted to the target currency for all symbols.

Candles are used for the representation of a specific symbol as an OHLC chart.

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`target_currency`	String	Target currency for conversion.
`symbols`	String	Comma-separated list of symbol codes.
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `10` Accepted values: `1` – `1000`

Response:

Name	Type	Description
`target_currency`	String	Target currency for conversion.
`data`	Map	Candles converted to the target currency.
>	[]JSON	Symbol code.
>> `timestamp`	DateTime	Candle timestamp.
>> `open`	Number	Open price.
>> `close`	Number	Closing price.
>> `min`	Number	The lowest price for the period.
>> `max`	Number	The highest price for the period.
>> `volume`	Number	Volume in base currency.
>> `volume_quote`	Number	Volume in quote currency.

Get Converted Candles by Symbol

curl "https://api.trade.mandala.exchange/api/3/public/converted/candles/ETHBTC?target_currency=USDT"

Response:

{
  "target_currency": "USDT",
  "data": [
    {
      "timestamp": "2024-02-01T10:30:00.000Z",
      "open": "2270.614518070",
      "close": "2267.450221945",
      "min": "2267.365840715",
      "max": "2271.205186680",
      "volume": "13.7525",
      "volume_quote": "31222.1126879271435"
    }
  ]
}

GET /api/3/public/converted/candles/{symbol}

Returns OHLCV data regarding the last price converted to the target currency for a symbol.

All parameters are optional.

Parameters:

Name	Type	Description
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `100` Accepted values: `1` – `1000`
`offset`	Number	Default value: `0` Accepted values: `0` – `100000`

Response:

Name	Type	Description
`target_currency`	String	Target currency for conversion.
`data`	[]JSON	Candles converted to the target currency.
> `timestamp`	DateTime	Candle timestamp.
> `open`	Number	Open price.
> `close`	Number	Closing price.
> `min`	Number	The lowest price for the period.
> `max`	Number	The highest price for the period.
> `volume`	Number	Volume in base currency.
> `volume_quote`	Number	Volume in quote currency.

Futures Info

Get Futures Information

curl "https://api.trade.mandala.exchange/api/3/public/futures/info"

Response:

{
  "UFO-1217": {
    "contract_type": "cash_settled",
    "mark_price": "1.21838",
    "index_price": "1.21838",
    "open_interest": "0",
    "indicative_settlement_price": "1.22421",
    "expiry": "2021-12-17T14:00:00.000Z",
    "timestamp": "2021-12-17T14:00:01.062Z"
  },
  "BTCUSDT_PERP": {
    "contract_type": "perpetual",
    "mark_price": "30897.68",
    "index_price": "30895.29",
    "funding_rate": "0.0001",
    "open_interest": "93.7128",
    "next_funding_time": "2021-07-21T16:00:00.000Z",
    "indicative_funding_rate": "0.0001",
    "premium_index": "0.000047541807127312",
    "avg_premium_index": "0.000087063368020112",
    "interest_rate": "0.0001",
    "timestamp": "2021-07-21T09:48:37.235Z"
  },
  "EOSETH_PERP": {
    "contract_type": "perpetual",
    "mark_price":"0.0020600",
    "index_price":"0.0020600",
    "funding_rate":"0.0001",
    "open_interest":"60.6580",
    "next_funding_time":"2024-04-25T16:00:00.000Z",
    "indicative_funding_rate":"0.0001",
    "premium_index":"0.1045547",
    "avg_premium_index":"0.1004467",
    "interest_rate": "0.0001",
    "timestamp":"2024-04-25T14:43:20.079Z"
  }
}

GET /api/3/public/futures/info

Returns futures information for all or multiple contracts.

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`symbols`	String	Optional. Comma-separated list of contract codes.

Response:

Name	Type	Description
`contract_type`	String	Contract type. Possible values: `perpetual`, `cash_settled`
`mark_price`	Number	Recent asset price adjusted by the value of fair basis.
`index_price`	Number	Average underlying asset price.
`funding_rate`	Number	Optional. Percent of the contract's mark value paid in the previous funding period. Returned only if `contract_type` is `perpetual`.
`open_interest`	Number	Total quantity of traded futures contracts.
`next_funding_time`	DateTime	Optional. Timestamp of the next funding. Returned only if `contract_type` is `perpetual`.
`indicative_funding_rate`	Number	Optional. Estimated percent of the contract's mark value to be paid after the end of the current funding period, calculated at the moment. Returned only if `contract_type` is `perpetual`.
`premium_index`	Number	Optional. Time-weighted average over premium indexes from the previous funding to the moment. Used during calculation of `indicative_funding_rate`. Returned only if `contract_type` is `perpetual`.
`avg_premium_index`	Number	Optional. Time-weighted average over premium indexes for previous funding period. Used during calculation of `funding_rate` for adjusting it to the deviation of contract market price from the mark price. Returned only if `contract_type` is `perpetual`.
`interest_rate`	Number	Optional. Contract interest rate for one funding period.
`indicative_settlement_price`	Number	Optional. Expected price of closing position on a cash settled contract. Calculated during the last 30 minutes prior to contract expiration — until that, equals to `index_price`. Returned only if `contract_type` is `cash_settled`.
`expiry`	DateTime	Optional. Contract expiration date. Returned only if `contract_type` is `cash_settled`.
`timestamp`	DateTime	Request timestamp.

Get Futures Information for Contract

curl "https://api.trade.mandala.exchange/api/3/public/futures/info/BTCUSDT_PERP"

Response:

{
  "BTCUSDT_PERP": {
    "contract_type": "perpetual",
    "mark_price": "30897.68",
    "index_price": "30895.29",
    "funding_rate": "0.0001",
    "open_interest": "93.7128",
    "next_funding_time": "2021-07-21T16:00:00.000Z",
    "indicative_funding_rate": "0.0001",
    "premium_index": "0.000047541807127312",
    "avg_premium_index": "0.000087063368020112",
    "interest_rate": "0.0001",
    "timestamp": "2021-07-21T09:48:37.235Z"
  }
}

GET /api/3/public/futures/info/{symbol}

Returns futures information for a specified contract.

Requires no API key Access Rights.

Response:

Name	Type	Description
`contract_type`	String	Contract type. Possible values: `perpetual`, `cash_settled`
`mark_price`	Number	Recent asset price adjusted by the value of fair basis.
`index_price`	Number	Average underlying asset price.
`funding_rate`	Number	Optional. Percentage of contract mark value paid after the end of current funding interval. Returned only if `contract_type` is `perpetual`.
`open_interest`	Number	Total quantity of traded futures contracts.
`next_funding_time`	DateTime	Optional. Timestamp of the next funding. Returned only if `contract_type` is `perpetual`.
`indicative_funding_rate`	Number	Optional. Estimated percent of the contract's mark value to be paid after the end of the current funding period, calculated at the moment. Returned only if `contract_type` is `perpetual`.
`premium_index`	Number	Optional. Time-weighted average over premium indexes from the previous funding to the moment. Used during calculation of `indicative_funding_rate`. Returned only if `contract_type` is `perpetual`.
`avg_premium_index`	Number	Optional. Time-weighted average over premium indexes for previous funding period. Used during calculation of `funding_rate` for adjusting it to the deviation of contract market price from the mark price. Returned only if `contract_type` is `perpetual`.
`interest_rate`	Number	Optional. Contract interest rate for one funding period.
`indicative_settlement_price`	Number	Optional. Expected price of closing position on a cash settled contract. Calculated during the last 30 minutes prior to contract expiration — until that, equals to `index_price`. Returned only if `contract_type` is `cash_settled`.
`expiry`	DateTime	Optional. Contract expiration date. Returned only if `contract_type` is `cash_settled`.
`timestamp`	DateTime	Request timestamp.

Funding History

Get Funding History

curl "https://api.trade.mandala.exchange/api/3/public/futures/history/funding"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-29T16:00:00.271Z",
      "funding_rate": "0.0001",
      "avg_premium_index": "0.000061858585213222",
      "next_funding_time": "2021-07-30T00:00:00.000Z",
      "interest_rate": "0.0001"
    },
    {
      "timestamp": "2021-07-29T08:00:00.506Z",
      "funding_rate": "0.0001",
      "avg_premium_index": "0.000064275104721498",
      "next_funding_time": "2021-07-29T16:00:00.000Z",
      "interest_rate": "0.0001"
    },
    {
      "timestamp": "2021-07-29T00:00:00.233Z",
      "funding_rate": "0.0001",
      "avg_premium_index": "0.000025719039726718",
      "next_funding_time": "2021-07-29T08:00:00.000Z",
      "interest_rate": "0.0001"
    }
  ]
}

GET /api/3/public/futures/history/funding

Returns funding history for specified perpetual contracts or all of those.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`symbols`	String	Comma-separated list of symbol codes.
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `10` Accepted values: `1` – `1000`
`offset`	Number	Default value: `0` Accepted values: `0` – `100000`

Response:

Name	Type	Description
`timestamp`	DateTime	Request timestamp.
`funding_rate`	String	Percentage of contract mark value paid after the end of current funding interval.
`avg_premium_index`	String	Time-weighted average over premium indexes for previous funding period. Used during calculation of `funding_rate` for adjusting it to the deviation of contract market price from the mark price.
`next_funding_time`	DateTime	Timestamp of the next funding.
`interest_rate`	String	Contract interest rate for one funding period.

Get Funding History for Contract

curl "https://api.trade.mandala.exchange/api/3/public/futures/history/funding/BTCUSDT_PERP"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-29T16:00:00.271Z",
      "funding_rate": "0.0001",
      "avg_premium_index": "0.000061858585213222",
      "next_funding_time": "2021-07-30T00:00:00.000Z",
      "interest_rate": "0.0001"
    },
    {
      "timestamp": "2021-07-29T08:00:00.506Z",
      "funding_rate": "0.0001",
      "avg_premium_index": "0.000064275104721498",
      "next_funding_time": "2021-07-29T16:00:00.000Z",
      "interest_rate": "0.0001"
    }
  ]
}

GET /api/3/public/futures/history/funding/{symbol}

Returns funding history for a specified perpetual contract.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `100` Accepted values: `1` – `1000`
`offset`	Number	Default value: `0` Accepted values: `0` – `100000`

Response:

Name	Type	Description
`timestamp`	DateTime	Request timestamp.
`funding_rate`	String	Percent of the contract's mark value paid in the previous funding period.
`avg_premium_index`	String	Time-weighted average over premium indexes for previous funding period. Used during calculation of `funding_rate` for adjusting it to the deviation of contract market price from the mark price.
`next_funding_time`	DateTime	Timestamp of the next funding.
`interest_rate`	String	Contract interest rate for one funding period.

Futures Index Price Candles

Get Index Price Candles

curl "https://api.trade.mandala.exchange/api/3/public/futures/candles/index_price"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-08T07:30:00.000Z",
      "open": "32414.58",
      "close": "32414.58",
      "min": "32414.58",
      "max": "32414.58"
    },
    {
      "timestamp": "2021-07-07T18:00:00.000Z",
      "open": "34748.31",
      "close": "34748.31",
      "min": "34748.31",
      "max": "34748.31"
    },
    {
      "timestamp": "2021-07-07T12:30:00.000Z",
      "open": "34777.96",
      "close": "34777.96",
      "min": "34777.96",
      "max": "34777.96"
    }
  ]
}

GET /api/3/public/futures/candles/index_price

Returns index price candles for all contracts.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`symbols`	String	Comma-separated list of contract codes.
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `10` Accepted values: `1` – `1000`

Response:

Name	Type	Description
`timestamp`	DateTime	Candle timestamp.
`open`	Number	Open index price.
`close`	Number	Closing index price.
`min`	Number	The lowest index price for the period.
`max`	Number	The highest index price for the period.

Get Index Price Candles by Contract

curl "https://api.trade.mandala.exchange/api/3/public/futures/candles/index_price/BTCUSDT_PERP"

Response:

[
  {
    "timestamp": "2021-07-08T07:30:00.000Z",
    "open": "32414.58",
    "close": "32414.58",
    "min": "32414.58",
    "max": "32414.58"
  },
  {
    "timestamp": "2021-07-07T18:00:00.000Z",
    "open": "34748.31",
    "close": "34748.31",
    "min": "34748.31",
    "max": "34748.31"
  },
  {
    "timestamp": "2021-07-07T12:30:00.000Z",
    "open": "34777.96",
    "close": "34777.96",
    "min": "34777.96",
    "max": "34777.96"
  }
]

GET /api/3/public/futures/candles/index_price/{symbol}

Returns index price candles for a certain contract.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `100` Accepted values: `1` – `1000`
`offset`	Number	Default value: `0` Accepted values: `0` – `100000`

Response:

Name	Type	Description
`timestamp`	DateTime	Candle timestamp.
`open`	Number	Open index price.
`close`	Number	Closing index price.
`min`	Number	The lowest index price for the period.
`max`	Number	The highest index price for the period.

Futures Mark Price Candles

Get Mark Price Candles

curl "https://api.trade.mandala.exchange/api/3/public/futures/candles/mark_price"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-08T07:30:00.000Z",
      "open": "32414.58",
      "close": "32414.58",
      "min": "32414.58",
      "max": "32414.58"
    },
    {
      "timestamp": "2021-07-07T18:00:00.000Z",
      "open": "34748.31",
      "close": "34748.31",
      "min": "34748.31",
      "max": "34748.31"
    },
    {
      "timestamp": "2021-07-07T12:30:00.000Z",
      "open": "34777.96",
      "close": "34777.96",
      "min": "34777.96",
      "max": "34777.96"
    }
  ]
}

GET /api/3/public/futures/candles/mark_price

Returns mark price candles for all contracts.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Limit to candles. Default value: `10` Maximum value: `1000`

Response:

Name	Type	Description
`timestamp`	DateTime	Candle timestamp.
`open`	Number	Open mark price.
`close`	Number	Closing mark price.
`min`	Number	The lowest mark price for the period.
`max`	Number	The highest mark price for the period.

Get Mark Price Candles by Contract

curl "https://api.trade.mandala.exchange/api/3/public/futures/candles/mark_price/BTCUSDT_PERP"

Response:

[
  {
    "timestamp": "2021-07-08T07:30:00.000Z",
    "open": "32414.58",
    "close": "32414.58",
    "min": "32414.58",
    "max": "32414.58"
  },
  {
    "timestamp": "2021-07-07T18:00:00.000Z",
    "open": "34748.31",
    "close": "34748.31",
    "min": "34748.31",
    "max": "34748.31"
  },
  {
    "timestamp": "2021-07-07T12:30:00.000Z",
    "open": "34777.96",
    "close": "34777.96",
    "min": "34777.96",
    "max": "34777.96"
  }
]

GET /api/3/public/futures/candles/mark_price/{symbol}

Returns mark price candles for a certain contract.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `100` Accepted values: `1` – `1000`
`offset`	Number	Default value: `0` Accepted values: `0` – `100000`

Response:

Name	Type	Description
`timestamp`	DateTime	Candle timestamp.
`open`	Number	Open mark price.
`close`	Number	Closing mark price.
`min`	Number	The lowest mark price for the period.
`max`	Number	The highest mark price for the period.

Futures Premium Index Candles

Get Premium Index Candles

curl "https://api.trade.mandala.exchange/api/3/public/futures/candles/premium_index"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-08T23:00:00.000Z",
      "open": "0.0001",
      "close": "-0.000204666639856002",
      "min": "-0.000390287528832163",
      "max": "0.000191382142641392"
    },
    {
      "timestamp": "2021-07-08T22:30:00.000Z",
      "open": "-0.000057633026633848",
      "close": "0.00006436921844495",
      "min": "-0.00060179788527768",
      "max": "0.0001"
    },
    {
      "timestamp": "2021-07-08T22:00:00.000Z",
      "open": "0.0001",
      "close": "-0.000205510656144068",
      "min": "-0.000604732863348008",
      "max": "0.0001"
    }
  ]
}

GET /api/3/public/futures/candles/premium_index

Returns premium index candles for all contracts.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`symbols`	String	Comma-separated list of contract codes.
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `10` Accepted values: `1` – `1000`

Response:

Name	Type	Description
`timestamp`	DateTime	Candle timestamp.
`open`	Number	Open premium index.
`close`	Number	Closing premium index.
`min`	Number	The lowest premium index for the period.
`max`	Number	The highest premium index for the period.

Get Premium Index Candles by Contract

curl "https://api.trade.mandala.exchange/api/3/public/futures/candles/premium_index/BTCUSDT_PERP"

Response:

[
  {
    "timestamp": "2021-07-08T23:00:00.000Z",
    "open": "0.0001",
    "close": "-0.000204666639856002",
    "min": "-0.000390287528832163",
    "max": "0.000191382142641392"
  },
  {
    "timestamp": "2021-07-08T22:30:00.000Z",
    "open": "-0.000057633026633848",
    "close": "0.00006436921844495",
    "min": "-0.00060179788527768",
    "max": "0.0001"
  },
  {
    "timestamp": "2021-07-08T22:00:00.000Z",
    "open": "0.0001",
    "close": "-0.000205510656144068",
    "min": "-0.000604732863348008",
    "max": "0.0001"
  }
]

GET /api/3/public/futures/candles/premium_index/{symbol}

Returns premium index candles for a certain contract.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `100` Accepted values: `1` – `1000`
`offset`	Number	Default value: `0` Accepted values: `0` – `100000`

Response:

Name	Type	Description
`timestamp`	DateTime	Candle timestamp.
`open`	Number	Open premium index.
`close`	Number	Closing premium index.
`min`	Number	The lowest premium index for the period.
`max`	Number	The highest premium index for the period.

Futures Open Interest Candles

Get Open Interest Candles

curl "https://api.trade.mandala.exchange/api/3/public/futures/candles/open_interest"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-22T16:30:00.000Z",
      "open": "1.06523",
      "close": "1.06523",
      "min": "1.06523",
      "max": "1.06523"
    },
    {
      "timestamp": "2021-07-22T16:00:00.000Z",
      "open": "1.06523",
      "close": "1.06523",
      "min": "1.06523",
      "max": "1.06523"
    },
    {
      "timestamp": "2021-07-22T15:30:00.000Z",
      "open": "1.06523",
      "close": "1.06523",
      "min": "1.06523",
      "max": "1.06523"
    }
  ]
}

GET /api/3/public/futures/candles/open_interest

Returns open interest candles for all contracts.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`symbols`	String	Comma-separated list of contract codes.
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `10` Accepted values: `1` – `1000`

Response:

Name	Type	Description
`timestamp`	DateTime	Candle timestamp.
`open`	Number	Opening value.
`close`	Number	Closing value.
`min`	Number	The lowest open interest for the period.
`max`	Number	The highest open interest for the period.

Get Open Interest Candles by Contract

curl "https://api.trade.mandala.exchange/api/3/public/futures/candles/open_interest/BTCUSDT_PERP"

Response:

[
  {
    "timestamp": "2021-07-22T16:30:00.000Z",
    "open": "1.06523",
    "close": "1.06523",
    "min": "1.06523",
    "max": "1.06523"
  },
  {
    "timestamp": "2021-07-22T16:00:00.000Z",
    "open": "1.06523",
    "close": "1.06523",
    "min": "1.06523",
    "max": "1.06523"
  },
  {
    "timestamp": "2021-07-22T15:30:00.000Z",
    "open": "1.06523",
    "close": "1.06523",
    "min": "1.06523",
    "max": "1.06523"
  }
]

GET /api/3/public/futures/candles/open_interest/{symbol}

Returns open interest candles for a certain contract.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name	Type	Description
`sort`	String	Sort direction. Accepted values: `ASC`, `DESC` Default value: `DESC`
`period`	String	Accepted values: `M1` (one minute), `M3`, `M5`, `M15`, `M30`, `H1` (one hour), `H4`, `D1` (one day), `D7`, `1M` (one month) Default value: `M30` (30 minutes)
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `100` Accepted values: `1` – `1000`
`offset`	Number	Default value: `0` Accepted values: `0` – `100000`

Response:

Name	Type	Description
`timestamp`	DateTime	Candle timestamp.
`open`	Number	Opening value.
`close`	Number	Closing value.
`min`	Number	The lowest open interest for the period.
`max`	Number	The highest open interest for the period.

Authentication

Public market data are available without authentication. Authentication is required for other requests.

You should create API keys on the API Settings page. You can create multiple API keys with different access rights for your applications.

Basic

curl -u "apiKey:secretKey" "https://api.trade.mandala.exchange/api/3/wallet/balance"

import requests

session = requests.session()
session.auth = ("apiKey", "secretKey")

const fetch = require('node-fetch');
const credentials = Buffer
  .from(
    'apiKey'
    + ':'
    + 'secretKey'
  )
  .toString('base64');

fetch(
  'https://api.trade.mandala.exchange/api/3/wallet/balance',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Basic ' + credentials
    }
  }
);

To authorize, place credentials to the request header. Those must be constituted of apiKey and secretKey as follows: "Basic " + apiKey + ":" + secretKey.

HS256

from base64 import b64encode
from hashlib import sha256
from hmac import HMAC
from time import time
from urllib.parse import urlsplit
from requests import Session
from requests.auth import AuthBase


class HS256(AuthBase):
    def __init__(self, api_key: str, secret_key: str, window: int = None):
        self.api_key = api_key
        self.secret_key = secret_key
        self.window = window

    def __call__(self, r):
        url = urlsplit(r.url)
        message = [r.method, url.path]
        if url.query:
            message.append('?')
            message.append(url.query)
        if r.body:
            message.append(r.body)

        timestamp = str(int(time() * 1000))
        window = str(self.window) if self.window else None
        message.append(timestamp)
        if window:
            message.append(window)

        signature = HMAC(key=self.secret_key.encode(),
                         msg=''.join(message).encode(),
                         digestmod=sha256).hexdigest()
        data = [self.api_key, signature, timestamp]
        if window:
            data.append(window)

        base64_encoded = b64encode(':'.join(data).encode()).decode()
        r.headers['Authorization'] = f'HS256 {base64_encoded}'
        return r


auth = HS256(api_key='apiKey', secret_key='secretKey')

with Session() as s:
    response = s.get('https://api.trade.mandala.exchange/api/3/wallet/balance', auth=auth)
    print(response.json())

The alternative authentication method is the HMAC signature.

To send a request, you should establish a persistent session using the credentials signed as follows:

Create an HMAC signature with secret_key as the secret key, SHA256 as the hash algorithm, and payload as the message, structured like:
<method> + <URL path> + [“?” + <query>] + [<body>] + <timestamp> + [<window>]
Add the authorization header to a request. It should have the following structure:
"HS256 " + Base64(api_key + ":" + <HMAC signature> + ":" + timestamp + [":" + window])

Spot Trading

Order Model

{
  "id": 828680665,
  "client_order_id": "f4307c6e507e49019907c917b6d7a084",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "partiallyFilled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "13.942",
  "price": "0.011384",
  "quantity_cumulative": "5.240",
  "created_at": "2024-04-16T14:18:47.321Z",
  "updated_at": "2024-04-16T14:18:47.321Z",
  "post_only": false,
  "trades": [
    {
      "id": 1361171432,
      "quantity": "5.240",
      "price": "0.011384",
      "fee": "0.001237803000",
      "taker": true,
      "timestamp": "2024-04-16T14:18:47.321Z"
    }
  ]
}

Order model consists of:

Name	Type	Description
`id`	Number	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`order_list_id`	String	Optional. Order list identifier. Returned only for an order list request.
`contingency_type`	String	Optional. Order list type. Returned only for an order list request. Possible values: `allOrNone`, `oneCancelOther`, `oneTriggerOther`, `oneTriggerOneCancelOther`
`symbol`	String	Symbol code.
`side`	String	Trade side. Possible values: `sell`, `buy`
`status`	String	Order state. Possible values: `new` — an order is placed in the order book. `suspended` — a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book. `partiallyFilled` — an order is executed, but a part of its quantity is not filled yet. `filled` — order quantity filled completely. `canceled` — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `expired` — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
`type`	String	Order type. Possible values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`
`time_in_force`	String	Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired. `GTC` — "Good-Till-Canceled" order won't be closed until it is filled. `IOC` — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled. `FOK` — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all. `Day` — keeps the order active until the end of the trading day (23:59 UTC+0). `GTD` — "Good-Till-Date" order may remain active until the time specified in `expire_time`.
`quantity`	Number	Order quantity.
`quantity_cumulative`	Number	Executed order quantity.
`price`	Number	Optional. Order price.
`stop_price`	Number	Optional. The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Optional. Date of order expiration. Specified if `time_in_force` is `GTD`.
`post_only`	Boolean	A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`original_client_order_id`	String	Optional. Identifier of replaced order.
`created_at`	DateTime	Date of order's creation.
`updated_at`	DateTime	Date of order's last update.
`trades`	[]Trade	Optional. List of trades. Never returned for an order list request.

Trade model consists of:

Name	Type	Description
`id`	Number	Trade identifier.
`quantity`	Number	Quantity of trade.
`price`	Number	Trade price.
`fee`	Number	Fee paid for trade.
`taker`	Boolean	Liquidity indicator.
`timestamp`	DateTime	Date of trade.

Get Spot Trading Balance

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/balance"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/spot/balance').json()

print(b)

Response. All currencies:

[
  {
    "currency": "ETH",
    "available": "10.000000000",
    "reserved": "0.56",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  },
  {
    "currency": "BTC",
    "available": "0.010205869",
    "reserved": "0",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  }
]

Response. One currency:

{
  "available": "10.000000000",
  "reserved": "0.56",
  "reserved_margin": "0",
  "cross_margin_reserved": "0"
}

GET /api/3/spot/balance GET /api/3/spot/balance/{currency}

Returns the user's trading balance.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	Optional. Currency filter.

Response:

Name	Type	Description
`currency`	String	Currency code.
`available`	Number	Amount available for trading or transfer to wallet.
`reserved_margin`	Number	Amount reserved for margin trading.
`cross_margin_reserved`	Number	Amount reserved for margin trading funded by a cross–margin account.
`reserved`	Number	Total amount reserved for active orders and incomplete transfers to wallet.

Get All Active Spot Orders

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/order"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/spot/order').json()

print(b)

Response:

[
  {
    "id": 840450210,
    "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.020",
    "price": "0.046001",
    "quantity_cumulative": "0.005",
    "post_only": false,
    "created_at": "2024-04-12T17:17:57.437Z",
    "updated_at": "2024-04-12T17:18:08.610Z"
  }
]

GET /api/3/spot/order

Returns a list of all active spot orders.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Optional. Parameter to filter active spot orders by symbol.

Response: array of spot orders

Get Active Spot Order

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/order/c1837634ef81472a9cd13c81e7b91401"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/spot/order/c1837634ef81472a9cd13c81e7b91401').json()

print(b)

Response:

{
  "id": 840450210,
  "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
  "symbol": "ETHBTC",
  "side": "buy",
  "status": "partiallyFilled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.020",
  "price": "0.046001",
  "quantity_cumulative": "0.005",
  "post_only": false,
  "created_at": "2024-04-12T17:17:57.437Z",
  "updated_at": "2024-04-12T17:18:08.610Z"
}

GET /api/3/spot/order/{client_order_id}

Returns an active spot order by client_order_id.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Response: spot order

Create New Spot Order

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/order" \
  -d "symbol=ETHBTC&side=sell&quantity=0.063&price=0.046016"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'symbol':'ETHBTC', 'side': 'sell', 'quantity': '0.063', 'price': '0.046016' }

r = session.post('https://api.trade.mandala.exchange/api/3/spot/order/', data = orderData)

print(r.json())

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Error response example:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

POST /api/3/spot/order

Creates a new spot order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`client_order_id`	String	Optional. If omitted, an order will be created, and it will be generated by the Server. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that. Must be from 8 to 32 long. May include Latin letters of any case, digits, and `_`, `-`. If specified and corresponds to an existing order, a request will be rejected.
`symbol`	String	Symbol code.
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Must be set to `market`, `stopMarket`, or `takeProfitMarket` if `price` was left unspecified. Accepted values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket` Default value: `limit`
`time_in_force`	String	Optional. Time in Force instruction. Accepted values: `GTC`, `IOC`, `FOK`, `Day`, `GTD` Default value: `FOK` — `type` is `market`, `stopMarket`, `takeProfitMarket`; `GTC` — `type` is `limit`, `stopLimit`, `takeProfitLimit`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	The price level that triggers order activation. Required if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Date of order expiration. Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`take_rate`	Number	Optional. Liquidity taker fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.
`make_rate`	Number	Optional. Liquidity provider fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.

Response: spot order

Price accuracy and quantity

Symbol config contains the tick_size parameter which means that price should be divided by tick_size with no remainder.
quantity should be divided by quantity_increment with no remainder.
By default, if strict_validate is not enabled, the Server rounds half down the price and quantity for tick_size and quantity_increment.

Example of ETHBTC: if tick_size is 0.000001, then price 0.046016 is valid, and 0.0460165 is invalid.

Fees

Charged fee is determined by the symbol's fee_currency. Maker-taker fees offer a transaction rebate make_rate to those who provide liquidity (a maker), while charging customers who take that liquidity take_rate (a taker).

To create buy orders, you must have sufficient balance including fees.

To create market buy orders, you must have sufficient balance including fees.

Available balance > price × quantity + price × quantity × max(take_rate, make_rate)

Order result status

For orders with time_in_force equal to IOC or FOK, the REST API returns final order status: filled or expired.

If an order can be instantly executed, then the REST API returns a status of filled or partiallyFilled in the order's info.

Create New Spot Order List

AON request:

curl \
  -X POST \
  -H 'Content-Type: application/json'\
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/order/list" \
  -d '{
        "contingency_type": "allOrNone",
        "orders": [
          {
            "symbol": "ETHBTC",
            "side": "sell",
            "quantity": "0.063",
            "type": "market",
            "time_in_force": "FOK"
          },
          {
            "symbol": "BTCUSDT",
            "side": "sell",
            "quantity": "0.057",
            "type": "market",
            "time_in_force": "FOK"
          }
        ]
      }'

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "allOrNone", "orders": [{"symbol": "ETHBTC", "side": "sell", "quantity": "0.063", "type": "market", "time_in_force": "FOK"}, {"symbol": "BTCUSDT", "side": "sell", "quantity": "0.057", "type": "market", "time_in_force": "FOK"}]}'

r = session.post('https://api.trade.mandala.exchange/api/3/spot/order/list', data = orderData, headers=headers)

print(r.json())

AON response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "filled",
    "type": "market",
    "time_in_force": "FOK",
    "quantity": "0.063",
    "price": "0.071476",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "allOrNone",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "BTCUSDT",
    "side": "sell",
    "status": "filled",
    "type": "market",
    "time_in_force": "FOK",
    "quantity": "0.057",
    "price": "43510.67",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "allOrNone",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/order/list" \
  -d '{
        "contingency_type": "oneCancelOther",
        "orders": [
          {
            "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
            "symbol": "ETHBTC",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false
          },
          {
            "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
            "symbol": "ETHBTC",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false
          }
        ]
      }'

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneCancelOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false}]}'

r = session.post('https://api.trade.mandala.exchange/api/3/spot/order/list', data = orderData, headers=headers)

print(r.json())

OCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.063",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.044016",
    "quantity_cumulative": "0.057",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/order/list" \
  -d '{
        "contingency_type": "oneTriggerOther",
        "orders": [
          {
            "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
            "symbol": "ETHBTC",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false
          },
          {
            "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
            "symbol": "ETHBTC",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false
          }
        ]
      }'

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false}]}'

r = session.post('https://api.trade.mandala.exchange/api/3/spot/order/list', data = orderData, headers=headers)

print(r.json())

OTO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.063",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.044016",
    "quantity_cumulative": "0.057",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTOCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/order/list" \
  -d '{
        "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
        "contingency_type": "oneTriggerOneCancelOther",
        "orders": [
          {
            "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
            "symbol": "ETHBTC",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false
          },
          {
            "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2",
            "symbol": "ETHBTC",
            "side": "sell",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.050000",
            "post_only": false
          },
          {
            "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
            "symbol": "ETHBTC",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false
          }
        ]
      }'

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOneCancelOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false}, {"client_order_id": "2723cdfba2d609b621d5d055e3ef9be2", "symbol": "ETHBTC", "side": "sell", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.050000", "post_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false}]}'

r = session.post('https://api.trade.mandala.exchange/api/3/spot/order/list', data = orderData, headers=headers)

print(r.json())

OTOCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.050000",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

Error response example:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

POST /api/3/spot/order/list

Creates a new spot order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`order_list_id`	String	Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to `client_order_id` of the first order in the request.
`contingency_type`	String	Order list type. Accepted values: `allOrNone` (AON) — all orders in the set should be executed within a single transaction or become expired otherwise; `oneCancelOther` (OCO) — all orders in the set should be canceled if one of them was executed; `oneTriggerOther` (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other; `oneTriggerOneCancelOther` (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
`orders`	[]Order	Orders in the list. There must be 2 or 3 orders for `allOrNone`/`oneCancelOther`/`oneTriggerOther` and 3 — for `oneTriggerOneCancelOther`. Placing any other number of orders will result in an error.

Order model consists of:

Name	Type	Description
`client_order_id`	String	Optional. Must be different from the identifiers of other orders in the list. If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`symbol`	String	Symbol code. For a `allOrNone` order list, symbol code must be unique for each order in the list. For an `oneTriggerOneCancelOther` order list, symbol code must be the same for all orders in the list (placing orders in different order books is not supported).
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Accepted values: for `allOrNone` — `limit`, `market`; for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `limit`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`; for `oneTriggerOneCancelOther` — `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`. Default value: `limit`
`time_in_force`	String	Optional (required for `allOrNone`). Time in Force instruction. Accepted values: for `allOrNone` — `FOK`; for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `GTC`, `IOC` (except `limit` orders), `FOK` (except `limit` orders), `Day`, `GTD`; for `oneTriggerOneCancelOther` — `GTC`, `IOC`, `FOK`, `Day`, `GTD`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	The price level that triggers order activation. Required if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Date of order expiration. Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`take_rate`	Number	Optional. Liquidity taker fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.
`make_rate`	Number	Optional. Liquidity provider fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.

Response: array of spot orders

Replace Spot Order

curl \
  -X PATCH \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/order/d8574207d9e3b16a4a5511753eeef174" \
  -d "quantity=0.063&price=0.046016&new_client_order_id=d8574207d9e3b16a4a5511753eeef175"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'quantity': '0.063', 'price': '0.046016', 'new_client_order_id': 'd8574207d9e3b16a4a5511753eeef175'}

r = session.patch('https://api.trade.mandala.exchange/api/3/spot/order/d8574207d9e3b16a4a5511753eeef174', data = orderData)

print(r.json())

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Error response example:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

PATCH /api/3/spot/order/{client_order_id}

Replaces a spot order

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`new_client_order_id`	String	Optional. `client_order_id` for a new order.
`quantity`	Number	Order quantity.
`price`	Number	Optional. Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	Optional. The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`strict_validate`	Boolean	Optional. Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.

Response: spot order

Cancel All Spot Orders

DELETE /api/3/spot/order

Cancels all active spot orders.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Optional. Parameter to filter active spot orders by symbol.

Response: array of spot orders

Cancel Spot Order

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/order/d8574207d9e3b16a4a5511753eeef175"

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "canceled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Example of Order not found error response:

{
  "error": {
    "code": 20002,
    "message": "Order not found",
    "description": ""
  }
}

DELETE /api/3/spot/order/{client_order_id}

Cancels a spot order.

Requires the "Place/cancel orders" API key Access Right.

Response: spot order

Get All Trading Commissions

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/fee"

Response:

[
  {
    "symbol": "BTCUSDT",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  },
  {
    "symbol": "ETHBTC",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  }
]

GET /api/3/spot/fee

Returns personal trading commission rates for all symbols.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Trading Commission

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/fee/ETHBTC"

Response:

{
  "symbol": "ETHBTC",
  "take_rate": "0.001",
  "make_rate": "-0.0001"
}

GET /api/3/spot/fee/{symbol}

Returns personal trading commission rate by symbol.

Requires the "Place/cancel orders" API key Access Right.

Spot Trading History

Spot Orders History

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/history/order?symbol=ETHBTC"

[
  {
    "id": 828680665,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.055487",
    "quantity_cumulative": "5.240",
    "created_at": "2024-04-16T14:18:47.321Z",
    "updated_at": "2024-04-19T15:23:54.876Z"
  },
  {
    "id": 828680667,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.045000",
    "quantity_cumulative": "5.240",
    "created_at": "2024-04-16T14:18:50.321Z",
    "updated_at": "2024-04-19T15:23:56.876Z"
  }
]

GET /api/3/spot/history/order

Returns all spot orders. Orders without executions are deleted after 24 hours.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`client_order_id`	String	If specified, other parameters will be ignored, including `limit` and `offset`.
`symbol`	String	Comma-separated symbol codes.
`sort`	String	Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`by`	String	Filter type. Accepted values: `timestamp`, `id` Default value: `id`
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`

Response:

Name	Type	Description
`id`	Number	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader. The order history may list several orders with the same `client_order_id`.
`symbol`	String	Symbol code.
`side`	String	Trade side. Possible values: `sell`, `buy`
`status`	String	Order state. Possible values: `new` — an order is placed in the order book. `suspended` — a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book. `partiallyFilled` — an order is executed, but a part of its quantity is not filled yet. `filled` — order quantity filled completely. `canceled` — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `expired` — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
`type`	String	Order type. Possible values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`
`time_in_force`	String	Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired. `GTC` — "Good-Till-Canceled" order won't be closed until it is filled. `IOC` — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled. `FOK` — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all. `Day` — keeps the order active until the end of the trading day (23:59 UTC+0). `GTD` — "Good-Till-Date" order may remain active until the time specified in `expire_time`.
`quantity`	Number	Order quantity.
`quantity_cumulative`	Number	Executed order quantity.
`price`	Number	Order price.
`price_average`	Number	Average price of executed order quantity.
`expire_time`	DateTime	Date of order expiration. Specified if `time_in_force` is `GTD`.
`stop_price`	Number	The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`created_at`	DateTime	Date of order's creation.
`updated_at`	DateTime	Date of order's last update.
`order_list_id`	String	Optional. Order list identifier.
`contingency_type`	String	Optional. Order list type. Possible values: `allOrNone`, `oneCancelOther`, `oneTriggerOther`, `oneTriggerOneCancelOther`

Spot Trades History

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/spot/history/trade?symbol=ETHBTC"

[
  {
    "id": 9535486,
    "order_id": 816088377,
    "client_order_id": "f8dbaab336d44d5ba3ff578098a68454",
    "symbol": "ETHBTC",
    "side": "sell",
    "quantity": "0.061",
    "price": "0.045487",
    "fee": "0.000002775",
    "timestamp": "2024-04-17T12:32:57.848Z",
    "taker": true
  },
  {
    "id": 9535437,
    "order_id": 816088021,
    "client_order_id": "27b9bfc068b44194b1f453c7af511ed6",
    "symbol": "ETHBTC",
    "side": "buy",
    "quantity": "0.038",
    "price": "0.046000",
    "fee": "-0.000000174",
    "timestamp": "2024-04-17T12:30:57.848Z",
    "taker": true
  }
]

GET /api/3/spot/history/trade

Returns the user's spot trading history.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`order_id`	String	Unique order identifier as assigned by exchange.
`symbol`	String	Comma-separated symbol codes.
`sort`	String	Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`by`	String	Filter type. Accepted values: `timestamp`, `id` Default value: `id`
`from`	DateTime or Number	Interval initial value. If sorting by `timestamp` is used, then `DateTime`; otherwise — `Number`.
`till`	DateTime or Number	Interval end value. If sorting by `timestamp` is used, then `DateTime`; otherwise — `Number`.
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`

Response:

Name	Type	Description
`id`	Number	Trade unique identifier as assigned by exchange.
`order_id`	Number	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader. The order history may list several orders with the same `client_order_id`.
`symbol`	String	Symbol code.
`side`	String	Trade side. Possible values: `sell`, `buy`
`quantity`	Number	Trade quantity.
`price`	Number	Trade price.
`fee`	Number	Trade commission. Can be negative ("rebate" — reward paid to the trader). See fee currency in the symbol config.
`timestamp`	DateTime	Trade timestamp.
`taker`	Boolean	Liquidity indicator.

Margin Trading

Margin Order Model

Margin Order:

{
  {
    "id": 828680665,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "quantity_cumulative": "5.240",
    "created_at": "2024-04-16T14:18:47.321Z",
    "updated_at": "2024-04-16T14:18:47.321Z",
    "post_only": false,
    "margin_mode": "isolated",
    "trades": [
      {
        "id": 1361171432,
        "position_id": 123,
        "quantity": "5.240",
        "price": "0.011384",
        "fee": "0.001237803000",
        "taker": true,
        "timestamp": "2024-04-16T14:18:47.321Z"
      }
    ]
  }
}

Margin order model consists of:

Name	Type	Description
`id`	Number	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`order_list_id`	String	Optional. Order list identifier.
`contingency_type`	String	Optional. Order list type. Possible values: `allOrNone`, `oneCancelOther`, `oneTriggerOther`, `oneTriggerOneCancelOther`
`symbol`	String	Symbol code.
`side`	String	Trade side. Possible values: `sell`, `buy`
`status`	String	Order state. Possible values: `new` — an order is placed in the order book. `suspended` — a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book. `partiallyFilled` — an order is executed, but a part of its quantity is not filled yet. `filled` — order quantity filled completely. `canceled` — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `expired` — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
`type`	String	Order type. Possible values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`
`time_in_force`	String	Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired. `GTC` — "Good-Till-Canceled" order won't be closed until it is filled. `IOC` — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled. `FOK` — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all. `Day` — keeps the order active until the end of the trading day (23:59 UTC+0). `GTD` — "Good-Till-Date" order may remain active until the time specified in `expire_time`.
`quantity`	Number	Order quantity.
`quantity_cumulative`	Number	Executed order quantity.
`price`	Number	Optional. Order price.
`stop_price`	Number	Optional. The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Optional. Date of order expiration. Specified if `time_in_force` is `GTD`.
`post_only`	Boolean	A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
`original_client_order_id`	String	Optional. Identifier of replaced order.
`created_at`	DateTime	Date of order's creation.
`updated_at`	DateTime	Date of order's last update.
`margin_mode`	String	Margin mode. Possible values: `isolated`, `cross`
`trades`	[]Trade	Optional. List of trades. Never returned for an order list request.

Trade model consists of:

Name	Type	Description
`id`	Number	Trade identifier.
`quantity`	Number	Quantity of trade.
`price`	Number	Trade price.
`fee`	Number	Fee paid for trade.
`position_id`	Number	Position identifier of the trade.
`taker`	Boolean	Liquidity indicator.
`timestamp`	DateTime	Date of trade.

Margin Account Model

Margin Account:

[
  {
    "symbol": "ETHUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:20:25.118Z",
    "updated_at": "2021-07-01T21:20:25.118Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.002000000000",
        "reserved_orders": "0",
        "reserved_positions": "0"
      }
    ],
    "positions": null
  },
  {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2024-04-19T17:26:10.758Z",
    "updated_at": "2021-07-01T21:20:03.64Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.097289003250",
        "reserved_orders": "0",
        "reserved_positions": "0.029557397625"
      }
    ],
    "positions": [
      {
        "id": 475421,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33304.11",
        "price_margin_call": "25395.20",
        "price_liquidation": "24884.62",
        "pnl": "0",
        "created_at": "2024-04-19T17:26:10.758Z",
        "updated_at": "2021-07-01T21:20:03.64Z"
      }
    ]
  }
]

Margin Account model consists of:

Name	Type	Description
`symbol`	String	Symbol code.
`leverage`	Number	Optional. The ratio of borrowed funds to trader's initial margin.
`type`	String	Type of margin. Possible values: `isolated`, `cross`
`created_at`	DateTime	Date of account creation.
`updated_at`	DateTime	Date of account last update.
`currencies`	[]Currency	Amount of funds on Margin Account.
`positions`	[]Position	Optional. Open positions of the Margin Account.

Currency Model

{
  "code": "USDT",
  "margin_balance": "999.9841334080000",
  "reserved_orders": "0",
  "reserved_positions": "1.605699104000"
}

Currency model consists of:

Name	Type	Description
`code`	String	Currency code.
`margin_balance`	Number	The total value of funds reserved for the position.
`reserved_orders`	Number	The value reserved for active orders in the position.
`reserved_positions`	Number	The minimum value reserved for position's executed quantity that cannot be reduced.

Position Model

{
  "id": 298724,
  "symbol": "BTCUSDT",
  "quantity": "-0.00100",
  "margin_mode": "isolated",
  "pnl": "0",
  "price_entry": "7933.30",
  "price_margin_call": "887772.25",
  "price_liquidation": "914625.61",
  "created_at": "2024-04-21T14:33:34.723Z",
  "updated_at": "2024-04-21T14:33:46.149Z"
}

Position model consists of:

Name	Type	Description
`id`	String	Position identifier.
`symbol`	String	Symbol code.
`quantity`	Number	Position quantity.
`leverage`	Number	Optional. The ratio of borrowed funds to trader's initial margin.
`margin_mode`	String	Margin mode. Possible values: `isolated`, `cross`
`pnl`	Number	Unrealized profit and loss.
`fee_cumulative`	String	Total amount of fees paid throughout the position lifetime until it is closed. This value does zero out after the position closes and does not when it flips.
`price_entry`	Number	Average weighted price of position open orders.
`price_margin_call`	Number	The mark price of margin call.
`price_liquidation`	Number	The mark price of force close.
`created_at`	DateTime	Position creation date and time.
`updated_at`	DateTime	Position last update date and time.

Get All Margin Accounts

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/account"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/margin/account').json()

print(b)

Response:

[
  {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-01T23:24:46.27Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.080816916750",
        "reserved_orders": "0.000018250000",
        "reserved_positions": "0.333861705262"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "27259.95",
        "price_liquidation": "26711.87",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-01T23:24:46.27Z"
      }
    ]
  },
  {
    "symbol": "ETHUSDT",
    "type": "cross",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:20:25.118Z",
    "updated_at": "2021-07-01T21:20:25.118Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.002000000000",
        "reserved_orders": "0",
        "reserved_positions": "0"
      }
    ],
    "positions": null
  }
]

GET /api/3/margin/account

Returns the user's all Margin Accounts' details.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Isolated Margin Account

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/account/isolated/BTCUSDT"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/margin/account/isolated/BTCUSDT').json()

print(b)

Response:

{
  "symbol": "BTCUSDT",
  "type": "isolated",
  "leverage": "12.00",
  "created_at": "2021-07-01T21:43:19.727Z",
  "updated_at": "2021-07-01T23:24:46.27Z",
  "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.080816916750",
      "reserved_orders": "0.000018250000",
      "reserved_positions": "0.333861705262"
    }
  ],
  "positions": [
    {
      "id": 485264,
      "symbol": "BTCUSDT",
      "quantity": "0.00001",
      "price_entry": "33386.18",
      "price_margin_call": "27259.95",
      "price_liquidation": "26711.87",
      "pnl": "0",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-01T23:24:46.27Z"
    }
  ]
}

GET /api/3/margin/account/isolated/{symbol}

Returns an isolated margin account details by symbol.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Cross–margin Account

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/account/cross/USDT"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/margin/account/cross/USDT').json()

print(b)

Response:

{
  "symbol": "BTCUSDT",
  "type": "cross",
  "created_at": "2021-07-01T21:43:19.727Z",
  "updated_at": "2021-07-01T23:24:46.27Z",
  "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.080816916750",
      "reserved_orders": "0.000018250000",
      "reserved_positions": "0.333861705262"
    }
  ],
  "positions": [
    {
      "id": 485264,
      "symbol": "BTCUSDT",
      "quantity": "0.00001",
      "leverage": "12.00",
      "margin_mode": "cross",
      "price_entry": "33386.18",
      "price_margin_call": "27259.95",
      "price_liquidation": "26711.87",
      "pnl": "0",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-01T23:24:46.27Z"
    }
  ]
}

GET /api/3/margin/account/cross/{currency}

Returns a cross-margin account details by currency.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create/Update Margin Account

curl \
  -X PUT \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/account/isolated/BTCUSDT" \
  -d "margin_balance=123.44"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.put('https://api.trade.mandala.exchange/api/3/margin/account/isolated/BTCUSDT', json={"margin_balance":"123.4455", "strict_validate": True}).json()

print(b)

{
  "symbol": "BTCUSDT",
  "type": "isolated",
  "leverage": "12.00",
  "created_at": "2024-04-19T17:26:10.758Z",
  "updated_at": "2021-07-01T21:20:03.64Z",
  "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.097289003250",
      "reserved_orders": "0",
      "reserved_positions": "0.029557397625"
    }
  ],
  "positions": [
    {
      "id": 475421,
      "symbol": "BTCUSDT",
      "quantity": "0.00001",
      "price_entry": "33304.11",
      "price_margin_call": "25395.20",
      "price_liquidation": "24884.62",
      "pnl": "0",
      "created_at": "2024-04-19T17:26:10.758Z",
      "updated_at": "2021-07-01T21:20:03.64Z"
    }
  ]
}

PUT /api/3/margin/account/{margin_mode}/{instrument}

Creates or updates an isolated margin account or a cross–margin account.

Setting the margin balance to zero will lead to closing a margin account and retrieval of all formerly reserved funds to the trading account.

To withdraw all funds from the margin account send a request with margin_balance equal to "0".

Returns the created/updated Margin Account details.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`margin_mode`	String	Margin mode. Accepted values: `isolated`, `cross`
`instrument`	String	Symbol or currency code for an isolated and a cross-margin position respectively.
`margin_balance`	Number	Amount of currency. `"0"` to close the margin account.
`strict_validate`	Boolean	The value indicating whether the `margin_balance` is going to be checked for correct non-exponential format and currency precision.

Close Margin Positions

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/position"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.delete('https://api.trade.mandala.exchange/api/3/margin/position').json()

print(b)

DELETE /api/3/margin/position

Closes all open positions.

Returns a list of the successfully closed margin positions.

Requires the "Place/cancel orders" API key Access Right.

Close Margin Position

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/position/isolated/BTCUSDT"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.delete('https://api.trade.mandala.exchange/api/3/margin/position/isolated/BTCUSDT', json={"price": "9800.50", "strict_validate": True}).json()

print(b)

DELETE /api/3/margin/position/{margin_mode}/{symbol}

Closes open positions by symbol.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Symbol code.
`margin_mode`	String	Margin mode. Accepted values: `isolated`, `cross`
`price`	Number	Optional. If a price is defined, then close order would be a limit order, instead, close order would be a market order.
`strict_validate`	Boolean	Optional. The value indicating whether the price is going to be checked for incrementation within the symbol’s tick size step. See the symbol's `tick_size`. Default value: `false`

Get Active Margin Orders

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/order"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/margin/order').json()

print(b)

Response:

[
  {
    "id": 840450210,
    "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.020",
    "price": "0.046001",
    "quantity_cumulative": "0.005",
    "post_only": false,
    "reduce_only": false,
    "margin_mode": "isolated",
    "created_at": "2024-04-12T17:17:57.437Z",
    "updated_at": "2024-04-12T17:18:08.610Z"
  }
]

GET /api/3/margin/order

Returns an array of active margin orders.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Optional. Parameter to filter active orders by symbol.

Get Active Margin Order

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/order/c1837634ef81472a9cd13c81e7b91401"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/margin/order/c1837634ef81472a9cd13c81e7b91401').json()

print(b)

Response:

{
  "id": 840450210,
  "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
  "symbol": "ETHBTC",
  "side": "buy",
  "status": "partiallyFilled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.020",
  "price": "0.046001",
  "quantity_cumulative": "0.005",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-12T17:17:57.437Z",
  "updated_at": "2024-04-12T17:18:08.610Z"
}

GET /api/3/margin/order/{client_order_id}

Returns an active margin order by client_order_id.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create Margin Order

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/order" \
  -d "symbol=ETHBTC&side=sell&quantity=0.063&price=0.046016"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'symbol':'ETHBTC', 'side': 'sell', 'quantity': '0.063', 'price': '0.046016'}

r = session.post('https://api.trade.mandala.exchange/api/3/margin/order', data = orderData)

print(r.json())

Response:

{
  "id": 583463871253,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Error response example:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

POST /api/3/margin/order

Requires the Margin Account for the order symbol.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`client_order_id`	String	Optional. If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`symbol`	String	Trading symbol.
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Must be set to `market`, `stopMarket`, or `takeProfitMarket` if `price` was left unspecified. Accepted values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket` Default value: `limit`
`time_in_force`	String	Optional. Time in Force instruction. Accepted values: `GTC`, `IOC`, `FOK`, `Day`, `GTD` Default value: `FOK` — `type` is `market`, `stopMarket`, `takeProfitMarket`; `GTC` — `type` is `limit`, `stopLimit`, `takeProfitLimit`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	The price level that triggers order activation. Required if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Date of order expiration. Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise. Default: `false` Conditions: `quantity` is omitted.
`margin_mode`	String	Optional. Margin mode. Accepted values: `isolated`, `cross` Default: `isolated`

Response: order

Create New Margin Order List

OCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/order/list" \
  -d '{
        "contingency_type": "oneCancelOther",
        "orders": [
          {
            "symbol": "ETHBTC",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false,
            "reduce_only": false
          },
          {
            "symbol": "ETHBTC",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false,
            "reduce_only": false
          }
        ]
      }'

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneCancelOther", "orders": [{"symbol": "ETHBTC", "side": "buy", "type": "limit","time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.trade.mandala.exchange/api/3/margin/order/list', data = orderData, headers=headers)

print(r.json())

OCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/order/list" \
  -d '{
        "contingency_type": "oneTriggerOther",
        "orders": [
            {
                "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
                "symbol": "ETHBTC",
                "side": "buy",
                "type": "limit",
                "time_in_force": "GTC",
                "quantity": "0.063",
                "price": "0.046016",
                "post_only": false,
                "reduce_only": false
            },
            {
                "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
                "symbol": "ETHBTC",
                "side": "sell",
                "type": "stopMarket",
                "time_in_force": "GTC",
                "quantity": "0.063",
                "stop_price": "0.044050",
                "post_only": false,
                "reduce_only": false
            }
        ]
      }'

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.trade.mandala.exchange/api/3/margin/order/list', data = orderData, headers=headers)

print(r.json())

OTO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.063",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.044016",
    "quantity_cumulative": "0.057",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTOCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/order/list" \
  -d '{
        "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
        "contingency_type": "oneTriggerOneCancelOther",
        "orders": [
            {
              "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
              "symbol": "ETHBTC",
              "side": "buy",
              "type": "limit",
              "time_in_force": "GTC",
              "quantity": "0.063",
              "price": "0.046016",
              "post_only": false,
              "reduce_only": false
            },
            {
              "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2", \
              "symbol": "ETHBTC",
              "side": "sell",
              "type": "limit",
              "time_in_force": "GTC",
              "quantity": "0.063",
              "price": "0.050000",
              "post_only": false,
              "reduce_only": false
            },
            {
              "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
              "symbol": "ETHBTC",
              "side": "sell",
              "type": "stopMarket",
              "time_in_force": "GTC",
              "quantity": "0.063",
              "stop_price": "0.044050",
              "post_only": false,
              "reduce_only": false
            }
        ]
      }'

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOneCancelOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"client_order_id": "2723cdfba2d609b621d5d055e3ef9be2", "symbol": "ETHBTC", "side": "sell", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.050000", "post_only": false, "reduce_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.trade.mandala.exchange/api/3/margin/order/list', data = orderData, headers=headers)

print(r.json())

OTOCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.050000",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

Error response example:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

POST /api/3/margin/order/list

Creates a new margin order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`order_list_id`	String	Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to `client_order_id` of the first order in the request.
`contingency_type`	String	Order list type. Accepted values: `oneCancelOther` (OCO) — all orders in the set should be canceled if one of them was executed; `oneTriggerOther` (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other; `oneTriggerOneCancelOther` (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
`orders`	[]Order	Orders in the list. There must be 2 or 3 orders for `allOrNone`/`oneCancelOther`/`oneTriggerOther` and 3 — for `oneTriggerOneCancelOther`. Placing any other number of orders will result in an error.

Order model consists of:

Name	Type	Description
`client_order_id`	String	Optional. Must be different from the identifiers of other orders in the list. If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`symbol`	String	Symbol code. Must be the same for all orders in an `oneTriggerOneCancelOther` order list (placing orders in different order books is not supported).
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Accepted values: for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `limit`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`; for `oneTriggerOneCancelOther` — `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`. Default value: `limit`
`time_in_force`	String	Optional. Time in Force instruction. Accepted values: for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `GTC`, `IOC` (except `limit` orders), `FOK` (except `limit` orders), `Day`, `GTD`; for `oneTriggerOneCancelOther` — `GTC`, `IOC`, `FOK`, `Day`, `GTD`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	The price level that triggers order activation. Required if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Date of order expiration. Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise. Default: `false` Conditions: `quantity` is omitted.
`margin_mode`	String	Optional. Margin mode. Accepted values: `isolated`, `cross` Default: `isolated`

Response: array of margin orders

Replace Margin Order

curl \
  -X PATCH \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/order/d8574207d9e3b16a4a5511753eeef174" \
  -d "quantity=0.063&price=0.046016&new_client_order_id=d8574207d9e3b16a4a5511753eeef175"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'quantity': '0.063', 'price': '0.046016', 'new_client_order_id': 'd8574207d9e3b16a4a5511753eeef175' }

r = session.patch('https://api.trade.mandala.exchange/api/3/margin/order/d8574207d9e3b16a4a5511753eeef174', data = orderData)

print(r.json())

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Error response example:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

PATCH /api/3/margin/order/{client_order_id}

Replaces a margin order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`new_client_order_id`	String	Optional. `client_order_id` for a new order.
`quantity`	Number	Order quantity.
`price`	Number	Optional. Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	Optional. The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`strict_validate`	Boolean	Optional. Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.

Response: margin order

Cancel All Margin Orders

DELETE /api/3/margin/order

Cancels all active margin orders.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Optional. Parameter to filter active margin orders by symbol.

Response: array of margin orders

Cancel Margin Order

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/order/d8574207d9e3b16a4a5511753eeef175"

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "canceled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.000",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T18:08:57.226Z"
}

Example of Order not found error response:

{
  "error": {
    "code": 20002,
    "message": "Order not found",
    "description": ""
  }
}

DELETE /api/3/margin/order/{client_order_id}

Cancels a margin order.

Requires the "Place/cancel orders" API key Access Right.

Response: margin order

Get Margin Position Parameters

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/config"

Response:

{
  "config": [
    {
      "symbol": "BTCUSD",
      "margin_call_leverage_mul": "1.50",
      "liquidation_leverage_mul": "2.00",
      "max_initial_leverage": "10.00",
      "margin_mode": "Isolated",
      "force_close_fee": "0.05",
      "enabled": true,
      "active": true,
      "limit_base": "50000.00",
      "limit_power": "2.2",
      "unlimited_threshold": "10.0"
    }
  ]
}

GET /api/3/margin/config

Returns information about margin position configuration.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Response:

Name	Type	Description
`symbol`	String	Trading symbol.
`margin_call_leverage_mul`	Number	Multiplier for calculating margin call leverage.
`liquidation_leverage_mul`	Number	Multiplier for calculating liquidation leverage.
`max_initial_leverage`	Number	Maximum leverage that the user can use for margin trading.
`margin_mode`	String	Mode of margin trading. Possible values: `Isolated`, `Cross`
`force_close_fee`	Number	Fee for the force closing of the position.
`enabled`	Boolean	Is margin trading available.
`active`	Boolean	Are there any positions which comply with the parameters (including not yet opened).
`limit_base`	Number	Optional. An absolute maximum that a position value can reach. Returns only if the risk limit exists.
`limit_power`	Number	Optional. Power which determines the influence of the leverage on the risk limit value. Returns only if the risk limit exists.
`unlimited_threshold`	Number	Optional. Position leverage below which the risk limit is not calculated. Returns only if the risk limit exists.

Margin Trading History

Margin Orders History

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/history/order?symbol=ETHBTC"

[
  {
    "id": 828680665,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.055487",
    "quantity_cumulative": "5.240",
    "margin_mode": "isolated",
    "created_at": "2024-04-16T14:18:47.321Z",
    "updated_at": "2024-04-19T15:23:54.876Z"
  },
  {
    "id": 828680667,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.045000",
    "quantity_cumulative": "5.240",
    "margin_mode": "isolated",
    "created_at": "2024-04-16T14:18:50.321Z",
    "updated_at": "2024-04-19T15:23:56.876Z"
  }
]

GET /api/3/margin/history/order

Returns all margin orders. Orders without executions are deleted after 24 hours.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`client_order_id`	String	If set, other parameters will be ignored, including `limit` and `offset`.
`sort`	String	Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`by`	String	Filter type. Accepted values: `timestamp`, `id` Default value: `id`
`symbol`	String	Comma-separated symbol codes.
`from`	DateTime	Interval initial value. If sorting by `timestamp` is used, then `DateTime`; otherwise `Number`.
`till`	DateTime	Interval end value. If sorting by `timestamp` is used, then `DateTime`; otherwise `Number`.
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`

Response:

Name	Type	Description
`id`	Number	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader. The order history may list several orders with the same `client_order_id`.
`symbol`	String	Symbol code.
`side`	String	Trade side. Possible values: `sell`, `buy`
`status`	String	Order state. Possible values: `new` — an order is placed in the order book. `suspended` — a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book. `partiallyFilled` — an order is executed, but a part of its quantity is not filled yet. `filled` — order quantity filled completely. `canceled` — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `expired` — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
`type`	String	Order type. Possible values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`
`time_in_force`	String	Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired. `GTC` — "Good-Till-Canceled" order won't be closed until it is filled. `IOC` — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled. `FOK` — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all. `Day` — keeps the order active until the end of the trading day (23:59 UTC+0). `GTD` — "Good-Till-Date" order may remain active until the time specified in `expire_time`.
`quantity`	Number	Order quantity.
`quantity_cumulative`	Number	Executed order quantity.
`price`	Number	Order price.
`price_average`	Number	Average price of executed order quantity.
`expire_time`	DateTime	Date of order expiration. Specified if `time_in_force` is `GTD`.
`position_id`	Number	Optional. Position identifier of the order.
`stop_price`	Number	The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`created_at`	DateTime	Date of order's creation.
`updated_at`	DateTime	Date of order's last update.
`order_list_id`	String	Optional. Order list identifier.
`contingency_type`	String	Optional. Order list type. Possible values: `oneCancelOther`, `oneTriggerOther`, `oneTriggerOneCancelOther`
`margin_mode`	String	Margin mode. Possible values: `isolated`, `cross`
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.

Margin Trades History

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/history/trade?symbol=ETHBTC"

[
  {
    "id": 9535486,
    "order_id": 816088377,
    "client_order_id": "f8dbaab336d44d5ba3ff578098a68454",
    "symbol": "ETHBTC",
    "side": "sell",
    "quantity": "0.061",
    "price": "0.045487",
    "fee": "0.000002775",
    "timestamp": "2024-04-17T12:32:57.848Z",
    "margin_mode": "isolated",
    "taker": true
  },
  {
    "id": 9535437,
    "order_id": 816088021,
    "client_order_id": "27b9bfc068b44194b1f453c7af511ed6",
    "symbol": "ETHBTC",
    "side": "buy",
    "quantity": "0.038",
    "price": "0.046000",
    "fee": "-0.000000174",
    "timestamp": "2024-04-17T12:30:57.848Z",
    "margin_mode": "isolated",
    "taker": true
  }
]

GET /api/3/margin/history/trade

Get the user's trading history.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`order_id`	Number	Unique order identifier as assigned by exchange.
`position_id`	Number	Position identifier of the taker's order in the trade.
`symbol`	String	Comma-separated symbol codes.
`sort`	String	Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`by`	String	Filter type. Accepted values: `timestamp`, `id` Default value: `id`
`from`	DateTime or Number	Interval initial value. If sorting by `timestamp` is used, then `DateTime`; otherwise `Number`.
`till`	DateTime or Number	Interval end value. If sorting by `timestamp` is used, then `DateTime`; otherwise `Number`.
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`

Response:

Name	Type	Description
`id`	String	Trade unique identifier as assigned by exchange.
`order_id`	String	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader. The order history may list several orders with the same `client_order_id`.
`symbol`	String	Trading symbol.
`side`	String	Trade side. Possible values: `sell`, `buy`
`quantity`	Number	Trade quantity.
`price`	Number	Trade price.
`fee`	Number	Trade commission. Can be negative ("rebate" — reward paid to the trader). See fee currency in the symbol config.
`timestamp`	DateTime	Trade timestamp.
`taker`	Boolean	Liquidity indicator.
`position_id`	Number	Optional. Position identifier of the taker's order in the trade.
`pnl`	Number	Optional. Realized Profit and Loss on this trade.
`liquidation`	Boolean	Optional. Whether it is a liquidation trade.
`margin_mode`	String	Margin mode. Possible values: `isolated`, `cross`

Margin Positions History

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/history/positions"

[
  {
    "id":3001,
    "entry_value": "0",
    "entry_price": "0.000",
    "avg_buy_price": "1978.057",
    "avg_sell_price": "3851.001",
    "quantity": "0",
    "margin_call_price": "0.000",
    "liquidation_price": "0.000",
    "bankruptcy_price": "0.000",
    "margin": "100.169018395350",
    "required_margin": "0",
    "orders_margin": "0.000006557500",
    "pnl": "0.187294400000",
    "leverage": "10.00",
    "margin_mode": "isolated",
    "state": "closed",
    "symbol": "ETHUSDT",
    "margin_call": false,
    "create_timestamp": 1626881592397,
    "update_timestamp": 1639570624225
  }
]

GET /api/3/margin/history/positions

Get the margin positions history.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`sort`	String	Optional. Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`from`	Number	Optional. Interval initial value in nanoseconds. Minimum value: `1`
`till`	Number	Optional. Interval end value in nanoseconds. Minimum value: `1`
`limit`	Number	Optional. Default value: `100` Maximum value: `1000`
`offset`	Number	Optional. Default value: `0` Maximum value: `100000`
`by`	String	The name of the field to order the results by (only sorting by `update_timestamp` is allowed). Accepted values: `ts`, `timestamp`

Response:

Name	Type	Description
`id`	Number	Position identifier.
`entry_value`	String	Position value in currency.
`entry_price`	String	Weighted average open price.
`avg_buy_price`	String	Weighted average buy price.
`avg_sell_price`	String	Weighted average sell price.
`quantity`	String	Position quantity.
`margin_call_price`	String	If the market is equal to or worse than this price, a margin call will be issued.
`liquidation_price`	String	The price at which the platform begins to close the position.
`bankruptcy_price`	String	The price at which the position can no longer be closed with any non-negative PnL.
`margin`	String	Amount of margin expressed in the quote currency.
`required_margin`	String	Margin reserved for close orders.
`orders_margin`	String	Margin reserved for open orders.
`pnl`	String	Unrealized Profit and Loss.
`leverage`	String	Position leverage.
`margin_mode`	String	Mode of margin trading. Possible values: `isolated`, `cross`
`state`	String	Position state. Possible values: `closed`, `active`, `liquidated`
`fee_cumulative`	String	Total amount of fees paid throughout the position lifetime until it is closed. This value does zero out after the position closes and does not when it flips.
`symbol`	String	Symbol code.
`margin_call`	Boolean	Flag indicating the position is close to the liquidation, and increased margin may prevent it from happening.
`create_timestamp`	Number	Timestamp of position creation in nanoseconds.
`update_timestamp`	Number	Timestamp of position update in nanoseconds.

Margin Clearing Details

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/margin/history/clearing"

[
  {
    "timestamp": 1646524800267,
    "position_id": 972,
    "position_quantity": "0.00010",
    "position_entry_value": "5.126379000000",
    "type": "interest",
    "symbol": "BTCUSDT",
    "currency": "USD",
    "amount": "0.011819526000",
    "rate": "0.0001",
    "debt_delta": "0"
  }
]

GET /api/3/margin/history/clearing

Get clearing details.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`currency`	String	Quote currency code.
`sort`	String	Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`from`	Number	Interval initial value in nanoseconds. Minimum value: `1`
`till`	Number	Interval end value in nanoseconds. Minimum value: `1`
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`

Response:

Name	Type	Description
`timestamp`	Number	Transfer timestamp in nanoseconds.
`position_id`	Number	Optional. Position identifier.
`position_quantity`	Number	Optional. Position quantity.
`position_entry_value`	Number	Optional. Position value in currency.
`type`	String	Transfer type. Possible values: `interest`
`symbol`	String	Optional. Symbol code.
`currency`	String	Transfer currency.
`amount`	Number	Transfer amount.
`rate`	Number	Optional. Interest rate. It is `null` if the withdrawal occurred during a close trade (debt collection).
`trade_id`	Number	Optional. Trade identifier. Applicable if the withdrawal occurred during a close trade (debt collection).
`debt_delta`	Number	Optional. Debt value. Returned if a user was unable to pay interest during the last withdrawal but had a positive UPnL.

Futures Trading

Futures Order Model

Futures Order:

{
  {
    "id": 828680665,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "BTCUSDT_PERP",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "quantity_cumulative": "5.240",
    "created_at": "2024-04-16T14:18:47.321Z",
    "updated_at": "2024-04-16T14:18:47.321Z",
    "post_only": false,
    "margin_mode": "isolated",
    "trades": [
      {
        "id": 1361171432,
        "position_id": 123,
        "quantity": "5.240",
        "price": "0.011384",
        "fee": "0.001237803000",
        "taker": true,
        "timestamp": "2024-04-16T14:18:47.321Z"
      }
    ]
  }
}

Margin order model consists of:

Name	Type	Description
`id`	Number	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`order_list_id`	String	Optional. Order list identifier.
`contingency_type`	String	Optional. Order list type. Possible values: `allOrNone`, `oneCancelOther`, `oneTriggerOneCancelOther`
`symbol`	String	Contract code.
`side`	String	Trade side. Possible values: `sell`, `buy`
`status`	String	Order state. Possible values: `new` — an order is placed in the order book. `suspended` — a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book. `partiallyFilled` — an order is executed, but a part of its quantity is not filled yet. `filled` — order quantity filled completely. `canceled` — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `expired` — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
`type`	String	Order type. Possible values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`
`time_in_force`	String	Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired. `GTC` — "Good-Till-Canceled" order won't be closed until it is filled. `IOC` — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled. `FOK` — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all. `Day` — keeps the order active until the end of the trading day (23:59 UTC+0). `GTD` — "Good-Till-Date" order may remain active until the time specified in `expire_time`.
`quantity`	Number	Order quantity.
`quantity_cumulative`	Number	Executed order quantity.
`price`	Number	Optional. Order price.
`stop_price`	Number	Optional. The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Optional. Date of order expiration. Specified if `time_in_force` is `GTD`.
`post_only`	Boolean	A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise. Default: `false` Conditions: `quantity` is omitted.
`original_client_order_id`	String	Optional. Identifier of replaced order.
`created_at`	DateTime	Date of order's creation.
`updated_at`	DateTime	Date of order's last update.
`margin_mode`	String	Margin mode. Possible values: `isolated`, `cross`
`trades`	[]Trade	Optional. List of trades. Never returned for an order list request.

Trade model consists of:

Name	Type	Description
`id`	Number	Trade identifier.
`quantity`	Number	Quantity of trade.
`price`	Number	Trade price.
`fee`	Number	Fee paid for trade.
`position_id`	Number	Position identifier of the trade.
`taker`	Boolean	Liquidity indicator.
`timestamp`	DateTime	Date of trade.

Futures Margin Account Model

Futures Margin Account:

[
  {
    "symbol": "ETHUSDT_PERP",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:20:25.118Z",
    "updated_at": "2021-07-01T21:20:25.118Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.002000000000",
        "reserved_orders": "0",
        "reserved_positions": "0"
      }
    ],
    "positions": null
  },
  {
    "symbol": "BTCUSDT_PERP",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2024-04-19T17:26:10.758Z",
    "updated_at": "2021-07-01T21:20:03.64Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.097289003250",
        "reserved_orders": "0",
        "reserved_positions": "0.029557397625"
      }
    ],
    "positions": [
      {
        "id": 475421,
        "symbol": "BTCUSDT_PERP",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33304.11",
        "price_margin_call": "25395.20",
        "price_liquidation": "24884.62",
        "pnl": "0",
        "created_at": "2024-04-19T17:26:10.758Z",
        "updated_at": "2021-07-01T21:20:03.64Z"
      }
    ]
  }
]

Margin Account model consists of:

Name	Type	Description
`symbol`	String	Contract code.
`leverage`	Number	Optional. The ratio of borrowed funds to trader's initial margin.
`type`	String	Type of margin. Possible values: `isolated`, `cross`
`created_at`	DateTime	Date of account creation.
`updated_at`	DateTime	Date of account last update.
`currencies`	[]Currency	Amount of funds on Margin Account.
`positions`	[]Position	Optional. Open positions of the Margin Account.

Currency Model

{
  "code": "USDT",
  "margin_balance": "999.9841334080000",
  "reserved_orders": "0",
  "reserved_positions": "1.605699104000"
}

Currency model consists of:

Name	Type	Description
`code`	String	Currency code.
`margin_balance`	Number	The total value of funds reserved for the position.
`reserved_orders`	Number	The value reserved for active orders in the position.
`reserved_positions`	Number	The minimum value reserved for position's executed quantity that cannot be reduced.

Position Model

{
  "id": 298724,
  "symbol": "BTCUSDT_PERP",
  "quantity": "-0.00100",
  "leverage": "12.00",
  "margin_mode": "isolated",
  "pnl": "0",
  "price_entry": "7933.30",
  "price_margin_call": "887772.25",
  "price_liquidation": "914625.61",
  "created_at": "2024-04-21T14:33:34.723Z",
  "updated_at": "2024-04-21T14:33:46.149Z"
}

Position model consists of:

Name	Type	Description
`id`	String	Position identifier.
`symbol`	String	Contract code.
`quantity`	Number	Position quantity.
`leverage`	Number	The ratio of borrowed funds to trader's initial margin.
`margin_mode`	String	Margin mode. Possible values: `isolated`, `cross`
`pnl`	Number	Unrealized profit and loss.
`fee_cumulative`	String	Total amount of fees paid throughout the position lifetime until it is closed. This value does zero out after the position closes and does not when it flips.
`price_entry`	Number	Average weighted price of position open orders.
`price_margin_call`	Number	The mark price of margin call.
`price_liquidation`	Number	The mark price of force close.
`created_at`	DateTime	Position creation date and time.
`updated_at`	DateTime	Position last update date and time.

Get Trading Balance

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/balance"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/futures/balance').json()

print(b)

Response. All currencies:

[
  {
    "currency": "ETH",
    "available": "10.000000000",
    "reserved": "0.56",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  },
  {
    "currency": "BTC",
    "available": "0.010205869",
    "reserved": "0",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  }
]

Response. One currency:

{
  "available": "10.000000000",
  "reserved": "0.56",
  "reserved_margin": "0",
  "cross_margin_reserved": "0"
}

GET /api/3/futures/balance GET /api/3/futures/balance/{currency}

Returns the user's trading balance.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	Optional. Currency filter.

Response:

Name	Type	Description
`currency`	String	Currency code.
`available`	Number	Amount available for trading or transfer to wallet.
`reserved`	Number	Total amount reserved for active orders, incomplete transfers to wallet, and margin trading.
`reserved_margin`	Number	Amount reserved for margin trading funded by an isolated margin account.
`cross_margin_reserved`	Number	Amount reserved for margin trading funded by a cross–margin account.

Get Futures Margin Accounts

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/account"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/futures/account').json()

print(b)

Response:

[
  {
    "symbol": "BTCUSDT_PERP",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-01T23:24:46.27Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.080816916750",
        "reserved_orders": "0.000018250000",
        "reserved_positions": "0.333861705262"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT_PERP",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "27259.95",
        "price_liquidation": "26711.87",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-01T23:24:46.27Z"
      }
    ]
  }
]

GET /api/3/futures/account

Returns all user's Futures Margin Accounts.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Futures Margin Account

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/account/isolated/BTCUSDT_PERP"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/futures/account/isolated/BTCUSDT_PERP').json()

print(b)

GET /api/3/futures/account/isolated/{symbol}

Returns Futures Margin Account details by symbol.

A full margin model description can be found in the "Margin Account Model" section.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Futures Cross–margin Account

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/account/cross/USDT"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/futures/account/cross/USDT').json()

print(b)

Response:

{
  "symbol": "BTCUSDT_PERP",
  "type": "cross",
  "created_at": "2021-07-01T21:43:19.727Z",
  "updated_at": "2021-07-01T23:24:46.27Z",
  "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.080816916750",
      "reserved_orders": "0.000018250000",
      "reserved_positions": "0.333861705262"
    }
  ],
  "positions": [
    {
      "id": 485264,
      "symbol": "BTCUSDT_PERP",
      "quantity": "0.00001",
      "leverage": "12.00",
      "margin_mode": "cross",
      "price_entry": "33386.18",
      "price_margin_call": "27259.95",
      "price_liquidation": "26711.87",
      "pnl": "0",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-01T23:24:46.27Z"
    }
  ]
}

GET /api/3/futures/account/cross/{currency}

Returns a cross-margin account details by currency.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create/Update Margin Account

curl \
  -X PUT \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/account/isolated/BTCUSDT_PERP" \
  -d "margin_balance=123.44&leverage=100"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.put('https://api.trade.mandala.exchange/api/3/futures/account/isolated/BTCUSDT_PERP', json={"margin_balance":"123.4455", "leverage": "100", "strict_validate": True}).json()
print(b)

Response:

{
  "symbol": "BTCUSDT_PERP",
  "type": "isolated",
  "leverage": "100.00",
  "created_at": "2021-07-01T21:43:19.727Z",
  "updated_at": "2021-07-01T23:24:46.27Z",
  "currencies": [
  {
    "code": "USDT",
    "margin_balance": "123.4455",
    "reserved_orders": "0",
    "reserved_positions": "0"
  }
  ],
  "positions": null
}

PUT /api/3/futures/account/{margin_mode}/{symbol}

Creates or updates a margin account. Setting margin balance to zero will lead to closing the margin account and retrieval all formerly reserved funds to the trading account.

Returns margin account details.

To withdraw all funds from the margin account send a request with margin_balance equal to "0".

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`margin_mode`	String	Margin mode. Accepted values: `isolated`, `cross`
`margin_balance`	Number	Amount of currency reserved.
`leverage`	Number	Optional. User leverage. Required if the balance of the isolated margin account is equal to zero. Minimum value: `"1"` Maximum value: `"1000"`
`strict_validate`	Boolean	Optional. The value indicating whether the `margin_balance` is going to be checked for correct non-exponential format and currency precision.

Close All Futures Margin Positions

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/position"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.delete('https://api.trade.mandala.exchange/api/3/futures/position').json()

print(b)

DELETE /api/3/futures/position

Closes all open positions.

Returns a list of the successfully closed margin positions.

Requires the "Place/cancel orders" API key Access Right.

Close Futures Margin Position

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/position/isolated/BTCUSDT_PERP"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.delete('https://api.trade.mandala.exchange/api/3/futures/position/isolated/BTCUSDT_PERP', json={"price": "9800.50", "strict_validate": True}).json()
print(b)

DELETE /api/3/futures/position/{margin_mode}/{symbol}

Closes open position by contract.

Returns a list of the successfully closed margin positions.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Contract code.
`margin_mode`	String	Margin mode. Accepted values: `isolated`, `cross`
`price`	Number	Optional. If a price is defined, then close order would be a limit order with the specified price, instead, close order would be a market order with the market price.
`strict_validate`	Boolean	Optional. The value indicating whether the price is going to be checked for incrementation within the symbol’s tick size step. See the symbol's `tick_size`. Default value: `false`

Get Active Futures Orders

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/order"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/futures/order').json()

print(b)

Response:

[
  {
    "id": 840450210,
    "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.020",
    "price": "0.046001",
    "quantity_cumulative": "0.005",
    "post_only": false,
    "reduce_only": false,
    "margin_mode": "isolated",
    "created_at": "2024-04-12T16:16:30.430Z",
    "updated_at": "2024-04-12T16:17:15.620Z"
  }
]

GET /api/3/futures/order

Returns an array of active futures orders.

A full order description can be found in the "Margin Order Model" section.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Optional. Contract code.

Response: array of orders

Get Active Futures Order

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/order/c1837634ef81472a9cd13c81e7b91401"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.trade.mandala.exchange/api/3/futures/order/c1837634ef81472a9cd13c81e7b91401').json()

print(b)

Response:

{
  "id": 840450210,
  "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
  "symbol": "ETHBTC_PERP",
  "side": "buy",
  "status": "partiallyFilled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.020",
  "price": "0.046001",
  "quantity_cumulative": "0.005",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-12T16:16:30.430Z",
  "updated_at": "2024-04-12T16:17:15.620Z"
}

GET /api/3/futures/order/{client_order_id}

Returns an active order by client_order_id.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create Futures Order

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/order" \
  -d "symbol=ETHBTC_PERP&side=sell&quantity=0.063&price=0.046016"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'symbol':'ETHBTC_PERP', 'side': 'sell', 'quantity': '0.063', 'price': '0.046016' }

r = session.post('https://api.trade.mandala.exchange/api/3/futures/order', data = orderData)

print(r.json())

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC_PERP",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Error response example:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

POST /api/3/futures/order

Creates a new futures order.

A full order description can be found in the "Margin Order Model" subsection.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`client_order_id`	String	Optional. If omitted, an order will be created, and it will be generated by the Server. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that. Must be from 8 to 32 characters long. May include Latin letters of any case, digits, and `_`, `-`. If specified and corresponds to an existing order, a request will be rejected.
`symbol`	String	Contract code.
`side`	String	Trade side. Possible values: `sell`, `buy`
`type`	String	Optional. Order type. Possible values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket` Default value: `limit`
`time_in_force`	String	Optional. Time in Force instruction. Possible values: `GTC`, `IOC`, `FOK`, `Day`, `GTD` Default value: `FOK` — `type` is `market`, `stopMarket`, `takeProfitMarket`; `GTC` — `type` is `limit`, `stopLimit`, `takeProfitLimit`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	The price level that triggers order activation. Required if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`.
`expire_time`	DateTime	Date of order expiration. Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`margin_mode`	String	Optional. Margin mode. Accepted values: `isolated`, `cross` Default: `isolated`
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise. Default: `false` Conditions: `quantity` is omitted.

Response: futures order

Create New Futures Order List

OCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/order/list" \
  -d '{
        "contingency_type": "oneCancelOther",
        "orders": [
          {
            "symbol": "ETHBTC_PERP",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false,
            "reduce_only": false
          },
          {
            "symbol": "ETHBTC_PERP",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false,
            "reduce_only": false
          }
        ]
      }'

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneCancelOther", "orders": [{"symbol": "ETHBTC_PERP", "side": "buy", "type": "limit","time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"symbol": "ETHBTC_PERP", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.trade.mandala.exchange/api/3/futures/order/list', data = orderData, headers=headers)

print(r.json())

OCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/order/list" \
  -d '{
        "contingency_type": "oneTriggerOther",
        "orders": [
          {
            "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
            "symbol": "ETHBTC_PERP",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false,
            "reduce_only": false
          },
          {
            "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
            "symbol": "ETHBTC_PERP",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false,
            "reduce_only": false
          }
        ]
      }'

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC_PERP", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC_PERP", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.trade.mandala.exchange/api/3/futures/order/list', data = orderData, headers=headers)

print(r.json())

OTO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.063",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.044016",
    "quantity_cumulative": "0.057",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTOCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/order/list" \
  -d '{
        "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
        "contingency_type": "oneTriggerOneCancelOther",
        "orders": [
          {
            "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
            "symbol": "ETHBTC_PERP",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false,
            "reduce_only": false
          },
          {
            "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2",
            "symbol": "ETHBTC_PERP",
            "side": "sell",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.050000",
            "post_only": false,
            "reduce_only": false
          },
          {
            "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
            "symbol": "ETHBTC_PERP",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false,
            "reduce_only": false
          }
        ]
      }'

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOneCancelOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC_PERP", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"client_order_id": "2723cdfba2d609b621d5d055e3ef9be2", "symbol": "ETHBTC_PERP", "side": "sell", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.050000", "post_only": false, "reduce_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC_PERP", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.trade.mandala.exchange/api/3/futures/order/list', data = orderData, headers=headers)

print(r.json())

OTOCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "suspended",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.050000",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

Error response example:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

POST /api/3/futures/order/list

Creates a new futures order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`order_list_id`	String	Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to `client_order_id` of the first order in the request.
`contingency_type`	String	Order list type. Accepted values: `oneCancelOther` (OCO) — all orders in the set should be canceled if one of them was executed; `oneTriggerOther` (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other; `oneTriggerOneCancelOther` (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
`orders`	[]Order	Orders in the list. There must be 2 or 3 orders for `allOrNone`/`oneCancelOther`/`oneTriggerOther` and 3 — for `oneTriggerOneCancelOther`. Placing any other number of orders will result in an error.

Order model consists of:

Name	Type	Description
`client_order_id`	String	Optional. Must be different from the identifiers of other orders in the list. If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`symbol`	String	Symbol code. Must be the same for all orders in an `oneTriggerOneCancelOther` order list (placing orders in different order books is not supported).
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Accepted values: for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `limit`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`; for `oneTriggerOneCancelOther` — `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`. Default value: `limit`
`time_in_force`	String	Optional. Time in Force instruction. Accepted values: for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `GTC`, `IOC` (except `limit` orders), `FOK` (except `limit` orders), `Day`, `GTD`; for `oneTriggerOneCancelOther` — `GTC`, `IOC`, `FOK`, `Day`, `GTD`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	The price level that triggers order activation. Required if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Date of order expiration. Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`margin_mode`	String	Optional. Margin mode. Accepted values: `isolated`, `cross` Default: `isolated`
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise. Default: `false` Conditions: `quantity` is omitted.

Response: array of futures orders

Cancel Futures Orders

DELETE /api/3/futures/order

Cancels all active futures orders or all active futures orders for the specified contract.

Returns a list of canceled futures orders.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Optional. Parameter to filter active futures orders by contract code.

Replace Futures Order

curl \
  -X PATCH \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/order/d8574207d9e3b16a4a5511753eeef174" \
  -d "quantity=0.063&price=0.046016&new_client_order_id=d8574207d9e3b16a4a5511753eeef175"

import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'quantity': '0.063', 'price': '0.046016', 'new_client_order_id': 'd8574207d9e3b16a4a5511753eeef175'}

r = session.patch('https://api.trade.mandala.exchange/api/3/futures/order/d8574207d9e3b16a4a5511753eeef174', data = orderData)

print(r.json())

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC_PERP",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-12T16:16:30.430Z",
  "updated_at": "2024-04-12T16:17:15.620Z"
}

Error response example:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

PATCH /api/3/futures/order/{client_order_id}

Replaces a futures order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`new_client_order_id`	String	Optional. Unique order identifier given by the trader or the system.
`quantity`	Number	Order quantity.
`price`	Number	Optional. Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	Optional. The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`strict_validate`	Boolean	Optional. Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.

Response: futures order

Cancel Futures Order

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/order/d8574207d9e3b16a4a5511753eeef175"

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC_PERP",
  "side": "sell",
  "status": "canceled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.000",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T18:08:57.226Z"
}

Example of Order not found error response:

{
  "error": {
    "code": 20002,
    "message": "Order not found",
    "description": ""
  }
}

DELETE /api/3/futures/order/{client_order_id}

Returns the successfully canceled futures order.

Requires the "Place/cancel orders" API key Access Right.

Response: futures order

Get Futures Position Parameters

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/config"

Response:

{
  "config": [
    {
      "symbol": "BTCUSD_PERP",
      "margin_call_leverage_mul": "1.20",
      "liquidation_leverage_mul": "2.00",
      "max_initial_leverage": "100.00",
      "margin_mode": "Isolated",
      "force_close_fee": "0.001",
      "enabled": true,
      "active": false,
      "limit_base": "5000000.000000000000",
      "limit_power": "1.25",
      "unlimited_threshold": "2.00"
    }
  ]
}

GET /api/3/futures/config

Returns information about futures position configuration.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Response:

Name	Type	Description
`symbol`	String	Trading symbol.
`margin_call_leverage_mul`	Number	Multiplier applied to a requested leverage for calculating margin call price.
`liquidation_leverage_mul`	Number	Multiplier applied to a requested leverage for calculating liquidation price.
`max_initial_leverage`	Number	Maximum leverage that the user can use for margin trading.
`margin_mode`	String	Mode of margin trading. Possible values: `Isolated`, `Cross`
`force_close_fee`	Number	Fee for the force closing of the position.
`enabled`	Boolean	Is margin trading available.
`active`	Boolean	Are there any positions which comply with the parameters (including not yet opened).
`limit_base`	Number	Optional. An absolute maximum that a position value can reach. Returns only if the risk limit exists.
`limit_power`	Number	Optional. Power which determines the influence of the leverage on the risk limit value. Returns only if the risk limit exists.
`unlimited_threshold`	Number	Optional. Position leverage below which the risk limit is not calculated. Returns only if the risk limit exists.

Risk Limits

Risk limits are a set of upper boundaries to the position value regarding the chosen leverage. Thus, each user leverage has its individual limit calculated according to the configuration as follows:

Risk limit = limit_base / ( L ^ limit_power ),

where L is a leverage set by the user.

Note that the resulting limit hedges the value of existing open orders (considering unfilled portion of their quantity) added to the position market value and the value of a new order.

Get All Trading Commissions

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/fee"

Response:

[
  {
    "symbol": "BTCUSDT_PERP",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  },
  {
    "symbol": "ETHBTC_PERP",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  }
]

GET /api/3/futures/fee

Returns personal trading commission rates for all contracts.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Trading Commission

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/fee/ETHBTC_PERP"

Response:

{
  "symbol": "ETHBTC_PERP",
  "take_rate": "0.001",
  "make_rate": "-0.0001"
}

GET /api/3/futures/fee/{symbol}

Returns personal trading commission rate by contract.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Futures Trading History

Futures Orders History

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/history/order?symbol=ETHBTC_PERP"

[
  {
    "id": 828680665,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.055487",
    "quantity_cumulative": "5.240",
    "margin_mode": "isolated",
    "created_at": "2024-04-16T14:18:47.321Z",
    "updated_at": "2024-04-19T15:23:54.876Z"
  },
  {
    "id": 828680667,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.045000",
    "quantity_cumulative": "5.240",
    "margin_mode": "isolated",
    "created_at": "2024-04-16T14:18:50.321Z",
    "updated_at": "2024-04-19T15:23:56.876Z"
  }
]

GET /api/3/futures/history/order

Returns all futures orders. Orders without executions are deleted after 24 hours.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`client_order_id`	String	If set, other parameters will be ignored, including `limit` and `offset`.
`symbol`	String	Comma-separated symbol codes.
`from`	DateTime	Interval initial value.
`till`	DateTime	Interval end value.
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`

Response:

Name	Type	Description
`id`	Number	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader. The order history may list several orders with the same `client_order_id`.
`symbol`	String	Symbol code.
`side`	String	Trade side. Possible values: `sell`, `buy`
`status`	String	Order state. Possible values: `new` — an order is placed in the order book. `suspended` — a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book. `partiallyFilled` — an order is executed, but a part of its quantity is not filled yet. `filled` — order quantity filled completely. `canceled` — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `expired` — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
`type`	String	Order type. Possible values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`
`time_in_force`	String	Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired. `GTC` — "Good-Till-Canceled" order won't be closed until it is filled. `IOC` — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled. `FOK` — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all. `Day` — keeps the order active until the end of the trading day (23:59 UTC+0). `GTD` — "Good-Till-Date" order may remain active until the time specified in `expire_time`.
`quantity`	Number	Order quantity.
`quantity_cumulative`	Number	Executed order quantity.
`price`	Number	Order price.
`price_average`	Number	Average price of executed order quantity.
`expire_time`	DateTime	Date of order expiration. Specified if `time_in_force` is `GTD`.
`position_id`	Number	Optional. Position identifier of the order.
`stop_price`	Number	The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`.
`created_at`	DateTime	Date of order's creation.
`updated_at`	DateTime	Date of order's last update.
`order_list_id`	String	Optional. Order list identifier.
`contingency_type`	String	Optional. Order list type. Possible values: `oneCancelOther`, `oneTriggerOther`, `oneTriggerOneCancelOther`
`margin_mode`	String	Margin mode. Possible values: `isolated`, `cross`
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.

Futures Trades History

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/history/trade?symbol=ETHBTC_PERP"

[
  {
    "id": 9535486,
    "order_id": 816088377,
    "client_order_id": "f8dbaab336d44d5ba3ff578098a68454",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "quantity": "0.061",
    "price": "0.045487",
    "fee": "0.000002775",
    "timestamp": "2024-04-17T12:32:57.848Z",
    "margin_mode": "isolated",
    "taker": true
  },
  {
    "id": 9535437,
    "order_id": 816088021,
    "client_order_id": "27b9bfc068b44194b1f453c7af511ed6",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "quantity": "0.038",
    "price": "0.046000",
    "fee": "-0.000000174",
    "timestamp": "2024-04-17T12:30:57.848Z",
    "margin_mode": "isolated",
    "taker": true
  }
]

GET /api/3/futures/history/trade

Get the user's futures trading history.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`order_id`	Number	Unique order identifier as assigned by exchange.
`position_id`	Number	Position identifier of the taker's order in the trade.
`symbol`	String	Comma-separated symbol codes.
`sort`	String	Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`by`	String	Filter type. Accepted values: `timestamp`, `id` Default value: `id`
`from`	DateTime or Number	Interval initial value. If sorting by `timestamp` is used, then `DateTime`; otherwise `Number`.
`till`	DateTime or Number	Interval end value. If sorting by `timestamp` is used, then `DateTime`; otherwise `Number`.
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`

Response:

Name	Type	Description
`id`	String	Trade unique identifier as assigned by exchange.
`order_id`	String	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader. The order history may list several orders with the same `client_order_id`.
`symbol`	String	Contract code.
`side`	String	Trade side. Possible values: `sell`, `buy`
`quantity`	Number	Trade quantity.
`price`	Number	Trade price.
`fee`	Number	Trade commission. Can be negative ("rebate" — reward paid to the trader). See fee currency in the symbol config.
`timestamp`	DateTime	Trade timestamp.
`taker`	Boolean	Liquidity indicator.
`position_id`	Number	Optional. Position identifier of the taker's order in the trade.
`pnl`	Number	Optional. Realized Profit and Loss on this trade
`liquidation`	Boolean	Optional. Whether it is a liquidation trade.
`margin_mode`	String	Margin mode. Possible values: `isolated`, `cross`

Futures Positions History

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/history/positions"

[
  {
    "id":3001,
    "entry_value": "0",
    "entry_price": "0.000",
    "avg_buy_price": "1978.057",
    "avg_sell_price": "3851.001",
    "quantity": "0",
    "margin_call_price": "0.000",
    "liquidation_price": "0.000",
    "bankruptcy_price": "0.000",
    "margin": "100.169018395350",
    "required_margin": "0",
    "orders_margin": "0.000006557500",
    "pnl": "0.187294400000",
    "leverage": "10.00",
    "margin_mode": "isolated",
    "state": "closed",
    "symbol": "ETHUSDT_PERP",
    "margin_call": false,
    "create_timestamp": 1626881592397,
    "update_timestamp": 1639570624225
  }
]

GET /api/3/futures/history/positions

Get the futures positions history.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`sort`	String	Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`from`	Number	Interval initial value in nanoseconds. Minimum value: `1`
`till`	Number	Interval end value in nanoseconds. Minimum value: `1`
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`
`by`	String	The name of the field to order the results by (only sorting by `update_timestamp` is allowed). Accepted values: `ts`, `timestamp`

Response:

Name	Type	Description
`id`	Number	Position identifier.
`entry_value`	Number	Position value in currency.
`entry_price`	Number	Weighted average open price.
`avg_buy_price`	Number	Weighted average buy price.
`avg_sell_price`	Number	Weighted average sell price.
`quantity`	Number	Position quantity.
`margin_call_price`	Number	If the market is equal to or worse than this price, a margin call will be issued.
`liquidation_price`	Number	The price at which the platform begins to close the position.
`bankruptcy_price`	Number	The price at which the position can no longer be closed with any non-negative PnL.
`margin`	Number	Amount of margin expressed in the quote currency.
`required_margin`	Number	Margin reserved for close orders.
`orders_margin`	Number	Margin reserved for open orders.
`pnl`	Number	Unrealized Profit and Loss.
`leverage`	Number	Position leverage.
`margin_mode`	String	Mode of margin trading. Possible values: `isolated`, `cross`
`state`	String	Position state. Possible values: `closed`, `active`, `liquidated`
`fee_cumulative`	String	Total amount of fees paid throughout the position lifetime until it is closed. This value does zero out after the position closes and does not when it flips.
`symbol`	String	Contract code.
`margin_call`	Boolean	Flag indicating the position is close to the liquidation, and increased margin may prevent it from happening.
`create_timestamp`	Number	Timestamp of position creation in nanoseconds.
`update_timestamp`	Number	Timestamp of position update in nanoseconds.

Futures Clearing Details

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/futures/history/clearing"

[
  {
    "timestamp": 1646524800267,
    "position_id": 972,
    "position_quantity": "0.00010",
    "position_entry_value": "5.126379000000",
    "type": "funding",
    "symbol": "BTCUSDT_PERP",
    "currency": "USD",
    "amount": "-0.011819526000",
    "rate": "0.003",
    "debt_delta": "0"
  }
]

GET /api/3/futures/history/clearing

Get clearing details.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`currency`	String	Quote currency code.
`sort`	String	Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`from`	Number	Interval initial value in nanoseconds. Minimum value: `1`
`till`	Number	Interval end value in nanoseconds. Minimum value: `1`
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`

Response:

Name	Type	Description
`timestamp`	Number	Transfer timestamp in nanoseconds.
`position_id`	Number	Optional. Position identifier.
`position_quantity`	Number	Optional. Position quantity.
`position_entry_value`	Number	Optional. Position value in currency.
`type`	String	Transfer type. Possible values: `funding`
`symbol`	String	Optional. Symbol code.
`currency`	String	Transfer currency.
`amount`	Number	Transfer amount.
`rate`	Number	Optional. Interest rate. It is `null` if the withdrawal occurred during a close trade (debt collection).
`debt_delta`	Number	Optional. Debt value. Returned if a user was unable to pay funding during the last withdrawal but had a positive UPnL.

Wallet Management

Wallet Balance

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/balance"

Response. All currencies:

[
  {
    "currency":"BTC",
    "available":"0.00005821",
    "reserved":"0.00001"
  },
  {
    "currency":"USDT",
    "available":"0.01",
    "reserved":"0"
  }
]

Response. One currency:

{
  "available":"0.00005821",
  "reserved":"0.00001"
}

GET /api/3/wallet/balance GET /api/3/wallet/balance/{currency}

Returns the user's wallet balances except zero balances.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	Optional. Currency filter.

Response:

Name	Type	Description
`currency`	String	Currency code.
`available`	Number	Amount available for withdrawals or transfers to the trading account.
`reserved`	Number	Amount reserved for incomplete transactions (including the fee).

Get Whitelisted Addresses

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/address/white-list"

{
  "addresses": [
    {
      "address": "3A3MR43kUvahSAJtTsxzE8mcTz3VfL9upi",
      "currency": "USDT",
      "name": "ETH withdrawal",
      "network": "ETH"
    }
  ]
}

GET /api/3/wallet/crypto/address/white-list

Returns whitelisted addresses.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`addresses`	[]JSON	Whitelisted addresses.
> `name`	String	Name of the whitelist item.
> `currency`	String	Currency code.
> `network`	String	Code of the currency of the hosting network.
> `address`	String	Address for deposits.

Get Deposit Crypto Address

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/address?currency=BTC"

[
  {
    "currency":"BTC",
    "address":"3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv"
  }
]

GET /api/3/wallet/crypto/address

Get current addresses. Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	Optional. Currency code.
`network_code`	String	Optional. Network code.

Response:

Name	Type	Description
`currency`	String	Optional. Currency code.
`address`	String	Address for deposits.
`payment_id`	String	Optional. An additional identifier required for specific currencies (for example, "Memo").
`public_key`	String	Optional. An additional identifier required for specific currencies.
`network_code`	String	Optional. Network code.

Generate Deposit Crypto Address

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/address" \
  -d "currency=BTC"

{
  "currency":"BTC",
  "address":"3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv"
}

POST /api/3/wallet/crypto/address

Creates a new deposit address. Existing addresses may still receive funds. For some tokens (e.g., Ethereum tokens), a single address is generated per base currency with additional identifiers which differ for each address: payment_id or public_key. As a result, generating a new address for such a token will change the current address for an entire base currency accordingly.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	Currency code.
`network_code`	String	Optional. Network code.

Response:

Name	Type	Description
`currency`	String	Optional. Currency code.
`address`	String	Address for deposits.
`payment_id`	String	Optional. An additional identifier required for specific currencies (for example, "Memo").
`public_key`	String	Optional. An additional identifier required for specific currencies.
`network_code`	String	Optional. Network code.

Last 10 Deposit Crypto Addresses

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/address/recent-deposit?currency=BTC"

[
  {
    "currency":"BTC",
    "address":"3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv"
  }
]

GET /api/3/wallet/crypto/address/recent-deposit

Returns the last 10 unique addresses used for deposits (by currency).

Requires the "Payment information" API key Access Right.

Name	Type	Description
`currency`	String	Currency code.
`network_code`	String	Optional. Network code.

Response:

Name	Type	Description
`currency`	String	Optional. Currency code.
`address`	String	Address for deposits.
`payment_id`	String	Optional. An additional identifier required for specific currencies (for example, "Memo").
`public_key`	String	Optional. An additional identifier required for specific currencies.
`network_code`	String	Optional. Network code.

Last 10 Withdrawal Crypto Addresses

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/address/recent-withdraw?currency=BTC"

[
  {
    "currency":"BTC",
    "address":"3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv"
  }
]

GET /api/3/wallet/crypto/address/recent-withdraw

Returns the last 10 unique addresses used for withdrawals (by currency).

Requires the "Payment information" API key Access Right.

Name	Type	Description
`currency`	String	Currency code.
`network_code`	String	Optional. Network code.

Response:

Name	Type	Description
`currency`	String	Optional. Currency code.
`address`	String	Address for deposits.
`payment_id`	String	Optional. An additional identifier required for specific currencies (for example, "Memo").
`public_key`	String	Optional. An additional identifier required for specific currencies.
`network_code`	String	Optional. Network code.

Withdraw Crypto

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/withdraw" \
  -d "currency=BTC&amount=0.001&address=3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv&auto_commit=false"

Success response:

{
  "id": "d2ce578f-647d-4fa0-b1aa-4a27e5ee597b"
}

Validation error:

{
  "error": {
    "code": 10001,
    "message": "Validation error",
    "description": "Invalid currency: fiat"
  }
}

Invalid currency error:

{
  "error": {
    "code": 2002,
    "message": "Currency not found",
    "description": "The requested currency can't be found. Requested: USD"
  }
}

Insufficient funds error:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

Limits exceeded error:

{
  "error": {
    "code": 20003,
    "message": "Limit exceeded",
    "description": "Withdrawal limit exceeded"
  }
}

POST /api/3/wallet/crypto/withdraw

Withdraw crypto. The transaction gets the status CREATED right after the creation.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Please take note that changing security settings affects withdrawals:

It is impossible to withdraw funds without enabling two-factor authentication (2FA).
Password reset blocks withdrawals for 72 hours (3 days).
2FA reset blocks withdrawals for 96 hours (4 days).
Each time a new address is added to the whitelist, it takes 48 hours before that address becomes active for withdrawal.

Parameters:

Name	Type	Description
`currency`	String	Currency code.
`network_code`	String	Optional. Network code.
`amount`	Number	The amount that will be sent to the specified address.
`address`	String	Address identifier.
`wallet_id`	String	Optional. Wallet ID.
`payment_id`	String	Optional. An additional identifier required for specific currencies (for example, "Memo").
`include_fee`	Boolean	Default value: `false` If `true` is set, then total spent value will include fees.
`auto_commit`	Boolean	Default value: `true` If `false` is set, then you should commit or rollback a transaction in an hour. Used in two-phase commit schema.
`use_offchain`	String	Whether the withdrawal may be committed off-chain. Accepted values: `never`, `optionally`, `required` Default value: `never`
`public_comment`	String	Optional. Maximum length is 255.

Response:

Name	Type	Description
`id`	String	Transaction unique identifier.

Convert Between Currencies

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/convert" \
  -d "from_currency=USDT20&to_currency=USDT&amount=0.01"

{
  "result": [
    "d2ce578f-647d-4fa0-b1aa-4a27e5ee597b",
    "d2ce57hf-6g7d-4ka0-b8aa-4a27e5ee5i7b"
  ]
}

POST /api/3/wallet/convert

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`from_currency`	String	Currency code.
`to_currency`	String	Currency code.
`amount`	Number	The amount that will be sent to the specified address.

Response:

Name	Type	Description
`result`	[]JSON	Transaction unique identifiers as assigned by exchange.

Withdraw Crypto Commit or Rollback

curl \
  -X PUT \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/withdraw/d2ce578f-647d-4fa0-b1aa-4a27e5ee597b"

{
  "result": true
}

PUT /api/3/wallet/crypto/withdraw/{id}

Commit a withdrawal. The transaction gets the status PENDING.

DELETE /api/3/wallet/crypto/withdraw/{id}

Roll back a withdrawal.

If the auto_commit parameter has been set to false while sending the request for withdrawing crypto, the withdrawal needs to be committed or rolled back one hour after the request. Use PUT /api/3/wallet/crypto/withdraw/{id} to approve the withdrawal operation, or DELETE /api/3/wallet/crypto/withdraw/{id} to discard it.

The id parameter must contain the unique transaction identifier value received as a result of the POST /api/3/wallet/crypto/withdraw request.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name	Type	Description
`id`	String	Transaction unique identifier returned to a `POST /api/3/wallet/crypto/withdraw` request.

Both methods are idempotent.

Response:

Name	Type	Description
`result`	Boolean	`true` if the request is completed.

Check If Crypto Address Belongs to Current Account

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/address/check-mine?address=1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2"

{
  "result": true
}

GET /api/3/wallet/crypto/address/check-mine

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`address`	String	Address.

Response:

`Name`	Type	Description
`result`	Boolean	`true` if the address belongs to the current account.

Transfer Between Wallet and Exchange

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/transfer" \
  -d "currency=eth&amount=0.01&source=wallet&destination=spot"

[
  "d2ce578f-647d-4fa0-b1aa-4a27e5ee597b"
]

POST /api/3/wallet/transfer

Transfers funds from the wallet to the exchange account to make them available for trading.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	Currency code.
`amount`	Number	The amount that will be transferred between accounts.
`source`	String	Transfer source account type. Accepted values: `wallet`, `spot`, `derivatives`. Must not be the same as `destination`.
`destination`	String	Transfer destination accounts type. Accepted values: `wallet`, `spot`, `derivatives`. Must not be the same as `source`.

Response:

Name	Type	Description
—	[]String	Transaction unique identifier as assigned by exchange.

Transfer Money to Another User

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/internal/withdraw" \
  -d "by=email&identifier=user@example.com&currency=BTC&amount=0.001"

{
  "result": "fd3088da-31a6-428a-b9b6-c482673ff0f2"
}

POST /api/3/wallet/internal/withdraw

Creates and commits an off-chain withdrawal from the wallet of one exchange user to the wallet of another exchange user.

Apart from available balance, the amount of a withdrawal must exceed the sum of:

fees;
the total amount reserved on all wallets;
the total amount reserved on all exchange accounts;
pending amounts of concurrent withdrawals.

An operation may fail due to the following reasons:

the user cannot perform this type of operation based on:
- temporary account limitations;
- no active 2FA.
it does not pass pre-AML checks.

Call GET /api/3/public/currency/{currency} and check payout_enabled to determine if withdrawals are allowed for the currency.

Call GET /api/3/wallet/transactions/{id} to check out the status of resulting transaction.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	Currency code.
`amount`	Number	The amount that will be transferred.
`by`	String	Type of the beneficiary `identifier` specified below. Accepted values: `email`, `username`, `external_id`
`identifier`	String	Beneficiary identifier value. Either email, external identifier, or username.
`public_comment`	String	Optional text comment for the external usage. Can be up to 255 characters long, excluding the following characters: `&`, `'`, `<`, `>`, `"`

Response:

Name	Type	Description
`result`	String	Transaction unique identifier as assigned by exchange.

Get Transactions History

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/transactions?currencies=ETH,BTC&sort=DESC"

[
  {
    "id": 50844835,
    "created_at": "2024-04-22T21:03:04.111Z",
    "updated_at": "2024-04-22T21:04:41.487Z",
    "last_activity_at": "2024-04-30T15:42:12.274495Z",
    "status": "SUCCESS",
    "type": "WITHDRAW",
    "subtype": "BLOCKCHAIN",
    "native": {
      "tx_id": "27fa7f14-ca49-42fd-834a-4ce630d069d2",
      "index": 1071885589,
      "currency": "ETH",
      "amount": "0.01042",
      "fee": "0.00958",
      "hash": "0xfb0ba568213d11230cd34d62fddd1cc1fe11fdc173l4f2007b0e47a06ad73d20",
      "address": "0xd959463c3fcb222124bb7bb642d6a6573a6c5aba",
      "confirmations": 20
    }
  },
  {
    "id": 36896428,
    "created_at": "2024-04-12T10:27:26.135Z",
    "updated_at": "2024-04-12T10:42:29.065Z",
    "last_activity_at": "2024-04-30T15:42:13.274495Z",
    "status": "SUCCESS",
    "type": "DEPOSIT",
    "subtype": "BLOCKCHAIN",
    "native": {
      "tx_id": "a271ad64-5f34-4115-a63e-1cb5bbe4f67e",
      "index": 429625504,
      "currency": "BTC",
      "amount": "0.04836614",
      "hash": "4d7ae7c9d6fe84405ae167b3f0beacx8c68eb5a9d5189bckeb65d5e306427oe6",
      "address": "3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv",
      "confirmations": 2,
      "senders": [
        "0xd959463c3fcb0d2124bb7ac642d6a6573a6c5aba"
      ]
    },
    "operation_id": "99e78bf4-a708-43a3-ab18-e8e7618cd891"
  }
]

GET /api/3/wallet/transactions

Returns all transactions or a number of transactions by identifiers.

Requires the "Payment information" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`from`	DateTime	Interval initial value (inclusive). The value type depends on `order_by`.
`till`	DateTime	Interval end value (inclusive). The value type depends on `order_by`.
`types`	String	Comma-separated transaction types.
`subtypes`	String	Comma-separated transaction subtypes.
`statuses`	String	Comma-separated transaction statuses. Accepted values: `CREATED`, `PENDING`, `FAILED`, `SUCCESS`, `ROLLED_BACK`
`currencies`	String	Comma-separated currency codes.
`networks`	String	Comma-separated network codes.
`id_from`	Number	Index interval initial value. Accepted values: `0` or greater
`id_till`	Number	Index interval end value. Accepted values: `0` or greater
`tx_ids`	String	Comma-separated transaction identifiers.
`order_by`	String	The field the entries sorted by. Accepted values: `id`, `created_at`, `updated_at`, `last_activity_at`, `ID`, `CREATED_AT`, `UPDATED_AT`, `LAST_ACTIVITY_AT` Default value: `created_at` Cannot be `id` or `ID` if `from` and (or) `till` are provided.
`sort`	String	Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`
`group_transactions`	Boolean	Flag indicating whether the returned transactions will be parts of a single operation. Default value: `false`

GET /api/3/wallet/transactions/{id}

Returns transaction by identifier.

Requires the "Payment information" API key Access Right.

Response:

Name	Type	Description
`id`	Number	Transaction unique identifier as assigned by exchange.
`status`	String	Transaction status. Possible values: `CREATED`, `PENDING`, `FAILED`, `SUCCESS`, `ROLLED_BACK`
`type`	String	Transaction type.
`subtype`	String	Transaction subtype.
`created_at`	DateTime	Date of transaction creation.
`updated_at`	DateTime	Date and time of the last transaction update.
`last_activity_at`	DateTime	Date and time of the last transaction info update.
`native`	Native	Optional. Transaction native attributes as assigned by the platform.
`meta`	Meta	Optional. Additional attributes assigned to certain types of transactions.
`operation_id`	String	Optional. UUID of the operation embracing the transaction.
`commit_risk`	Commit Risk	Optional. Deposit risk score info.

Commit Risk model consists of:

Name	Type	Description
`score`	Number	Risk score that decreases non-linearly when the transaction gains confirmations. Scores from 0 to 50 imply the transaction may be considered committed (but it is not guaranteed) or it may take at least half an hour otherwise. Possible values: `0` – `100`
`rbf`	Boolean	Flag indicating whether the transaction did not gain a sufficient number of confirmations and may be replaced by another one for an additional fee. This value indicates the transaction is complete and does not affect the score. `false` value along with a score above 50 gives a good chance that the transaction is irreversible.
`low_fee`	Boolean	Flag indicating whether the actual network fee is lower than the estimated one. This value indicates the difference between the estimated fee and the actual paid fee and does not affect the score.

Native model consists of:

Name	Type	Description
`tx_id`	String	Transaction unique identifier as assigned by exchange.
`network_code`	String	Optional. Network code.
`protocol_code`	String	Optional. The protocol or the standard powering the network.
`wallet_id`	String	Wallet ID.
`index`	Number	Internal index value that represents when the entry was updated.
`currency`	String	Currency code.
`amount`	Number	Amount of funds.
`fee`	Number	Payment commission value.
`address`	String	Address identifier.
`payment_id`	String	Optional. An additional identifier required for specific currencies (for example, "Memo").
`hash`	String	Transaction hash.
`offchain_id`	String	Transaction identifier of external system.
`confirmations`	Number	Current count of confirmations for transaction in network.
`public_comment`	String	Optional. Custom text comment for external use.
`error_code`	String	Payout error reason. Possible values: `INVALID_ADDRESS`, `INVALID_PAYMENT_ID`, `BAD_PRECISION`
`senders`	[]String	Senders for this payin transaction. Displayed only for deposits.
`operation_type`	String	Optional. Operation type. Possible values: `SWAP`, `OTC`

Meta model consists of:

Name	Type	Description
`fiat_to_crypto`	Fiat to Crypto	Optional. Attributes of a fiat deposit, or an order (for `subtype` equal to `FIAT`).
`instant_exchange`	Instant Exchange	Optional. Attributes of a swap (for `subtype` equal to `INSTANT_EXCHANGE`).

Fiat to Crypto model consists of:

Name	Type	Description
`id`	Number	Order identifier.
`provider_name`	String	Optional. Provider name.
`order_type`	String	Order type. Possible values: `buy`
`source_currency`	String	Source currency code.
`target_currency`	String	Destination currency code.
`wallet_address`	String	Wallet address for the incoming payment.
`tx_hash`	String	Transaction hash.
`target_amount`	String	Amount in the target currency.
`source_amount`	String	Amount in the source currency.
`status`	String	Order status. Possible values: `INITIAL`—the order is created in the system but will possibly never be submitted by the user; `IN_PROGRESS`—the order is pending; `COMPLETED`—the order was successfully processed at the provider's end; `FAILED`—the order failed at the provider's end; `EXPIRED`—the order expired after not receiving an incoming fiat payment; `UNKNOWN`—no status obtained at the provider's end.
`created_at`	DateTime	Order creation date.
`updated_at`	DateTime	Optional. Date of order last update.
`deleted_at`	DateTime	Optional. Date of order deletion.
`payment_method_type`	String	Optional. Payment system alias.

Instant Exchange model consists of:

Name	Type	Description
`id`	Number	Swap identifier.
`exchange_tx_id`	String	Transaction identifier.
`from_currency`	String	Source currency code.
`to_currency`	String	Target currency code.
`from_amount`	String	Source amount.
`to_amount`	String	Target amount.
`exchange_rate`	String	Actual exchange rate of the swap.
`payin_offchain_id`	String	Optional. Identifier of the transfer from the system account to the user's account.
`payout_offchain_id`	String	Optional. Identifier of the transfer from the user's account to the system account.
`is_offchain`	Boolean	Flag indicating whether the swap includes offchain transactions.
`created_at`	DateTime	Order creation date.
`updated_at`	DateTime	Optional. Date of order last update.
`type`	String	Swap type. Possible values: `market`
`payin_hash`	String	Optional. Hash of the transaction from the system account to the user's account. Equals to `payin_offchain_id`.
`payout_hash`	String	Optional. Hash of the transaction from the user's account to the system account. Equals to `payout_offchain_id`.
`product`	String	Operation type. Possible values: `"SWAP"`, `"OTC"`

type field may have the following values:

Type	Description
`DEPOSIT`	Deposit to a wallet address.
`WITHDRAW`	Withdrawal to another crypto address.
`TRANSFER`	Transfer of funds between wallet and trading accounts.
`SWAP`	Exchange funds between different wallets.
`OTC`	Exchanging funds between different wallets via an OTC trade.

subtype field may have the following values:

Type	Subtype	Description
`DEPOSIT`, `WITHDRAW`	`UNCLASSIFIED`	Deposit or withdrawal of fiat or crypto.
`DEPOSIT`, `WITHDRAW`	`BLOCKCHAIN`	Deposit or withdrawal of crypto committed to the Blockchain.
`DEPOSIT`	`BUY_CRYPTO`	Buying crypto with fiat.
`DEPOSIT`, `WITHDRAW`	`OFFCHAIN`	Deposit or withdrawal of crypto offchain.
`DEPOSIT`, `WITHDRAW`	`FIAT`	Fiat deposit or withdrawal.
`TRANSFER`	`WALLET_TO_SPOT`	Transfer from a wallet to a spot trading account.
`TRANSFER`	`SPOT_TO_WALLET`	Transfer from a futures trading account to a wallet.
`TRANSFER`	`WALLET_TO_DERIVATIVES`	Transfer from a wallet to a futures trading account.
`TRANSFER`	`DERIVATIVES_TO_WALLET`	Transfer from a futures trading account to a wallet.
`SWAP`	`CHAIN_SWITCH_FROM`	Transferring funds from an original wallet during a conversion.
`SWAP`	`CHAIN_SWITCH_TO`	Transferring funds to a target wallet during a conversion.
`SWAP`	`INSTANT_EXCHANGE`	Exchange funds between different wallets (swap).
`OTC`	`INSTANT_EXCHANGE`	Exchanging funds between different wallets via an OTC trade.
`DEPOSIT`	`AIRDROP`	Claimed airdrop payment.

status field may have the following values:

Name	Description
`CREATED`	The transaction has been created and needs to be approved. For withdrawals, the status means that the transaction has been created but not committed. It remains in this status until manually validated or moved to a blockchain.
`PENDING`	The transaction has been created and is queued until the fees are paid and it can be processed further. Also, for withdrawals and deposits, the status means that blockchain confirmations have not yet been gathered.
`FAILED`	The transaction could not be committed.
`ROLLED_BACK`	The transaction has been canceled.
`SUCCESS`	The transaction has been approved and fully processed.

Check If Offchain is Available

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/check-offchain-available" \
  -d "currency=ETH&address=0xfaEF4bE10dDF50B68c220c9ab19381e20B8EEB2B"

{
  "result": true
}

POST /api/3/wallet/crypto/check-offchain-available

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	Currency code.
`address`	String	Address identifier.
`payment_id`	String	Optional. An additional identifier required for specific currencies (for example, "Memo").

Response:

Name	Type	Description
`result`	String	`true` if an offchain transaction is available to the specified address.

Estimate Withdrawal Fees

curl \
  -X POST -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/fees/estimate" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '[
        {
          "amount": "12",
          "currency": "BTC"
        }
      ]'

[
  {
    "fee": "0.09",
    "networkFee": "0",
    "amount": "12",
    "currency": "btc"
  }
]

POST /api/3/wallet/crypto/fees/estimate

Returns estimated fees charged for processing of on-chain withdrawals for provided combination of currency and network.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
*	[]JSON	Combinations of currencies, networks, and amounts.
> `currency`	String	Currency code.
> `amount`	Number	The amount that will be deposited.
> `network_code`	String	Optional. Network code.

Response:

Name	Type	Description
*	[]JSON	Combinations of fees, currencies, networks, and amounts.
> `fee`	Number	Estimated withdrawal fee considering user's personal settings. The fee value is guaranteed not to change until the transaction is committed.
> `networkFee`	Number	Network fee.
> `amount`	Number	The amount that will be withdrawn.
> `currency`	String	Currency code.
> `networkCode`	String	Optional. Network code

Estimate Withdrawal Fee

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/fee/estimate?currency=BTC&amount=0.01"

{
  "fee": "0.0008"
}

GET /api/3/wallet/crypto/fee/estimate

Returns estimated fee charged for processing on-chain withdrawals for provided combination of currency and network.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	Currency code.
`amount`	Number	The amount that will be withdrawn.
`network_code`	String	Optional. Network code.

Response:

Name	Type	Description
`fee`	String	Estimated withdrawal fee considering user's personal settings. The fee value is guaranteed not to change until the transaction is committed.

Bulk Estimate Withdrawal Fee

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/fee/estimate/bulk" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '[
        {
          "amount": "12",
          "currency": "BTC"
        }
      ]'

[
  {
    "fee": "1.21",
    "currency": "BTC",
    "amount": "12"
  }
]

POST /api/3/wallet/crypto/fee/estimate/bulk

Returns estimated fees charged for processing on-chain withdrawals for provided combinations of currencies and networks.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
*	[]JSON	Combinations of currencies, networks, and amounts.
> `currency`	String	Currency code.
> `amount`	Number	The amount that will be deposited.
> `network_code`	String	Optional. Network code.

Response:

Name	Type	Description
*	[]JSON	Combinations of fees, currencies, networks, and amounts.
> `fee`	String	Estimated deposit fee considering user's personal settings. The fee value is guaranteed not to change until the transaction is committed.
> `currency`	String	Currency code.
> `amount`	Number	The amount that will be deposited.
> `network_code`	String	Optional. Network code.

Get Withdrawal Fees Hash

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/crypto/fee/withdraw/hash"

{
  "hash": "3982183395978"
}

GET /api/3/wallet/crypto/fee/withdraw/hash

Returns the hash for withdrawal fees.

Requires the "Payment information" API key Access Right.

Response:

Name	Type	Description
`hash`	String	Fees hash.

Swaps

Best Practices

The system allows exchanging currency in the following ways:

at market rate—only target amount is specified and the sum in the target currency is hardly predictable in favor of a shorter processing time;
at fixed rate via an OTC trade—the source amount is specified, and the exchange returns available rates which stay valid for 30 seconds for committing a trade providing a target amount or a rate identifier.
at floating rate—the desired price is specified loosely with the band that defines the accepted price deviation.

To exchange at market price, perform the following steps:

Determine whether the source currency supports swaps to the target currency.
API call: GET /api/3/wallet/swap/currencies
Check amount limits for the source currency.
API call: POST /api/3/wallet/swap/amount/market
Create a transaction specifying the amount in source currency.
API call: POST /api/3/wallet/swap/transaction/market
Check the transaction status.
API call: GET /api/3/wallet/swap/transaction/{id}

To exchange at floating rate, perform the following steps:

Determine whether the source currency supports swaps to the target currency. Only currencies exchanged at the market price ("market_currencies" in response) support floating rate swaps.
API call: GET /api/3/wallet/swap/currencies
Check amount limits for the source currency and the target currency.
API call: POST /api/3/wallet/swap/amount/fixed
Determine the exchange rate providing from_currency or to_currency.
API call: POST /api/3/wallet/swap/rate/fixed
Calculate the value of expected_price as amount_from divided by amount_to.
Create a transaction specifying the amount in source currency, expected price, and maximum slippage rate (if necessary).
API call: POST /api/3/wallet/swap/transaction/market
Check the transaction status.
API call: GET /api/3/wallet/swap/transaction/{id}

To commit an OTC trade at fixed rate, perform the following steps:

Determine whether the source currency supports swaps to the target currency.
API call: GET /api/3/wallet/swap/currencies
Check amount limits for the source currency and the target currency.
API call: POST /api/3/wallet/swap/amount/fixed
Determine the exchange rate specifying the source amount.
API call: POST /api/3/wallet/swap/rate/fixed
Within 30 seconds after receiving the rate, create a transaction specifying the amount in source currency, the amount in target currency, and the rate identifier.
API call: POST /api/3/wallet/swap/transaction/fixed
Check the transaction status.
API call: GET /api/3/wallet/swap/transaction/{id}

Get Supported Currencies

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/swap/currencies"

Response:

{
  "fixed_currencies": [],
  "market_currencies": [
    {
      "from_currency": "USDT",
      "to_currencies": [
        "ADA",
        "BTC",
        "USDSS",
        "USDT2"
      ],
      "minimal_amount": "2.37",
      "lot_size": 100
    }
  ]
}

GET /api/3/wallet/swap/currencies

Returns a list of supported instant exchange options both at a fixed price and the market price. The list is updated every 10 minutes.

Requires the "Payment information" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`product`	String	Flag indicating the call is related to OTC exchanges. Accepted values: `swap`, `otc` Default: `swap`

Response:

Name	Type	Description
`fixed_currencies`	[]Currencies	A list of currency codes exchanged at a fixed price.
`to_currencies`	[]Currencies	A list of currency codes exchanged at the market price.
`minimal_amount`	String	Minimum swap amount in the source currency.
`lot_size`	Number	Exponent of the minimum source amount (number of zeros in the number equals the maximum number of digits after the dot).

Currencies model consists of:

Name	Type	Description
`from_currency`	String	Source currency code.
`to_currencies`	[]String	A list of target currency codes.

Get Amount Limits at Market Price

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/swap/amount/market" \
  -d '{
        "from_currency":"USD",
        "to_currency":"XRP"
      }'

Response:

{
  "from_currency": "USD",
  "to_currency": "XRP",
  "min_amount_from": "29.05",
  "max_amount_from": "5500"
}

POST /api/3/wallet/swap/amount/market

Returns an estimated amount of target currency after an exchange performed at the asset market price.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`from_currency`	String	Source currency.
`to_currency`	String	Target currency.
`product`	String	Flag indicating the call is related to OTC exchanges. Accepted values: `swap`, `otc` Default: `swap`

Response:

Name	Type	Description
`from_currency`	String	Source currency.
`to_currency`	String	Target currency.
`min_amount_from`	String	Minimum estimated amount in the source currency.
`max_amount_from`	String	Maximum estimated amount in the source currency.

Get Amount Limits at Fixed Price

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/swap/amount/fixed" \
  -d '{
        "from_currency":"USD",
        "to_currency":XRP"
      }'

Response:

{
  "from_currency": "USD",
  "to_currency": "XRP",
  "min_amount_from": "15.02",
  "max_amount_from": "2750",
  "min_amount_to": "29.05",
  "max_amount_to": "5500"
}

POST /api/3/wallet/swap/amount/fixed

Returns an estimated amount of target currency after an exchange executed at a fixed rate.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`from_currency`	String	Source currency.
`to_currency`	String	Target currency.
`product`	String	Flag indicating the call is related to OTC exchanges. Accepted values: `swap`, `otc` Default: `swap`

Response:

Name	Type	Description
`from_currency`	String	Source currency.
`to_currency`	String	Target currency.
`min_amount_from`	String	Minimum estimated amount in the source currency.
`max_amount_from`	String	Maximum estimated amount in the source currency.
`min_amount_to`	String	Minimum estimated amount in the target currency.
`max_amount_to`	String	Maximum estimated amount in the target currency.

Get Estimated Rate at Market Price

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/swap/rate/market" \
  -d '{
        "from_currency":"USD",
        "to_currency":"XRP",
        "amount":31"
      }'

Response:

{
  "from_currency": "USD",
  "to_currency": "XRP",
  "amount_from": "31",
  "amount_to": "82.074726",
  "rate": "2.647571827"
}

POST /api/3/wallet/swap/rate/market

Returns an estimated exchange rate for the specified amount of source currency.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`from_currency`	String	Source currency.
`to_currency`	String	Target currency.
`amount`	String	Amount in the source currency.
`product`	String	Flag indicating the call is related to OTC exchanges. Accepted values: `swap`, `otc` Default: `swap`

Response:

Name	Type	Description
`from_currency`	String	Source currency.
`to_currency`	String	Target currency.
`amount_from`	String	Estimated amount in the source currency.
`amount_to`	String	Estimated amount in the target currency.
`rate`	String	Estimated exchange rate.

Get Estimated Rate at Fixed Price

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/swap/rate/fixed" \
  -d '{
        "from_currency":"USD",
        "to_currency":"XRP",
        "from_amount":"31"
      }'

Response:

{
  "from_currency": "USD",
  "to_currency": "XRP",
  "amount_from": "31",
  "amount_to": "82.074726",
  "rate": "2.647571827",
  "rate_id": "fe8993badf88c62f6c1e4d505d8a44b392f59d842e8023a9b3c601d627c1a3495d324a3ba388296bb94b8b6e6b3dede61818b88d001109e665c21903867cd4f89eb2c73cec04488613771e47f4506708f9"
}

POST /api/3/wallet/swap/rate/fixed

Returns an estimated exchange rate for the specified amount of source or target currency.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`from_currency`	String	Source currency.
`to_currency`	String	Target currency.
`from_amount`	String	Amount in the source currency.
`to_amount`	String	Amount in the target currency.
`product`	String	Flag indicating the call is related to OTC exchanges. Accepted values: `swap`, `otc` Default: `swap`

Response:

Name	Type	Description
`from_currency`	String	Source currency.
`to_currency`	String	Target currency.
`amount_from`	String	Estimated amount in the source currency.
`amount_to`	String	Estimated amount in the target currency.
`rate`	String	Estimated exchange rate.
`rate_id`	String	Rate identifier.

Exchange Assets at Market Price

curl \
  -X POST \
  "https://api.trade.mandala.exchange/api/3/wallet/swap/transaction/market" \
  -u "apiKey:secretKey" \
  -H "Content-Type: application/json" \
  -d '{
        "from_currency":"USD",
        "to_currency":"XRP",
        "from_amount":"31"
      }'

Response:

{
  "id": 74,
  "from_currency": "USD",
  "to_currency": "XRP",
  "from_amount": "31",
  "to_amount": "82.074726",
  "from_address": "HZcvXjbGmpWrdieawgx6MTwd9ChYArgUB",
  "to_address": "0x44999ee17c648b54f50d011523ce2581f27bee8e",
  "exchange_rate": "2.647571827",
  "created_at": "2021-12-24T14:07:21.797163Z",
  "updated_at": "2021-12-24T14:07:25.589624Z",
  "type": "MARKET",
  "status": "CREATED"
}

POST /api/3/wallet/swap/transaction/market

Creates a transaction to the exchange at the market price.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name	Type	Description
`from_currency`	String	Source currency.
`to_currency`	String	Target currency.
`from_amount`	String	Amount in the source currency.
`expected_price`	String	Optional. Expected exchange price. Required for an exchange at floating rate. Default value: `"0.05"` Example: `"0.01"` (1%)
`max_slippage_rate`	String	Optional. Maximum decimal fraction of the price slippage. May be specified for an exchange at floating rate.
`product`	String	Flag indicating the call is related to OTC exchanges. Accepted values: `swap`, `otc` Default: `swap`
`idempotency_key`	String	Idempotency key (UUID). Expires after 48 hours.

Response:

Name	Type	Description
`id`	Number	Swap identifier.
`from_currency`	String	Source currency code.
`to_currency`	String	Target currency code.
`from_amount`	String	Amount in the source currency.
`to_amount`	String	Amount in the target currency.
`from_address`	String	Source wallet address.
`to_address`	String	Target wallet address.
`exchange_rate`	String	Exchange rate.
`created_at`	DateTime	Date and time of the transaction creation.
`updated_at`	DateTime	Date and time of the last transaction status update.
`type`	String	Transaction type. Possible values: `MARKET`
`status`	String	Transaction status. Possible values: `CREATED`, `PENDING`, `FAILED`, `SUCCESS`, `ROLLED_BACK`

Exchange Assets at Fixed Price

curl \
    -X POST \
    -u "apiKey:secretKey" \
    "https://api.trade.mandala.exchange/api/3/wallet/swap/transaction/fixed" \
    -H "Content-Type: application/json" \
    -d '{
          "from_currency": "USD",
          "to_currency": "XRP",
          "from_amount": "31",
          "to_amount": "82.074726",
          "exchange_rate_id": "fe8993badf88c62f6c1e4d505d8a44b392f59d842e8023a9b3c601d627c1a3495d324a3ba388296bb94b8b6e6b3dede61818b88d001109e665c21903867cd4f89eb2c73cec04488613771e47f4506708f9"
        }'

Response:

{
  "id": 74,
  "from_currency": "USD",
  "to_currency": "XRP",
  "from_amount": "31",
  "to_amount": "82.074726",
  "from_address": "HZcvXjbGmpWrdieawgx6MTwd9ChYArgUB",
  "to_address": "0x44999ee17c648b54f50d011523ce2581f27bee8e",
  "exchange_rate": "2.647571827",
  "created_at": "2021-12-24T14:07:21.797163Z",
  "updated_at": "2021-12-24T14:07:25.589624Z",
  "type": "FIXED",
  "status": "CREATED"
}

POST /api/3/wallet/swap/transaction/fixed

Creates a transaction to the exchange at a fixed rate.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name	Type	Description
`from_currency`	String	Source currency.
`to_currency`	String	Target currency.
`from_amount`	String	Amount in the source currency.
to_amount	String	Amount in the target currency.
`exchange_rate_id`	String	Exchange rate identifier. Returned while getting an estimated rate at a fixed price (see Get Estimated Rate at Fixed Price).
`product`	String	Flag indicating the call is related to OTC exchanges. Accepted values: `swap`, `otc` Default: `swap`
`idempotency_key`	String	Idempotency key (UUID). Expires after 48 hours.

Response:

Name	Type	Description
`id`	Number	Swap identifier.
`from_currency`	String	Source currency code.
`to_currency`	String	Target currency code.
`from_amount`	String	Amount in the source currency.
`to_amount`	String	Amount in the target currency.
`from_address`	String	Source wallet address.
`to_address`	String	Target wallet address.
`exchange_rate`	String	Exchange rate.
`created_at`	DateTime	Date and time of the transaction creation.
`updated_at`	DateTime	Date and time of the last transaction status update.
`type`	String	Transaction type. Possible values: `FIXED`
`status`	String	Transaction status. Possible values: `CREATED`, `PENDING`, `FAILED`, `SUCCESS`, `ROLLED_BACK`

Get Transaction Details

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/swap/transaction/74"

Response:

{
  "id": 74,
  "status": "CREATED",
  "payin_hash": "0dce5c72-10b0-4c82-a6b7-1b3cse8eb1fe",
  "payout_hash": "75ae7494-0be2-44f3-87e8-4b3eef7930a1",
  "from_currency": "USD",
  "to_currency": "XRP",
  "from_amount": "31",
  "to_amount": "82.074726",
  "created_at": "2021-12-24T14:07:21.797163Z",
  "updated_at": "2021-12-24T14:07:25.589624Z"
}

GET /api/3/wallet/swap/transaction/{id}

Return transaction's details.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Response:

Name	Type	Description
`id`	Number	Swap identifier.
`status`	String	Transaction status. Possible values: `CREATED`, `PENDING`, `FAILED`, `SUCCESS`, `ROLLED_BACK`
`payin_hash`	String	Transaction identifier of the payin made to the target currency's balance.
`payout_hash`	String	Transaction identifier of the payout made from the source currency's balance.
`from_currency`	String	Source currency code.
`to_currency`	String	Target currency code.
`from_amount`	String	Amount in the source currency.
`to_amount`	String	Amount in the target currency.
`created_at`	DateTime	Date and time of the transaction creation.
`updated_at`	DateTime	Date and time of the last transaction status update.

Airdrops

Get Airdrops

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/airdrops"

[
  {
    "id": 3,
    "created_at": "2021-07-29T12:07:09.883538Z",
    "updated_at": "2021-08-04T12:54:59.301077Z",
    "currency": "BTC",
    "base_currency": "usd",
    "description": "test airdrop",
    "start_time": "2021-07-19T07:00:00Z",
    "end_time": "2022-07-19T07:00:00Z",
    "amount": "0.1",
    "status": "committed",
    "transaction_id": "85032346-7b90-4bdc-85ee-1f01e2390076"
  }
]

GET /api/3/wallet/airdrops

The request above returns the list of Airdrops.

Requires the "Payment information" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`currency`	String	The code of dropped currency.
`base_currency`	String	The code of base currency (the currency used for dropped currency amount calculation).
`active_at`	DateTime	The request returns Airdrops, active at the specified moment. Default value: `now`
`statuses`	[]String	An array of desired Airdrop statuses. Accepted values: `available` — ready for claiming; `claimed` — the Airdrop has been requested already; `pending` — the payment is in progress; `committed` — the payment is finished.
`transaction_id`	String	Airdrop transaction identifier.

Response:

Name	Type	Description
`id`	Number	Airdrop identifier.
`created_at`	DateTime	The moment when an Airdrop was created.
`updated_at`	DateTime	The moment when an Airdrop was changed.
`currency`	String	The code of dropped currency.
`base_currency`	String	The code of base currency (the currency used for dropped currency amount calculation).
`description`	String	Text note.
`start_time`	DateTime	The moment when an Airdrop claiming became available for the users.
`end_time`	DateTime	The moment when an Airdrop claiming will become unavailable for the users.
`amount`	String	The user's claimed amount.
`status`	String	Airdrop status. Possible values: `available` — ready for claim; `claimed` — the Airdrop has been requested already; `pending` — the payment is in progress; `committed` — the payment is finished.
`transaction_id`	String	Optional. Airdrop transaction identifier.

Claim Airdrop

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/airdrops/3/claim" \
  -d "currency=BTC"

{}

POST /api/3/wallet/airdrops/{id}/claim

Claim an airdrop by its identifier.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	The code of dropped currency.

Get Amount Locks

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/wallet/amount-locks?currency=BTC"

[
  {
    "id": 1,
    "currency": "BTC",
    "amount": "12.023",
    "date_end": "",
    "description": "default",
    "canceled": false,
    "canceled_at": null,
    "cancel_description": null,
    "created_at": "2021-07-29T12:07:09.883538Z"
  }
]

GET /api/3/wallet/amount-locks

Returns a list of amount locks.

Amount locks allow setting the minimum user's balance to determine their solvency. The locked amount is not displayed in the user's balances.

Amount locks are not tied to a currency. All locks in total affect the ability to withdraw the balance in any currency.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`currency`	String	Optional. Currency code.
`active`	Boolean	Optional. Value showing whether the lock is active.
`limit`	Number	Default value: `100` Accepted range: `0` – `1000`
`offset`	Number	Optional Default value: `0` Minimum value: `0`

Response:

Name	Type	Description
`id`	Number	Lock identifier.
`currency`	String	Currency code.
`amount`	String	Reserved amount.
`date_end`	DateTime	The date and time of the lock expiration.
`description`	String	Lock text description.
`canceled`	Boolean	Value showing whether the lock was canceled.
`canceled_at`	DateTime	The date and time at which the lock was canceled.
`cancel_description`	String	Text description on cancellation.
`created_at`	DateTime	The date and time of the lock was created.

Buy Crypto

You can purchase cryptocurrency on our platform. The current section requests allow receiving the list of providers, available for buying crypto, and information about them. You can receive rates and orders, and create orders using these API methods as well.

Get Providers Information

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/buy-crypto/provider"

Response:

[
  {
    "provider_id": 2,
    "provider_name": "provider",
    "methods": [
      {
        "id": 0,
        "name": "credit_debit_card",
        "description": "",
        "method_type": "credit_card",
        "logo_url": "https://example.com/logo.png",
        "status": "ACTIVE",
        "type": "credit_debit_card",
        "supported_source": [
          {
            "code": "USD",
            "display_name": "USD"
          }
        ],
        "supported_target": [
          {
            "code": "ETH",
            "display_name": "ETH"
          }
        ],
        "transaction_limits": [
          {
            "currency_code": "USD",
            "target_code": "ETH",
            "source_min": "0",
            "source_max": "124"
          }
        ]
      }
    ]
  }
]

GET /api/3/buy-crypto/provider

Returns the providers' information (transaction limits, available currencies, payment methods).

Requires the "Payment information" API key Access Right.

All parameters are optional.

Parameters:

Name	Type	Description
`provider_id`	Number	Provider identifier.
`source`	String	The source (fiat) currency code.
`target`	String	The target (crypto) currency code.

Response:

Name	Type	Description
`provider_id`	Number	Provider identifier.
`provider_name`	String	Provider name.
`methods`	[]Method	Payment methods list.

Method model consists of:

Name	Type	Description
`id`	Number	Payment method identifier.
`name`	String	Payment method name.
`description`	String	Payment method text description.
`method_type`	String	Method type.
`logo_url`	String	Payment method logo URL.
`status`	String	Payment method status. Possible values: `active`
`type`	String	Payment method type.
`supported_source`	[]Currency	The source currencies, supported by the payment method.
`supported_target`	[]Currency	The target currencies, supported by the payment method.
`transaction_limits`	[]Limit	Payment method limits.

Currency model consists of:

Name	Type	Description
`code`	String	The currency code.
`display_name`	String	The currency display name.
`network_code`	String	Optional. Network code.

Limit model consists of:

Name	Type	Description
`currency_code`	String	Transaction source currency code.
`target_code`	String	Transaction target currency code.
`source_min`	String	Minimum source currency amount.
`source_max`	String	Maximum source currency amount.
`network_code`	String	Optional. Network code.

Get Rates per Payment Method

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/buy-crypto/provider/1/rate"

Response:

{
  "spot_price": "10268.74",
  "prices": [
    {
      "payment_method_id": 6025,
      "type": "credit_debit_card",
      "target_code": "BTC",
      "target_amount": "1",
      "source_code": "USD",
      "source_amount": "10472.06"
    }
  ]
}

GET /api/3/buy-crypto/provider/{provider_id}/rate

Returns the rates information per payment method.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`source`	String	Source currency code.
`target`	String	Target currency code.
`source_amount`	String	Optional. Amount in the source currency.
`target_amount`	String	Optional. Amount in the target currency.
`payment_method_id`	Number	Optional. Payment method identifier.

Response:

Name	Type	Description
`spot_price`	String	The spot price.
`prices`	[]Price	Prices list.

Price model consists of:

Name	Type	Description
`payment_method_id`	Number	Payment method identifier.
`type`	String	Payment method type.
`target_code`	String	Target currency code.
`source_code`	String	Source currency code.
`target_amount`	String	Amount in the target currency.
`source_amount`	String	Amount in the source currency.

Get Order List

curl \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/buy-crypto/provider/1/order"

Response:

[
  {
    "id": 79,
    "provider_id": 1,
    "order_type": "buy",
    "source_code": "BTC",
    "target_code": "GBP",
    "wallet_address": "2N2gCeg7C1zKvZpFkdNNEnRFux9VSttzSVx",
    "checkout_url": "",
    "status": "expired",
    "created_at": "2024-04-07T10:04:40Z"
  }
]

GET /api/3/buy-crypto/provider/{provider_id}/order

Returns the list of buying cryptocurrency orders.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`from`	Number	Optional. Unix timestamp, filter by order creation date.
`till`	Number	Optional. Unix timestamp, filter by order creation date.
`limit`	Number	Optional. Limit.
`offset`	Number	Optional. Offset.
`source_code`	String	Optional. Source currency code.
`target_code`	String	Optional. Target currency code.
`wallet_address`	String	Optional. Filter by wallet address.
`target_network_code`	String	Optional. Network code.
`order_by`	String	Optional. Defines order type. Accepted values: `created_at`
`sort`	String	Optional. Sort direction. Accepted values: `desc`, `asc`

Response:

Name	Type	Description
`id`	Number	Order identifier.
`provider_id`	Number	Provider identifier.
`order_type`	String	Provider order type (buy).
`source_code`	String	Source currency code.
`target_code`	String	Target currency code.
`wallet_address`	String	The user will receive cryptocurrency from the crypto provider to this address. This address is generated and provided to the crypto provider by the exchange (by us).
`checkout_url`	String	Checkout URL.
`status`	String	Provider order status. Possible values: `initial`, `in_progress`, `completed`, `failed`, `expired`
`created_at`	String	Order creation date and time.
`operation_id`	String	Operation identifier.

Create Order

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.trade.mandala.exchange/api/3/buy-crypto/provider/1/order" \
  -H "Content-Type: application/json" \
  -d '{
        "target":"BTC",
        "source":"EUR",
        "source_amount":"20",
        "payment_method_id":6037
      }'

Response:

{
  "id": 79,
  "provider_id": 1,
  "order_type": "buy",
  "source_code": "BTC",
  "target_code": "GBP",
  "wallet_address": "2N2gCeg7C1zKvZpFkdNNEnRFux9VSttzSVx",
  "checkout_url": "",
  "status": "expired",
  "created_at": "2024-04-07T10:04:40Z"
}

POST /api/3/buy-crypto/provider/{provider_id}/order

Creates an order. The checkout_url will lead to a provider's widget page.

Requires the "Payment information" API key Access Right.

Parameters:

Name	Type	Description
`target`	String	Target currency.
`source`	String	Source currency.
`source_amount`	String	Amount in source currency.
`target_amount`	String	Optional. Amount in target currency.
`payment_method_id`	Number	Payment method identifier to use.
`ip`	String	Optional. IP address.
`user_agent`	String	Optional. User's client agent.
`target_network_code`	String	Optional. Network code.

Response:

Name	Type	Description
`id`	Number	Order identifier.
`provider_id`	Number	Provider identifier.
`order_type`	String	Provider order type (buy).
`source_code`	String	Source currency code.
`target_code`	String	Target currency code.
`wallet_address`	String	The user will receive cryptocurrency from the crypto provider to this address. This address is generated and provided to the crypto provider by the exchange.
`checkout_url`	String	Checkout URL.
`status`	String	Provider order status. Possible values: `initial`, `in_progress`, `completed`, `failed`, `expired`
`created_at`	String	Order creation date and time.
`operation_id`	String	Operation identifier.

SOCKET API REFERENCE

Connection

The number of WebSoсket connections established per IP address cannot exceed 100.

Ping

wscat -c wss://api.trade.mandala.exchange/api/3/ws/public -P

Ping messages

< Received ping
< Received ping
< Received ping

After a WebSocket connection is established, the system sends ping messages to the client each 30 seconds.

In order to see incoming ping messages, place -P flag after the endpoint.

Request Object

Request

{
  "method": "spot_new_order",
  "params": {
    "client_order_id": "57d5525562c945448e3cbd559bd068c4",
    "symbol": "ETHBTC",
    "side": "sell",
    "price": "0.059837",
    "quantity": "0.015"
  },
  "id": 123
}

An RPC call is represented by sending a Request object to a Server.

The Request object has the following members:

method — a String containing the name of the method to be invoked;
params — a Structured value that holds the parameter values to be used during the invocation of the method;
id — An identifier established by the Client that MUST contain a String, Number, or null value if included. If it is not included it is assumed to be a notification. The value SHOULD NOT be null.

Notification

Notification

{
  "ch": "trades",
  "update": {
    "BTCUSDT": [{
      "t": 1626861123552,
      "i": 1555634359,
      "p": "30877.68",
      "q": "0.00006",
      "s": "sell"
    }]
  }
}

A Notification is a Request object without an id member. A Request object (a Notification) signifies the lack of the Client's interest in the corresponding Response object. Therefore, no Response objects need to be returned to the Client.

Response Object

When an RPC call is made, the server must reply with responses, except for notifications cases.

Response on success subscription is true. Example:

Response

{
  "result": true,
  "id": 123
}

Response error

{
  "error": {
    "code": 2001,
    "message": "Symbol not found",
    "description": "Symbol not found"
  },
  "id": 123
}

The Response is represented as a single JSON Object, with the following members:

result — this member is REQUIRED on success. This member MUST NOT exist if there was an error during method invocation. The value of this member is determined by the method invoked on the Server;
error — this member is REQUIRED on error. This member MUST NOT exist if there was no error triggered during method invocation. The value for this member MUST be an Object as defined in the "Error Response" section.

Socket Market Data

In order to access market data via WebSocket interface, connect to the endpoint:

wscat -c wss://api.trade.mandala.exchange/api/3/ws/public

Request

{
  "method": "subscribe",
  "ch": "orderbook/top/1000ms",          // Channel
  "params": {
    "symbols": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

From that point on, you will be able to send request messages in JSON format with the following parameters:

Name	Type	Description
`method`	String	The name of the method to be invoked. Accepted values: `subscribe`, `unsubscribe`, `subscriptions`
`ch`	String	Channel name.
`params`	JSON	Parameter values to be used during the method invocation. The set of parameters may vary depending on the channel chosen.
`id`	String	Optional. Request identifier as assigned by sender.

Response

{
  "result": {
    "ch": "orderbook/top/1000ms",        // Channel
    "subscriptions": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Any valid and successfully processed request will result in a JSON-formatted response message containing the following fields:

Name	Type	Description
`result`	Result	Details about resulting subscription status.
`id`	String	Optional. Request identifier as assigned by sender.

Result model consists of:

Name	Type	Description
`ch`	String	Channel name.
`subscriptions`	[]String	List of active subscriptions.

Subscriptions

In case of a successful subscriptions, the server will send:

for price/rate/{speed}, ticker/price/{speed}, ticker/{speed}, orderbook/{depth}/{speed}, orderbook/top/{speed}, futures/info: data notifications (data) with a specified rate. {speed} — the period of updating data which embraces the changes that have occurred if any;
for trades, orderbook/full, candles/{period}: snapshot (snapshot) and update (update) notifications.

In the second case, the first snapshot comes right after the response if the limit parameter is greater than 0. Snapshot gives a full account of the market within the defined scope, and an update contains only recent changes which are being sent immediately.

Batch Notifications

If a market data request includes a number of subscriptions, a choice of channel will determine the distribution of updates over incoming notifications.

In the basic scenario, a single notification will contain data on a particular symbol only. Subscription to "batch" channels (ones ending with /batch) allows notifying via combined updates per multiple symbols.

Get Active Subscriptions

Request

{
  "method": "subscriptions",
  "ch": "trades",                        // Channel
  "params": {
    "symbols": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "trades",                      // Channel
    "subscriptions": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Method: subscriptions

Returns the list of all active subscriptions on a channel.

Request

{
  "method": "subscribe",
  "ch": "trades",                        // Channel
  "params": {
    "symbols": ["ETHBTC", "BTCUSDT"],
    "limit": 1
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "trades",                      // Channel
    "subscriptions": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Notification snapshot

{
  "ch": "trades",                        // Channel
  "snapshot": {
    "BTCUSDT": [{
      "t": 1626861109494,                // Timestamp in milliseconds
      "i": 1555634969,                   // Trade identifier
      "p": "30881.96",                   // Price
      "q": "12.66828",                   // Quantity
      "s": "buy"                         // Side
    }]
  }
}

Notification update

{
  "ch": "trades",
  "update": {
    "BTCUSDT": [{
      "t": 1626861123552,
      "i": 1555634969,
      "p": "30877.68",
      "q": "0.00006",
      "s": "sell"
    }]
  }
}

Channel: trades

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes.
`limit`	Number	Optional. Limit to returned entries. Accepted values: `0` – `1000` Default value: `0` (no history returned)

Request

{
  "method": "subscribe",
    "ch": "candles/M1",                  // Channel
    "params": {
      "symbols": ["BTCUSDT"],
      "limit": 10
    },
    "id": 123
  }

Response

{
  "result": {
    "ch": "candles/M1",
    "subscriptions": ["ETHBTC", "BTCUSDT"]
  },
  "id": 123
}

Notification snapshot

{
  "ch": "candles/M1",                    // Channel
  "snapshot": {
    "BTCUSDT": [
      {
        "t": 1626860340000,              // Message timestamp
        "o": "30881.95",                 // Open price
        "c": "30890.96",                 // Last price
        "h": "30900.8",                  // High price
        "l": "30861.27",                 // Low price
        "v": "1.27852",                  // Base asset volume
        "q": "39493.9021811"             // Quote asset volume
      },
      {
        "t": 1626860400000,
        "o": "30888.33",
        "c": "30860.52",
        "h": "30889.53",
        "l": "30860.31",
        "v": "3.80019",
        "q": "117283.0686182"
      },
      {
        "t": 1626860460000,
        "o": "30858.39",
        "c": "30863.56",
        "h": "30864.89",
        "l": "30853.83",
        "v": "53.04288",
        "q": "1636858.7119248"
      }
    ]
  }
}

Notification update

{
  "ch": "candles/M1",
  "update": {
    "ETHBTC": [
      {
        "t": 1626860880000,
        "o": "0.060711",
        "c": "0.060749",
        "h": "0.060749",
        "l": "0.060711",
        "v": "12.2800",
        "q": "0.7455339675"
      }
    ]
  }
}

Channel: candles/{period}

Supported periods: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes.
`limit`	Number	Optional. Limit to returned entries. Accepted values: `0` – `1000` Default value: `0` (no history returned)

Request

{
  "method": "subscribe",
  "ch": "converted/candles/M1",          // Channel
  "params": {
    "symbols": ["BTCUSDT"],
    "target_currency": "USDT",
    "limit": 10
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "converted/candles/M1",
    "subscriptions": [
      "BTCUSDT"
    ]
  },
  "id": 123
}

Notification snapshot

{
  "ch": "converted/candles/M1",
  "target_currency": "USDT",
  "snapshot": {
    "BTCUSDT": [
      {
        "t": 1626860340000,              // Message timestamp
        "o": "30881.95",                 // Open price
        "c": "30890.96",                 // Last price
        "h": "30900.8",                  // High price
        "l": "30861.27",                 // Low price
        "v": "1.27852",                  // Base asset volume
        "q": "39493.9021811"             // Quote asset volume
      }
    ]
  }
}

Notification update

{
  "ch": "converted/candles/M1",
  "target_currency": "USDT",
  "update": {
    "ETHBTC": {
      "BTCUSDT": [
        {
          "t": 1626860340000,
          "o": "30881.95",
          "c": "30890.96",
          "h": "30900.8",
          "l": "30861.27",
          "v": "1.27852",
          "q": "39493.9021811"
        }
      ]
    }
  }
}

Channel: converted/candles/{period}

Supported periods: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)

Requires no API key Access Rights.

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes.
`target_currency`	String	Target currency.
`limit`	Number	Optional. Limit to returned entries. Accepted values: `0` – `1000` Default value: `0` (no history returned)

Request

{
  "method": "subscribe",
  "ch": "price/rate/1s",                 // Channel
  "params": {
    "currencies": [
      "ETH",
      "BTC"
    ],
    "target_currency": "USDT"
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "price/rate/1s",               // Channel
    "target_currency": "USDT",
    "subscriptions": ["ETH","BTC"]
  },
  "id": 123
}

Data notification

{
  "ch": "price/rate/1s",
  "target_currency": "USDT",
  "data": {
    "ETH": {
      "t": 1684490221380,                // Timestamp
      "r": "1810.155"                    // Rate
    }
  }
}

{
  "ch": "price/rate/1s",
  "target_currency": "USDT",
  "data": {
    "BTC": {
      "t": 1684487340001,
      "r": "26863.71"
    }
  }
}

Channel: price/rate/{speed}

Supported speed: 1s, 3s

Parameters:

Name	Type	Description
`currencies`	[]String	List of currency codes. Value `["*"]` means all symbols are selected.
`target_currency`	String	Quote currency.

Request

{
  "method": "subscribe",
  "ch": "price/rate/1s/batch",           // Channel
  "params": {
    "currencies": [
      "ETH",
      "BTC"
    ],
    "target_currency": "USDT"
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "price/rate/1s/batch",         // Channel
    "target_currency": "USDT",
    "subscriptions": [
      "ETH",
      "BTC"
    ]
  },
  "id": 123
}

Data notification

{
  "ch": "price/rate/1s/batch",
  "target_currency": "USDT",
  "data": {
    "ETH": {
      "t": 1684490221380,                // Timestamp
      "r": "1810.155"                    // Rate
    },
    "BTC": {
      "t": 1684487340001,
      "r": "26863.71"
    }
  }
}

Channel: price/rate/{speed}/batch

Supported speed: 1s, 3s

Parameters:

Name	Type	Description
`currencies`	[]String	List of currency codes. Value `["*"]` means all symbols are selected.
`target_currency`	String	Quote currency.

Request

{
  "method": "subscribe",
  "ch": "ticker/price/1s",               // Channel
  "params": {
    "symbols": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "ticker/price/1s",             // Channel
    "subscriptions": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Data notification

{
  "ch": "ticker/price/1s",
  "data": {
    "ETHBTC": {
      "t": 1614815872000,                // Timestamp in milliseconds
      "o": "0.030781",                   // Open price
      "c": "0.060043",                   // Last price
      "h": "0.031788",                   // High price
      "l": "0.030733",                   // Low price
      "v": "62.587",                     // Base asset volume
      "q": "1.951420577"                 // Quote asset volume
    }
  }
}

{
  "ch": "ticker/price/1s",
  "data": {
    "BTCUSDT": {
      "t": 1614815872030,
      "o": "32636.79",
      "c": "32085.51",
      "h": "33379.92",
      "l": "30683.28",
      "v": "11.90667",
      "q": "384081.1955629"
    }
  }
}

Channel: ticker/price/{speed}

Supported speed: 1s, 3s

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes. Value `["*"]` means all symbols are selected.

Request

{
  "method": "subscribe",
  "ch": "ticker/price/1s/batch",         // Channel
  "params": {
    "symbols": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "ticker/price/1s/batch",       // Channel
    "subscriptions": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Data notification

{
  "ch": "ticker/price/1s/batch",
  "data": {
    "ETHBTC": {
      "t": 1614815872000,                // Timestamp in milliseconds
      "o": "0.030781",                   // Open price
      "c": "0.060043",                   // Last price
      "h": "0.031788",                   // High price
      "l": "0.030733",                   // Low price
      "v": "62.587",                     // Base asset volume
      "q": "1.951420577"                 // Quote asset volume
    },
    "BTCUSDT": {
      "t": 1614815872030,
      "o": "32636.79",
      "c": "32085.51",
      "h": "33379.92",
      "l": "30683.28",
      "v": "11.90667",
      "q": "384081.1955629"
    }
  }
}

Channel: ticker/price/{speed}/batch

Supported speed: 1s, 3s

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes. Value `["*"]` means all symbols are selected.

Request

{
  "method": "subscribe",
  "ch": "ticker/1s",                     // Channel
  "params": {
    "symbols": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "ticker/1s",                   // Channel
    "subscriptions": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Data notification

{
  "ch": "ticker/1s",
  "data": {
    "ETHBTC": {
      "t": 1614815872000,                // Timestamp in milliseconds
      "a": "0.031175",                   // Best ask
      "A": "0.03329",                    // Best ask quantity
      "b": "0.031148",                   // Best bid
      "B": "0.10565",                    // Best bid quantity
      "c": "0.031210",                   // Last price
      "o": "0.030781",                   // Open price
      "h": "0.031788",                   // High price
      "l": "0.030733",                   // Low price
      "v": "62.587",                     // Base asset volume
      "q": "1.951420577",                // Quote asset volume
      "p": "0.000429",                   // Price change
      "P": "1.39",                       // Price change percent
      "L": 1182694927                    // Last trade identifier
    }
  }
}

{
  "ch": "ticker/1s",
  "data": {
    "BTCUSDT": {
      "t": 1614815872050,
      "a": "32289.55",
      "A": "0.41210",
      "b": "32286.67",
      "B": "1.70049",
      "c": "0.057069",
      "o": "0.030545",
      "h": "0.029653",
      "l": "0.031804",
      "v": "11.90667",
      "q": "384081.1955629",
      "p": "0.003131",
      "P": "2.77",
      "L": 1182694927
    }
  }
}

Channel: ticker/{speed}

Supported speed: 1s, 3s

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes. Value `["*"]` means all symbols are selected.

Request

{
  "method": "subscribe",
  "ch": "ticker/1s/batch",               // Channel
  "params": {
    "symbols": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "ticker/1s/batch",             // Channel
    "subscriptions": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Data notification

{
  "ch": "ticker/1s/batch",
  "data": {
    "ETHBTC": {
      "t": 1614815872000,                // Timestamp in milliseconds
      "a": "0.031175",                   // Best ask
      "A": "0.03329",                    // Best ask quantity
      "b": "0.031148",                   // Best bid
      "B": "0.10565",                    // Best bid quantity
      "c": "0.031210",                   // Last price
      "o": "0.030781",                   // Open price
      "h": "0.031788",                   // High price
      "l": "0.030733",                   // Low price
      "v": "62.587",                     // Base asset volume
      "q": "1.951420577",                // Quote asset volume
      "p": "0.000429",                   // Price change
      "P": "1.39",                       // Price change percent
      "L": 1182694927                    // Last trade identifier
    },
    "BTCUSDT": {
      "t": 1614815872050,
      "a": "32289.55",
      "A": "0.41210",
      "b": "32286.67",
      "B": "1.70049",
      "c": "0.057069",
      "o": "0.030545",
      "h": "0.029653",
      "l": "0.031804",
      "v": "11.90667",
      "q": "384081.1955629",
      "p": "0.003131",
      "P": "2.77",
      "L": 1182694927
    }
  }
}

Channel: ticker/{speed}/batch

Supported speed: 1s, 3s

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes. Value `["*"]` means all symbols are selected.

Request

{
  "method": "subscribe",
  "ch": "orderbook/full",                // Channel
  "params": {
    "symbols": ["ETHBTC"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "orderbook/full",              // Channel
    "subscriptions": ["ETHBTC"]
  },
  "id": 123
}

Notification snapshot

{
  "ch": "orderbook/full",                // Channel
  "snapshot": {
    "ETHBTC": {
      "t": 1626866578796,                // Timestamp in milliseconds
      "s": 27617207,                     // Sequence number
      "a": [                             // Asks
        ["0.060506", "0"],
        ["0.060549", "12.6431"],
        ["0.060570", "0"],
        ["0.060612", "0"]
      ],
      "b": [                             // Bids
        ["0.060439", "4.4095"],
        ["0.060414", "0"],
        ["0.060407", "7.3349"],
        ["0.060390", "0"]
      ]
    }
  }
}

Notification update

{
  "ch": "orderbook/full",
  "update": {
    "ETHBTC": {
      "t": 1626866578902,
      "s": 27617208,
      "a": [
        ["0.060508", "0"],
        ["0.060509", "2.5486"]
        ],
      "b": [
        ["0.060501", "3.9000"],
        ["0.060500", "3.0459"]
        ]
    }
  }
}

Channel: orderbook/full

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes.

Request

{
  "method": "subscribe",
  "ch": "orderbook/D5/100ms",            // Channel
  "params": {
    "symbols": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "orderbook/D5/100ms",          // Channel
    "subscriptions": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Data notification

{
  "ch": "orderbook/D5/100ms",            // Channel
  "data": {
    "BTCUSDT": {
      "t": 1626958488996,                // Timestamp in milliseconds
      "s": 29472321,                     // Sequence number
      "a": [                             // Asks
        ["32091.84", "0.01016"],
        ["32091.85", "0.41484"],
        ["32095.82", "0.00705"],
        ["32095.95", "0.52001"],
        ["32097.04", "0.20518"]
      ],
      "b": [                             // Bids
        ["32089.29", "0.00228"],
        ["32088.70", "0.40315"],
        ["32084.29", "0.00616"],
        ["32084.27", "0.53169"],
        ["32078.89", "0.01016"]
      ]
    },
    "ETHBTC": {
      "t": 1626958488990,
      "s": 28438797,
      "a": [
        ["0.061873", "4.8257"],
        ["0.061887", "1.9938"],
        ["0.061912", "0.5427"],
        ["0.061913", "0.1696"],
        ["0.061914", "0.1575"]
      ],
      "b": [
        ["0.061867", "0.9868"],
        ["0.061858", "0.1598"],
        ["0.061854", "1.8327"],
        ["0.061850", "0.8125"],
        ["0.061842", "0.1763"]
      ]
    }
  }
}

Channel: orderbook/{depth}/{speed}

Supported depth: D5, D10, D20

Supported speed: 100ms, 500ms, 1000ms

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes. Value `["*"]` means all symbols are selected.

Request

{
  "method": "subscribe",
  "ch": "orderbook/D5/1000ms/batch",     // Channel
  "params": {
    "symbols": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "orderbook/D5/1000ms/batch",   // Channel
    "subscriptions": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Data notification

{
  "ch": "orderbook/D5/1000ms/batch",     // Channel
  "data": {
    "BTCUSDT": {
      "t": 1626958488996,                // Timestamp in milliseconds
      "s": 29472321,                     // Sequence number
      "a": [                             // Asks
        ["32091.84", "0.01016"],
        ["32091.85", "0.41484"],
        ["32095.82", "0.00705"],
        ["32095.95", "0.52001"],
        ["32097.04", "0.20518"]
      ],
      "b": [                             // Bids
        ["32089.29", "0.00228"],
        ["32088.70", "0.40315"],
        ["32084.29", "0.00616"],
        ["32084.27", "0.53169"],
        ["32078.89", "0.01016"]
      ]
    },
    "ETHBTC": {
      "t": 1626958488990,
      "s": 28438797,
      "a": [
        ["0.061873", "4.8257"],
        ["0.061887", "1.9938"],
        ["0.061912", "0.5427"],
        ["0.061913", "0.1696"],
        ["0.061914", "0.1575"]
      ],
      "b": [
        ["0.061867", "0.9868"],
        ["0.061858", "0.1598"],
        ["0.061854", "1.8327"],
        ["0.061850", "0.8125"],
        ["0.061842", "0.1763"]
      ]
    }
  }
}

Channel: orderbook/{depth}/{speed}/batch

Supported depth: D5, D10, D20

Supported speed: 100ms, 500ms, 1000ms

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes. Value `["*"]` means all symbols are selected.

Request

{
  "method": "subscribe",
  "ch": "orderbook/top/1000ms",          // Channel
  "params": {
    "symbols": ["ETHBTC", "BTCUSDT"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "orderbook/top/1000ms",        // Channel
    "subscriptions": ["ETHBTC", "BTCUSDT"]
  },
  "id": 123
}

Data notifications

{
  "ch": "orderbook/top/1000ms",
  "data": {
    "ETHBTC": {
      "t": 1626954648761,                // Timestamp in milliseconds
      "a": "0.062135",                   // Best ask
      "A": "4.1591",                     // Best ask quantity
      "b": "0.062124",                   // Best bid
      "B": "0.9877"                      // Best bid quantity
    }
  }
}

{
  "ch": "orderbook/top/1000ms",
  "data": {
    "BTCUSDT": {
      "t": 1626954648863,
      "a": "31936.09",
      "A": "1.30000",
      "b": "31933.40",
      "B": "0.00058"
    }
  }
}

Channel: orderbook/top/{speed}

Supported speed: 100ms, 500ms, 1000ms

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes. Value `["*"]` means all symbols are selected.

Request

{
  "method": "subscribe",
  "ch": "orderbook/top/100ms/batch",     // Channel
  "params": {
    "symbols": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "orderbook/top/100ms/batch",   // Channel
    "subscriptions": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Data notification

{
  "ch": "orderbook/top/100ms/batch",
  "data": {
    "ETHBTC": {
      "t": 1614815872000                 // Timestamp in milliseconds
      "a": "0.031175",                   // Best ask
      "A": "0.4033",                     // Best ask quantity
      "b": "0.031148",                   // Best bid
      "B": "0.3649",                     // Best bid quantity
    },
    "BTCUSDT": {
      "t": 1614815872005
      "a": "0.031175",
      "A": "0.4033",
      "b": "0.031148",
      "B": "0.3649",
    }
  }
}

Channel: orderbook/top/{speed}/batch

Supported speed: 100ms, 500ms, 1000ms

Parameters:

Name	Type	Description
`symbols`	[]String	List of symbol codes. Value `["*"]` means all symbols are selected.

Request

{
  "method": "subscribe",
  "ch": "futures/info",                  // Channel
  "params": {
    "symbols": ["*"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "futures/info",                // Channel
    "subscriptions": ["BTCUSDT_PERP", "UFO-0115"]
  },
  "id": 123
}

Data notification

{
  "ch": "futures/info",
  "data": {
    "BTCUSDT_PERP": {
      "c": "perpetual",                 // Contract type
      "t": 1626861214235,               // Timestamp in milliseconds
      "m": "30873.48",                  // Mark price
      "i": "30871.12",                  // Index price
      "p": "0.000045936718467837",      // Premium index
      "P": "0.000087063368020112",      // Average premium index
      "o": "93.7128",                   // Open interest
      "r": "0.0001",                    // Funding rate
      "R": "0.0001",                    // Indicative funding rate
      "I": "0.0001",                    // Contract interest rate for one funding period
      "T": 1626883200000                // Next funding date
    }
  }
}

{
  "ch": "futures/info",
  "data": {
    "UFO-0715": {
      "c": "cash_settled",               // Contract type
      "t": 1640187241062,                // Timestamp in milliseconds
      "m": "1.34783",                    // Mark price
      "i": "1.33958",                    // Index price
      "o": "0",                          // Open interest
      "s": null,                         // Indicative settlement price
      "e": 1657886400000                 // Expiration date
    }
  }
}

Channel: futures/info

Parameters:

Name	Type	Description
`symbols`	[]String	List of contract codes. Value `["*"]` means all symbols are selected.

Socket Authentication

Basic

Examples with Basic algorithm:

wscat -c wss://api.trade.mandala.exchange/api/3/ws/wallet

{
  "method": "login",
  "params": {
    "type": "BASIC",
    "api_key": "apiKey",
    "secret_key": "secretKey"
  }
}

Request method: login

Parameters:

Name	Type	Description
`type`	String	Encryption algorithm. Accepted values: `BASIC`
`api_key`	String	API public key.
`secret_key`	String	API secret key.

HS256

Example with HS256 algorithm:


wscat -c wss://api.trade.mandala.exchange/api/3/ws/wallet

{
  "method": "login",
  "params": {
    "type": "HS256",
    "api_key": "apiKey",
    "timestamp": 1626861109494,
    "signature": "secretKey"
  }
}

Signature generation example

from websocket import create_connection
import websocket
import json
from hashlib import sha256
from hmac import HMAC
from time import time


timestamp = int(time() * 1000)
api_key = "apiKey"
secret = "secretKey"
window = 10000
message = str(timestamp)

if window:
    message += str(window)

ws = create_connection('wss://api.trade.mandala.exchange/api/3/ws/wallet')

sign = HMAC(key=secret.encode(),
            msg=message.encode(),
            digestmod=sha256).hexdigest()

res = ws.send(json.dumps({"method": "login", "params": {"type": "HS256", "api_key": api_key, "timestamp": timestamp, "window": window, "signature": sign}}))

print(ws.recv())

Request method: login

Parameters:

Name	Type	Description
`type`	String	Encryption algorithm. Accepted values: `HS256`
`api_key`	String	API public key.
`timestamp`	Number	Timestamp.
`window`	Number	Optional. Maximum difference between `timestamp` and the moment of request processing in milliseconds. Accepted range: `1000` – `60000` Default value: `10000`
`signature`	String	HMAC SHA256 sign with API secret key.

Socket Trading

Trade via socket has some major differences compared to REST:

quickness. The time to place a new order is a bit higher than network latency;
the Server notifies you of any order updates;
FIFO. Your requests are executed on a First In First Out basis.

Socket Spot Trading

Request

wscat -c wss://api.trade.mandala.exchange/api/3/ws/trading

{
  "method": "spot_subscribe",
  "params": {},
  "id": 123
}

Subscription result:

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 123
}

Notification Spot orders snapshot

{
  "jsonrpc": "2.0",
  "method": "spot_orders",
  "params": [
    {
      "id": 584244931496,
      "client_order_id": "b5acd79c0a854b01b558665bcf379456",
      "symbol": "BTCUSDT",
      "side": "buy",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.01000",
      "quantity_cumulative": "0",
      "price": "0.01",
      "post_only": false,
      "created_at": "2021-07-02T22:52:32.864Z",
      "updated_at": "2021-07-02T22:52:32.864Z",
      "report_type": "status"
    },
    {
      "id": 584246978340,
      "client_order_id": "eeb7d144eca545cd93d83078bc60b7f4",
      "symbol": "BTCUSDT",
      "side": "buy",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.01000",
      "quantity_cumulative": "0",
      "price": "0.02",
      "post_only": false,
      "created_at": "2021-07-02T22:56:43.588Z",
      "updated_at": "2021-07-02T22:56:43.588Z",
      "report_type": "status"
    }
  ]
}

Notification Spot order update

{
  "jsonrpc": "2.0",
  "method": "spot_order",
  "params": {
    "id": 584244931496,
    "client_order_id": "b5acd79c0a854b01b558665bcf379456",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.01000",
    "quantity_cumulative": "0",
    "price": "0.01",
    "post_only": false,
    "created_at": "2021-07-02T22:52:32.864Z",
    "updated_at": "2021-07-02T22:52:32.864Z",
    "report_type": "new"
  }
}

Notification Spot trade

{
  "jsonrpc": "2.0",
  "method": "spot_order",
  "params": {
    "id": 626857425737,
    "client_order_id": "rqq6qnVTWvHa5YYG-7RviHLyA8JBu6Gj",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "filled",
    "type": "market",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0.00001",
    "post_only": false,
    "created_at": "2021-08-23T16:29:24.006Z",
    "updated_at": "2021-08-23T16:29:24.006Z",
    "trade_id": 1361977606,
    "trade_quantity": "0.00001",
    "trade_price": "49595.04",
    "trade_fee": "0.001239876000",
    "trade_taker": true,
    "report_type": "trade"
  }
}

Method: spot_subscribe, spot_unsubscribe

Income methods: spot_order, spot_orders

Subscribes to execution reports of user's orders.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Response:

Name	Type	Description
`id`	Number	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader.
`symbol`	String	Symbol code.
`side`	String	Trade side. Accepted values: `sell`, `buy`
`status`	String	Order state. Possible values: `new` — an order is placed in the order book. `suspended` — a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book. `partiallyFilled` — an order is executed, but a part of its quantity is not filled yet. `filled` — (in updates) order quantity filled completely. `canceled` — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `expired` — (in updates) an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
`type`	String	Order type. Possible values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`
`time_in_force`	String	Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired. `GTC` — "Good-Till-Canceled" order won't be closed until it is filled. `IOC` — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled. `FOK` — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all. `Day` — keeps the order active until the end of the trading day (23:59 UTC+0). `GTD` — "Good-Till-Date" order may remain active until the time specified in `expire_time`.
`quantity`	Number	Order quantity.
`price`	Number	Order price.
`cum_quantity`	Number	Cumulative executed quantity.
`post_only`	Boolean	A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`created_at`	DateTime	Report creation date.
`updated_at`	DateTime	Date of the report's last update.
`stop_price`	Number	Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
`expire_time`	DateTime	Date of order expiration for `time_in_force` equal to `GTD`.
`original_client_order_id`	String	Identifier of replaced order.
`trade_id`	Number	Trade identifier. Required if `report_type` is `trade`.
`trade_quantity`	Number	Quantity of trade. Required if `report_type` is `trade`.
`trade_price`	Number	Trade price. Required if `report_type` is `trade`.
`trade_fee`	Number	Fee paid for trade. Required if `report_type` is `trade`.
`trade_taker`	Boolean	Liquidity indicator. Required if `report_type` is `trade`.
`report_type`	String	Report type. Possible values: `status` — (in snapshots) the record of an event occurred during the last snapshot period. `new` — (in updates) an order has been placed in the order book (`status` is `new`). `suspended` — (in updates) a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book (`status` is `suspended`). `canceled` — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `rejected` — (in updates) order request has been rejected (it is applicable exclusively to a request entry, so the `status` of the related canceled/replaced order will not change — i.e., it cannot be different from `new`, `suspended`, `partiallyFilled`). `status` is `rejected`. `expired` — (in updates) an order is deactivated as it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements (`status` is `expired`). `replaced` — (in updates) an order cancel/replace request has been accepted and successfully processed (`status` is `canceled`, a new order placed instead has the `new` status value). `trade` — (in updates) an order has been fully or partially executed (`status` is `filled` or `partiallyFilled`).

Get Active Spot Orders

Notification report

{
  "jsonrpc": "2.0",
  "result": [
    {
      "id": 583502239480,
      "client_order_id": "9be4d950d3c04485854ec5d7f260b1e8",
      "symbol": "BTCUSDT",
      "side": "buy",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.01000",
      "quantity_cumulative": "0",
      "price": "0.01",
      "post_only": false,
      "created_at": "2021-07-01T23:04:04.048Z",
      "updated_at": "2021-07-01T23:04:04.048Z",
      "report_type": "status"
    }
  ],
  "id": 123
}

Method: spot_get_orders

Returns active orders.

Place New Spot Order

Request:

{
  "method": "spot_new_order",
  "params": {
    "client_order_id": "57d5525562c945448e3cbd559bd068c4",
    "symbol": "ETHBTC",
    "side": "sell",
    "type": "limit",
    "quantity": "0.015",
    "price": "0.059837"
  },
  "id": 123
}

Success response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583565960004,
    "client_order_id": "57d5525562c945448e3cbd559bd06211",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "market",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "post_only": false,
    "created_at": "2021-07-02T00:58:05.307Z",
    "updated_at": "2021-07-02T00:58:05.307Z",
    "report_type": "new"
  },
  "id": 123
}

Example error response:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  },
  "id": 123
}

Method: spot_new_order

Creates a new spot order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`client_order_id`	String	Optional. Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`symbol`	String	Symbol code.
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Must be set to `market`, `stopMarket`, or `takeProfitMarket` if `price` was left unspecified. Accepted values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket` Default value: `limit`
`time_in_force`	String	Optional. Order type. Accepted values: `GTC`, `IOC`, `FOK`, `Day`, `GTD` Default value: `FOK` — `type` is `market`, `stopMarket`, `takeProfitMarket`; `GTC` — `type` is `limit`, `stopLimit`, `takeProfitLimit`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required for limit types.
`stop_price`	Number	Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
`expire_time`	DateTime	Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol's tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`take_rate`	Number	Optional. Liquidity taker fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.
`make_rate`	Number	Optional. Liquidity provider fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.

Create New Spot Order List

Request:

{
  "method": "spot_new_order_list",
  "params": {
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "orders": [
      {
        "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
        "symbol": "ETHBTC",
        "side": "buy",
        "type": "limit",
        "time_in_force": "GTC",
        "quantity": "0.063",
        "price": "0.046016",
        "post_only": false
      },
      {
        "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
        "symbol": "ETHBTC",
        "side": "sell",
        "type": "stopMarket",
        "time_in_force": "GTC",
        "quantity": "0.063",
        "stop_price": "0.044050",
        "price": "0.044016",
        "post_only": false
      }
    ]
  },
  "id": 123
}

Success response:

{
  "jsonrpc": "2.0",
  "result":
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  "id": 123
}

{
  "jsonrpc": "2.0",
  "result":
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  "id": 123
}

Example error response:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  },
  "id": 123
}

Method: spot_new_order_list

Creates a new spot order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`order_list_id`	String	Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to `client_order_id` of the first order in the request.
`contingency_type`	String	Order list type. Accepted values: `allOrNone` (AON) — all orders in the set should be executed within a single transaction or become expired otherwise; `oneCancelOther` (OCO) — all orders in the set should be canceled if one of them was executed; `oneTriggerOther` (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other; `oneTriggerOneCancelOther` (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
`orders`	[]Order	Orders in the list. There must be 2 or 3 orders for `allOrNone`/`oneCancelOther`/`oneTriggerOther` and 3 — for `oneTriggerOneCancelOther`. Placing any other number of orders will result in an error.

Order model consists of:

Name	Type	Description
`client_order_id`	String	Optional. Must be different from the identifiers of other orders in the list. If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`symbol`	String	Symbol code. For an `allOrNone` order list, symbol code must be unique for each order in the list. For an `oneTriggerOneCancelOther` order list, symbol code must be the same for all orders in the list (placing orders in different order books is not supported).
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Accepted values: for `allOrNone` — `limit`, `market`; for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `limit`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`; for `oneTriggerOneCancelOther` — `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`. Default value: `limit`
`time_in_force`	String	Optional (required for `allOrNone`). Time in Force instruction. Accepted values: for `allOrNone` — `FOK`; for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `GTC`, `IOC` (except `limit` orders), `FOK` (except `limit` orders), `Day`, `GTD`; for `oneTriggerOneCancelOther` — `GTC`, `IOC`, `FOK`, `Day`, `GTD`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	The price level that triggers order activation. Required if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Date of order expiration. Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`take_rate`	Number	Optional. Liquidity taker fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.
`make_rate`	Number	Optional. Liquidity provider fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.

Cancel Spot Order

Request:

{
  "method": "spot_cancel_order",
  "params": {
    "client_order_id": "57d5525562c945448e3cbd559bd068c4"
  },
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583569472521,
    "client_order_id": "8a97337322774d8ea56448290fbc87b3",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "canceled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "0.01",
    "post_only": false,
    "created_at": "2021-07-02T01:03:56.625Z",
    "updated_at": "2021-07-02T01:05:41.84Z",
    "report_type": "canceled"
  },
  "id": 123
}

Method: spot_cancel_order

Cancels an existing order.

Cancel/Replace Spot Order

Request:

{
  "method": "spot_replace_order",
  "params": {
    "client_order_id": "d6b645556af740b1bd1683400fd9cbce",
    "new_client_order_id": "d6b645556af740b1bd1683400fd9cbcf",
    "quantity": "0.00001",
    "price": "0.02"
  },
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583572753114,
    "client_order_id": "d6b645556af740b1bd1683400fd9cbcf",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "0.02",
    "post_only": false,
    "created_at": "2021-07-02T01:10:06.976Z",
    "updated_at": "2021-07-02T01:11:18.238Z",
    "original_client_order_id": "d6b645556af740b1bd1683400fd9cbce",
    "report_type": "replaced"
  }
}

The Cancel/Replace request is used to change the parameters of an existing order and to change the quantity or price attribute of an open order.

Do not use this request to cancel the quantity remaining in an outstanding order. Use the Cancel request message for this purpose.

It is stipulated that a newly entered order cancels a prior order that has been entered but not yet executed.

Method: spot_replace_order

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`client_order_id`	String	Identifier of the order being replaced.
`new_client_order_id`	String	Optional. `client_order_id` for a new order. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`quantity`	Number	New order quantity.
`price`	Number	Optional. Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	Optional. The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`strict_validate`	Boolean	Optional. Price and quantity will be checked for the incrementation within tick size and quantity step. See symbol's `tick_size` and `quantity_increment`.

Cancel Spot Orders

Request:

{
  "method": "spot_cancel_orders",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
  {
    "id": 583572753114,
    "client_order_id": "d6b645556af740b1bd1683400fd9cbcf",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "0.02",
    "post_only": false,
    "created_at": "2021-07-02T01:10:06.976Z",
    "updated_at": "2021-07-02T01:11:18.238Z",
    "report_type": "canceled"
  }
  ]
}

Method: spot_cancel_orders

Cancels all user's active orders and returns the ones which could not be canceled.

Requires the "Place/cancel orders" API key Access Right.

Request

{
  "method": "spot_balance_subscribe",
  "params": {
    "mode": "updates"
  },
  "id": 123
}

Subscription result:

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 123
}

Notification Spot balance

{
  "jsonrpc": "2.0",
  "method": "spot_balance",
  "params": [
    {
      "currency": "BCN",
      "available": "100.000000000000",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "BTC",
      "available": "0.013634021",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "ETH",
      "available": "0",
      "reserved": "0.00200000",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    }
  ]
}

Method: spot_balance_subscribe, spot_balance_unsubscribe

Income methods: spot_balance

Subscribes to the user's balances.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`mode`	String	Subscription mode. Accepted values: `updates` — messages arrive after balance updates. `batches` — messages arrive at equal intervals if there were any updates.

Response:

Name	Type	Description
`currency`	String	Currency code.
`available`	Number	Amount available for trading or transfer to wallet.
`reserved_margin`	Number	Amount reserved for margin trading funded by an isolated margin account.
`cross_margin_reserved`	Number	Amount reserved for margin trading funded by a cross–margin account.
`reserved`	Number	Total amount reserved for active orders and incomplete transfers to wallet.

Get Spot Trading Balances

Request:

{
  "method": "spot_balances",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc":"2.0",
  "result": [
    {
      "currency": "BCN",
      "available": "100.000000000000",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "BTC",
      "available": "0.013634021",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "ETH",
      "available": "0",
      "reserved": "0.00200000",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    }
  ],
  "id": 123
}

Method: spot_balances

Returns all non-zero trading balances.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Spot Trading Balance

Request:

{
  "method": "spot_balance",
  "params": {
    "currency": "BTC"
  },
  "id": 123
}

Response:

{
  "jsonrpc":"2.0",
  "result": {
    "currency": "BTC",
    "available": "0.013634021",
    "reserved": "0",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  },
  "id": 123
}

Method: spot_balance

Returns trading balance for a single currency.

Get Spot Fees

Request:

{
  "method": "spot_fees",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc":"2.0",
  "result": [
  {
    "symbol": "BTCUSDT",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  },
  {
    "symbol": "ETHBTC",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  }
  ],
  "id": 123
}

Method: spot_fees

Returns fees for all available symbols.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Spot Fee

Request:

{
  "jsonrpc":"2.0",
  "method": "spot_fee",
  "params": {
    "symbol": "BTCUSDT"
  },
  "id": 123
}

Response:

{
  "jsonrpc":"2.0",
  "result":
  {
    "symbol": "BTCUSDT",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  },
  "id": 123
}

Method: spot_fee

Returns fees for the symbol specified.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Socket Margin Trading

Description

API provides the following tools to manage margin trading: * subscribe to the reports about: * margin account changes; * margin orders. * setup isolated margin account — reserve amount for margin trading per symbol; * handle margin orders: * list orders; * place a new order; * cancel an order; * alter an order; * cancel all orders. * close position.

Request

wscat -c wss://api.trade.mandala.exchange/api/3/ws/trading

{
  "method": "margin_subscribe",
  "params": {},
  "id": 123
}

Subscription result:

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 1234
}

Notification. Margin Orders snapshot:

{
  "jsonrpc": "2.0",
  "method": "margin_orders",
  "params": [
    {
      "id": 584244931496,
      "client_order_id": "b5acd79c0a854b01b558665bcf379456",
      "symbol": "BTCUSDT",
      "side": "buy",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.01000",
      "quantity_cumulative": "0",
      "price": "0.01",
      "post_only": false,
      "reduce_only": false,
      "created_at": "2021-07-02T22:52:32.864Z",
      "updated_at": "2021-07-02T22:52:32.864Z",
      "margin_mode": "isolated",
      "report_type": "status"
    },
    {
      "id": 584246978340,
      "client_order_id": "eeb7d144eca545cd93d83078bc60b7f4",
      "symbol": "BTCUSDT",
      "side": "buy",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.01000",
      "quantity_cumulative": "0",
      "price": "0.02",
      "post_only": false,
      "reduce_only": false,
      "created_at": "2021-07-02T22:56:43.588Z",
      "updated_at": "2021-07-02T22:56:43.588Z",
      "margin_mode": "isolated",
      "report_type": "status"
    }
  ]
}

Notification. Margin Order update:

{
  "jsonrpc": "2.0",
  "method": "margin_order",
  "params": {
    "id": 583583708580,
    "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
    "symbol": "BTCUSDT",
    "side": "sell",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "80000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:32:15.732Z",
    "updated_at": "2021-07-02T01:32:15.732Z",
    "margin_mode": "isolated",
    "report_type": "new"
  }
}

Notification. Margin trade:

{
  "jsonrpc": "2.0",
  "method": "margin_order",
  "params": {
    "id": 583583708580,
    "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
    "symbol": "BTCUSDT",
    "side": "sell",
    "status": "filled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0.00001",
    "price": "80000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:32:15.732Z",
    "updated_at": "2021-07-02T01:32:15.732Z",
    "margin_mode": "isolated",
    "trade_id": 1361988214,
    "trade_quantity": "0.00001",
    "trade_price": "49509.81",
    "trade_fee": "0.001237745250",
    "trade_position_id": 485308,
    "report_type": "trade"
  }
}

Notification. Margin Accounts snapshot:

{
  "jsonrpc": "2.0",
  "method": "margin_accounts",
  "params": [
    {
      "symbol": "BTCUSDT",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T00:54:28.591Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.080706742356",
          "reserved_orders": "0",
          "reserved_positions": "0.029630234750"
        }
      ],
      "positions": [
        {
          "id": 485264,
          "symbol": "BTCUSDT",
          "quantity": "0.00001",
          "margin_mode": "isolated",
          "price_entry": "33386.18",
          "price_margin_call": "27269.85",
          "price_liquidation": "26721.57",
          "pnl": "0",
          "created_at": "2021-07-01T21:43:19.727Z",
          "updated_at": "2021-07-02T00:54:28.591Z"
        }
      ],
      "report_type": "status",
      "report_reason": "status"
    },
    {
      "symbol": "ETHUSDT",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:20:25.118Z",
      "updated_at": "2021-07-01T21:20:25.118Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.002000000000",
          "reserved_orders": "0",
          "reserved_positions": "0"
        }
      ],
      "positions": null,
      "report_type": "status",
      "report_reason": "status"
    }
  ]
}

Notification. Margin Account update:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T00:54:28.591Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.080706742356",
        "reserved_orders": "0",
        "reserved_positions": "0.029630234750"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "27269.85",
        "price_liquidation": "26721.57",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T00:54:28.591Z"
      }
    ],
    "report_type": "status",
    "report_reason": "status"
  }
}

Method: margin_subscribe, margin_unsubscribe

Requires the "Orderbook, History, Trading balance" API key Access Right.

Income method: margin_order, margin_orders

Fields:

Name	Type	Description
`id`	Number	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader.
`symbol`	String	Symbol code.
`side`	String	Trade side. Accepted values: `sell`, `buy`
`status`	String	Order state. Possible values: `new` — an order is placed in the order book. `suspended` — a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book. `partiallyFilled` — an order is executed, but a part of its quantity is not filled yet. `filled` — (in updates) order quantity filled completely. `canceled` — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `expired` — (in updates) an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
`type`	String	Order type. Possible values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`
`time_in_force`	String	Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired. `GTC` — "Good-Till-Canceled" order won't be closed until it is filled. `IOC` — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled. `FOK` — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all. `Day` — keeps the order active until the end of the trading day (23:59 UTC+0). `GTD` — "Good-Till-Date" order may remain active until the time specified in `expire_time`.
`quantity`	Number	Order quantity.
`price`	Number	Order price.
`cum_quantity`	Number	Cumulative executed quantity.
`post_only`	Boolean	A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
`created_at`	DateTime	Report creation date.
`updated_at`	DateTime	Date of the report's last update.
`margin_mode`	String	Margin mode. Possible values: `isolated`, `cross`
`stop_price`	Number	Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
`expire_time`	DateTime	Date of order expiration for `time_in_force` equal to `GTD`.
`original_client_order_id`	String	Identifier of replaced order.
`trade_id`	Number	Trade identifier. Required if `report_type` is `trade`.
`trade_quantity`	Number	Quantity of trade. Required if `report_type` is `trade`.
`trade_price`	Number	Trade price. Required if `report_type` is `trade`.
`trade_fee`	Number	Fee paid for trade. Required if `report_type` is `trade`.
`trade_taker`	Boolean	Liquidity indicator. Required if `report_type` is `trade`.
`trade_position_id`	Number	Position identifier of the trade.
`report_type`	String	Report type. Possible values: `status` — (in snapshots) the record of an event occurred during the last snapshot period. `new` — (in updates) an order has been placed in the order book (`status` is `new`). `suspended` — (in updates) a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book (`status` is `suspended`). `canceled` — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `rejected` — (in updates) order request has been rejected (it is applicable exclusively to a request entry, so the `status` of the related canceled/replaced order will not change — i.e., it cannot be different from `new`, `suspended`, `partiallyFilled`). `status` is `rejected`. `expired` — (in updates) an order is deactivated as it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements (`status` is `expired`). `replaced` — (in updates) an order cancel/replace request has been accepted and successfully processed (`status` is `canceled`, a new order placed instead has the `new` status value). `trade` — (in updates) an order has been fully or partially executed (`status` is `filled` or `partiallyFilled`).

Income method: margin_account, margin_accounts

Fields:

Name	Type	Description
`symbol`	String	Trading symbol. Where base currency is the currency of funds reserved on the trading account for positions and quote currency is the currency of funds reserved on a margin account (e.g., `"BTCUSDT"`).
`type`	String	Type of margin. Only `isolated`.
`leverage`	Number	Optional. Margin leverage. The ratio of the trader's own funds to funds borrowed from the platform.
`created_at`	DateTime	Account creation date and time.
`updated_at`	DateTime	Account last update date and time.
`currencies`	Currency	Amount of funds on Margin Account.
`positions`	Position	Optional. Open positions of the Margin Account.
`report_type`	String	Report type. Possible values: `status` — status of margin account requested, e.g., subscription report with a list of current margin accounts. `created` — new margin account created or position, e.g., new margin account requested or a flip trade occurs with position. `updated` — margin account or position updated. `closed` — margin account closed.
`report_reason`	String	Report reason. Possible values: `status`, `created`, `updated`, `marginChanged`, `openTrade`, `closeTrade`, `flipTrade`, `closed`, `reopened`, `liquidated`, `interestTaken`, `liquidationTrade`

Currency model consists of:

Name	Type	Description
`code`	String	Currency code.
`margin_balance`	Number	The total value of funds reserved for the position.
`reserved_orders`	Number	The value reserved for active orders in the position.
`reserved_positions`	Number	The minimum value reserved for position's executed quantity that cannot be reduced.

Report type values:

Status	Description
`status`	Status of margin account requested, e.g., get accounts or subscription report with a list of current margin accounts.
`created`	A new margin account created, e.g., new margin account has been created or recreated as a result of flip trade occurs with the position.
`updated`	Margin account or position has been updated.
`closed`	Margin account has been closed.

Report reason values:

Status	Description
`status`	Response to an account information request.
`created`	Position has been created.
`updated`	Position has been changed as a result of any order report, e.g., `new`, `canceled`, `filled`, and so on.
`marginChanged`	Margin account has been changed as a result of any requested change of the `margin_balance`.
`openTrade`	Opening trade has been executed.
`closeTrade`	Closing trade has been executed.
`flipTrade`	The position has been flipped as a result of opposite order execution with a quantity exceeding the position quantity (quantity has changed sign).
`closed`	The position quantity has been set to `"0"` (zero) as a result of close trade.
`liquidated`	The position has been liquidated.
`interestTaken`	The interest rate has been paid.
`liquidationTrade`	Liquidation order has been placed.

Get Margin Orders

Request:

{
  "method": "margin_get_orders",
  "params": {},
  "id": 1234
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "id": 583583708580,
      "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
      "symbol": "BTCUSDT",
      "side": "sell",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.00001",
      "quantity_cumulative": "0",
      "price": "80000.00",
      "post_only": false,
      "reduce_only": false,
      "created_at": "2021-07-02T01:32:15.732Z",
      "updated_at": "2021-07-02T01:32:15.732Z",
      "margin_mode": "isolated",
      "report_type": "status"
    }
  ],
  "id": 1234
}

Method: margin_get_orders

Returns all active margin orders.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Place New Margin Order

Request:

{
  "method": "margin_new_order",
  "params": {
    "symbol": "BTCUSDT",
    "side": "buy",
    "quantity": "0.00001",
    "price": "30000",
    "client_order_id": "2d42e072e4f34846954509c955303e11"
  },
  "id": 1238
}

Notification. Order report:

{
  "jsonrpc": "2.0",
  "method": "margin_order",
  "params": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "margin_mode": "isolated",
    "report_type": "new"
  }
}

Notification. Account report:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.080706742356",
        "reserved_orders": "0.027375000000",
        "reserved_positions": "0.049647514286"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "30218.68",
        "price_liquidation": "29611.12",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:41:07.18Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "updated"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "margin_mode": "isolated",
    "report_type": "new"
  },
  "id": 1238
}

Method: margin_new_order

Places a new margin order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`client_order_id`	String	Optional. Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`symbol`	String	Symbol code.
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Must be set to `market`, `stopMarket`, or `takeProfitMarket` if `price` was left unspecified. Accepted values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket` Default value: `limit`
`time_in_force`	String	Optional. Accepted values: `GTC`, `IOC`, `FOK`, `Day`, `GTD` Default value: `FOK` — `type` is `market`, `stopMarket`, `takeProfitMarket`; `GTC` — `type` is `limit`, `stopLimit`, `takeProfitLimit`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required for limit types.
`stop_price`	Number	Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
`expire_time`	DateTime	Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol's tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise. Default: `false` Conditions: `quantity` is omitted.
`margin_mode`	String	Optional. Margin mode. Accepted values: `isolated`, `cross` Default: `isolated`

Create New Margin Order List

Request:

{
  "method": "margin_new_order_list",
  "params": {
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "orders": [
      {
        "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
        "symbol": "ETHBTC",
        "side": "buy",
        "type": "limit",
        "time_in_force": "GTC",
        "quantity": "0.063",
        "price": "0.046016",
        "reduce_only": false,
        "post_only": false
      },
      {
        "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
        "symbol": "ETHBTC",
        "side": "sell",
        "type": "stopMarket",
        "time_in_force": "GTC",
        "quantity": "0.063",
        "stop_price": "0.044050",
        "price": "0.044016",
        "reduce_only": false,
        "post_only": false
      }
    ]
  },
  "id": 123
}

Success response:

{
  "jsonrpc": "2.0",
  "result":
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z",
    "margin_mode": "isolated"
  }
  "id": 123
}

{
  "jsonrpc": "2.0",
  "result":
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z",
    "margin_mode": "isolated"
  }
  "id": 123
}

Example error response:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  },
  "id": 123
}

Method: margin_new_order_list

Creates a new margin order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`order_list_id`	String	Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to `client_order_id` of the first order in the request.
`contingency_type`	String	Order list type. Accepted values: `oneCancelOther` (OCO) — all orders in the set should be canceled if one of them was executed; `oneTriggerOther` (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other; `oneTriggerOneCancelOther` (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
`orders`	[]Order	Orders in the list. There must be 2 or 3 orders for `allOrNone`/`oneCancelOther`/`oneTriggerOther` and 3 — for `oneTriggerOneCancelOther`. Placing any other number of orders will result in an error.

Order model consists of:

Name	Type	Description
`client_order_id`	String	Optional. Must be different from the identifiers of other orders in the list. If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`symbol`	String	Symbol code. Must be the same for all orders in an `oneTriggerOneCancelOther` order list (placing orders in different order books is not supported).
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Accepted values: for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `limit`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`; for `oneTriggerOneCancelOther` — `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`. Default value: `limit`
`time_in_force`	String	Optional. Time in Force instruction. Accepted values: for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `GTC`, `IOC` (except `limit` orders), `FOK` (except `limit` orders), `Day`, `GTD`; for `oneTriggerOneCancelOther` — `GTC`, `IOC`, `FOK`, `Day`, `GTD`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	The price level that triggers order activation. Required if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Date of order expiration. Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise. Default: `false` Conditions: `quantity` is omitted.
`margin_mode`	String	Optional. Margin mode. Accepted values: `isolated`, `cross` Default: `isolated`

Cancel Margin Order

Request:

{
  "method": "margin_cancel_order",
  "params": {
    "client_order_id": "2d42e072e4f34846954509c955303e11"
  },
  "id": 1240
}

Notification. Order report:

{
  "jsonrpc": "2.0",
  "method": "margin_order",
  "params": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "canceled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:46:06.016Z",
    "margin_mode": "isolated",
    "report_type": "canceled"
  }
}

Notification. Account report:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:46:06.016Z",
    "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.080706742356",
      "reserved_orders": "0",
      "reserved_positions": "0.029822235125"
    }
    ],
    "positions": [
    {
      "id": 485264,
      "symbol": "BTCUSDT",
      "quantity": "0.00001",
      "margin_mode": "isolated",
      "price_entry": "33386.18",
      "price_margin_call": "27269.85",
      "price_liquidation": "26721.57",
      "pnl": "0",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T01:46:06.016Z"
    }
    ],
    "report_type": "updated",
    "report_reason": "updated"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "canceled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:46:06.016Z",
    "margin_mode": "isolated",
    "report_type": "canceled"
  },
  "id": 1240
}

Method: margin_cancel_order

Cancels an active margin order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`client_order_id`	String	Required. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.

Cancel/Replace Margin Order

Request:

{
  "method": "margin_replace_order",
  "params": {
    "quantity": "0.00001",
    "price": "32000",
    "client_order_id": "2d42e072e4f34846954509c955303e12",
    "new_client_order_id": "2d42e072e4f34846954509c955303e13"
  },
  "id": 1239
}

Notification. Margin Order report:

{
  "jsonrpc": "2.0",
  "method": "margin_order",
  "params": {
    "id": 583593326663,
    "client_order_id": "2d42e072e4f34846954509c955303e13",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "32000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:48:21.882Z",
    "updated_at": "2021-07-02T01:49:51.003Z",
    "margin_mode": "isolated",
    "original_client_order_id": "2d42e072e4f34846954509c955303e12",
    "report_type": "replaced"
  }
}

Notification. Margin Account report:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:49:51.003Z",
    "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.080706742356",
      "reserved_orders": "0.029200000000",
      "reserved_positions": "0.030699895239"
    }
    ],
    "positions": [
    {
      "id": 485264,
      "symbol": "BTCUSDT",
      "quantity": "0.00001",
      "margin_mode": "isolated",
      "price_entry": "33386.18",
      "price_margin_call": "30415.27",
      "price_liquidation": "29803.76",
      "pnl": "0",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T01:49:51.003Z"
    }
    ],
    "report_type": "updated",
    "report_reason": "updated"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583593326663,
    "client_order_id": "2d42e072e4f34846954509c955303e13",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "32000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:48:21.882Z",
    "updated_at": "2021-07-02T01:49:51.003Z",
    "margin_mode": "isolated",
    "original_client_order_id": "2d42e072e4f34846954509c955303e12",
    "report_type": "replaced"
  },
  "id": 1239
}

Method: margin_replace_order

Changes the parameters of an existing margin order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`client_order_id`	String	Identifier of the order being replaced.
`new_client_order_id`	String	Optional. `client_order_id` for a new order. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`quantity`	Number	New order quantity.
`price`	Number	Optional. Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	Optional. The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`strict_validate`	Boolean	Optional. Price and quantity will be checked for the incrementation within tick size and quantity step. See symbol's `tick_size` and `quantity_increment`.

Get Margin Accounts

Request:

{
  "method": "margin_get_accounts",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "symbol": "ETHUSDT",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:20:25.118Z",
      "updated_at": "2021-07-01T21:20:25.118Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.002000000000",
          "reserved_orders": "0",
          "reserved_positions": "0"
        }
      ],
      "positions": null,
      "report_type": "status",
      "report_reason": "status"
    },
    {
      "symbol": "BTCUSDT",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T01:49:51.003Z",
        "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.080706742356",
          "reserved_orders": "0.029200000000",
          "reserved_positions": "0.030699895239"
        }
      ],
      "positions": [
        {
          "id": 485264,
          "symbol": "BTCUSDT",
          "quantity": "0.00001",
          "margin_mode": "isolated",
          "price_entry": "33386.18",
          "price_margin_call": "30415.27",
          "price_liquidation": "29803.76",
          "pnl": "0",
          "created_at": "2021-07-01T21:43:19.727Z",
          "updated_at": "2021-07-02T01:49:51.003Z"
        }
      ],
      "report_type": "status",
      "report_reason": "status"
    }
  ]
}

Method: margin_get_accounts

Returns a list of Margin Accounts with details about open positions.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create/Update Margin Account

Request:

{
  "method": "margin_set_account",
  "params": {
    "margin_balance": "0.07",
    "symbol": "BTCUSDT",
    "margin_mode": "isolated"
  },
  "id": 1234
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:54:46.636Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.070000000000",
        "reserved_orders": "0.029200000000",
        "reserved_positions": "0.030699895239"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "31568.60",
        "price_liquidation": "30933.90",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:54:46.636Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "marginChanged"
  },
  "id": 1234
}

Notification:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:54:46.636Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.070000000000",
        "reserved_orders": "0.029200000000",
        "reserved_positions": "0.030699895239"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "31568.60",
        "price_liquidation": "30933.90",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:54:46.636Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "marginChanged"
  }
}

Method: margin_set_account

Adds a margin for the specified symbol meaning creating the corresponding position of the entire margin value.

Setting margin balance to zero will lead to closing the margin account and return of all formerly reserved funds to the trading account.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Symbol code. Where base currency is the currency of funds reserved on the trading account for positions and quote currency is the currency of funds reserved on a margin account (e.g., `"BTCUSDT"`).
`margin_mode`	String	Margin mode. Accepted values: `isolated`, `cross`
`margin_balance`	Number	Amount of currency reserved.
`strict_validate`	Boolean	The value indicating whether the `margin_balance` is going to be checked for correct non-exponential format and currency precision.

Close Margin Position

Request:

{
  "method": "margin_close_position",
  "params": {
    "symbol": "BTCUSDT",
    "margin_mode": "isolated"
  },
  "id": 1243
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:57:21.752Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.070000000000",
        "reserved_orders": "0",
        "reserved_positions": "0.030741868625"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated"
        "price_entry": "33386.18",
        "price_margin_call": "28423.18",
        "price_liquidation": "27851.72",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:57:21.752Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "updated"
  },
  "id": 1243
}

Notification:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:57:21.752Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.067915777250",
        "reserved_orders": "0",
        "reserved_positions": "0"
      }
    ],
    "positions": null,
    "report_type": "closed",
    "report_reason": "closed"
  }
}

Method: margin_close_position

Closes a position for the specified symbol. This will result in canceling all open orders within the position.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Symbol code. Where base currency is the currency of funds reserved on the trading account for positions and quote currency is the currency of funds reserved on a margin account (e.g., `"BTCUSDT"`).
`margin_mode`	String	Optional. Margin mode. Accepted values: `isolated`, `cross` Default: `isolated`

Socket Futures Trading

Description

API provides the following tools to manage margin trading:

subscribe to the reports about:
- futures account changes;
- futures orders.
create futures account — reserve amount for margin trading per contract;
handle futures orders:
- list orders;
- place a new order;
- cancel an order;
- alter an order;
- cancel all orders.
close position.

Request

wscat -c wss://api.trade.mandala.exchange/api/3/ws/trading

{
  "method": "futures_subscribe",
  "params": {},
  "id": 123
}

Subscription result:

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 1234
}

Notification. Futures orders snapshot:

{
  "jsonrpc": "2.0",
  "method": "futures_orders",
  "params": [
    {
      "id": 583583708580,
      "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
      "symbol": "BTCUSDT_PERP",
      "side": "sell",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.00001",
      "quantity_cumulative": "0",
      "price": "80000.00",
      "post_only": false,
      "reduce_only": false,
      "created_at": "2021-07-02T01:32:15.732Z",
      "updated_at": "2021-07-02T01:32:15.732Z",
      "margin_mode": "isolated",
      "report_type": "status"
    },
    {
      "id": 583583708581,
      "client_order_id": "5c8c50cbf326488cb1d3415cd3e01387",
      "symbol": "BTCUSDT_PERP",
      "side": "sell",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.00001",
      "quantity_cumulative": "0",
      "price": "80000.00",
      "post_only": false,
      "reduce_only": false,
      "created_at": "2021-07-02T01:32:15.732Z",
      "updated_at": "2021-07-02T01:32:15.732Z",
      "margin_mode": "isolated",
      "report_type": "status"
    }
  ]
}

Notification. Futures order update:

{
  "jsonrpc": "2.0",
  "method": "futures_order",
  "params": {
    "id": 583583708580,
    "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
    "symbol": "BTCUSDT_PERP",
    "side": "sell",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "80000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:32:15.732Z",
    "updated_at": "2021-07-02T01:32:15.732Z",
    "margin_mode": "isolated",
    "report_type": "new"
  }
}

Notification. Futures trade:

{
  "jsonrpc": "2.0",
  "method": "futures_order",
  "params": {
    "id": 583583708580,
    "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
    "symbol": "BTCUSDT",
    "side": "sell",
    "status": "filled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0.00001",
    "price": "80000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:32:15.732Z",
    "updated_at": "2021-07-02T01:32:15.732Z",
    "margin_mode": "isolated",
    "trade_id": 1361988214,
    "trade_quantity": "0.00001",
    "trade_price": "49509.81",
    "trade_fee": "0.001237745250",
    "trade_position_id": 485308,
    "report_type": "trade"
  }
}

Notification. Futures accounts snapshot:

{
  "jsonrpc": "2.0",
  "method": "futures_accounts",
  "params": [
    {
      "symbol": "BTCUSDT_PERP",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T00:54:28.591Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.080706742356",
          "reserved_orders": "0",
          "reserved_positions": "0.029630234750"
        }
      ],
      "positions": [
        {
          "id": 485264,
          "symbol": "BTCUSDT_PERP",
          "quantity": "0.00001",
          "margin_mode": "isolated",
          "price_entry": "33386.18",
          "price_margin_call": "27269.85",
          "price_liquidation": "26721.57",
          "pnl": "0",
          "created_at": "2021-07-01T21:43:19.727Z",
          "updated_at": "2021-07-02T00:54:28.591Z"
        }
      ],
      "report_type": "status",
      "report_reason": "status"
    },
    {
      "symbol": "ETHUSDT_PERP",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T00:54:28.591Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.080706742356",
          "reserved_orders": "0",
          "reserved_positions": "0.029630234750"
        }
      ],
      "positions": null,
      "report_type": "status",
      "report_reason": "status"
    }
  ]
}

Method: futures_subscribe, futures_unsubscribe

Income method: futures_order, futures_orders

Requires the "Orderbook, History, Trading balance" API key Access Right.

Fields:

Name	Type	Description
`id`	Number	Unique order identifier as assigned by exchange.
`client_order_id`	String	Unique order identifier as assigned by the trader.
`symbol`	String	Contract code.
`side`	String	Trade side. Accepted values: `sell`, `buy`
`status`	String	Order state. Possible values: `new` — an order is placed in the order book. `suspended` — a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book. `partiallyFilled` — an order is executed, but a part of its quantity is not filled yet. `filled` — (in updates) order quantity filled completely. `canceled` — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `expired` — (in updates) an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
`type`	String	Order type. Possible values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`
`time_in_force`	String	Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired. `GTC` — "Good-Till-Canceled" order won't be closed until it is filled. `IOC` — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled. `FOK` — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all. `Day` — keeps the order active until the end of the trading day (23:59 UTC+0). `GTD` — "Good-Till-Date" order may remain active until the time specified in `expire_time`.
`quantity`	Number	Order quantity.
`price`	Number	Order price.
`cum_quantity`	Number	Cumulative executed quantity.
`post_only`	Boolean	A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
`created_at`	DateTime	Report creation date.
`updated_at`	DateTime	Date of the report's last update.
`margin_mode`	String	Margin mode. Possible values: `isolated`, `cross`
`stop_price`	Number	Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
`expire_time`	DateTime	Date of order expiration for `time_in_force` equal to `GTD`.
`original_client_order_id`	String	Identifier of replaced order.
`trade_id`	Number	Trade identifier. Required if `report_type` is `trade`.
`trade_quantity`	Number	Quantity of trade. Required if `report_type` is `trade`.
`trade_price`	Number	Trade price. Required if `report_type` is `trade`.
`trade_fee`	Number	Fee paid for trade. Required if `report_type` is `trade`.
`trade_taker`	Boolean	Liquidity indicator. Required if `report_type` is `trade`.
`trade_position_id`	Number	Position identifier of the trade.
`report_type`	String	Report type. Possible values: `status` — (in snapshots) the record of an event occurred during the last snapshot period. `new` — (in updates) an order has been placed in the order book (`status` is `new`). `suspended` — (in updates) a `stopLimit`, `stopMarket`, `takeProfitLimit` or `takeProfitMarket` order is parked until it meets the conditions for placement in the order book (`status` is `suspended`). `canceled` — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances. `rejected` — (in updates) order request has been rejected (it is applicable exclusively to a request entry, so the `status` of the related canceled/replaced order will not change — i.e., it cannot be different from `new`, `suspended`, `partiallyFilled`). `status` is `rejected`. `expired` — (in updates) an order is deactivated as it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements (`status` is `expired`). `replaced` — (in updates) an order cancel/replace request has been accepted and successfully processed (`status` is `canceled`, a new order placed instead has the `new` status value). `trade` — (in updates) an order has been fully or partially executed (`status` is `filled` or `partiallyFilled`).

Income method: futures_account, futures_accounts

Fields:

Name	Type	Description
`symbol`	String	Contract code (e.g., `"BTCUSDT_PERP"`).
`type`	String	Type of margin. Only `isolated`.
`leverage`	Number	Margin leverage. The ratio of the trader's own funds to funds borrowed from the platform.
`created_at`	DateTime	Account creation date and time.
`updated_at`	DateTime	Account last update date and time.
`currencies`	Currency	Amount of funds on Margin Account.
`positions`	Position	Optional. Open positions of the Margin Account.
`report_type`	String	Report type. Possible values: `status` — status of margin account requested, e.g., subscription report with a list of current margin accounts. `created` — new margin account created or position, e.g., new margin account requested or a flip trade occurs with position. `updated` — margin account or position updated. `closed` — margin account closed.
`report_reason`	String	Report reason. Possible values: `status`, `created`, `updated`, `marginChanged`, `openTrade`, `closeTrade`, `flipTrade`, `closed`, `reopened`, `liquidated`, `liquidationTrade`, `interestTaken`, `fundingTaken`, `deleveraged`, `deleverageTrade`.

Currency model consists of:

Name	Type	Description
`code`	String	Currency code.
`margin_balance`	Number	The total value of funds reserved for the position.
`reserved_orders`	Number	The value reserved for active orders in the position.
`reserved_positions`	Number	The minimum value reserved for position's executed quantity that cannot be reduced.

Report type values:

Status	Description
`status`	Status of futures account requested, e.g., get accounts or subscription report with a list of current futures accounts.
`created`	A new futures account created, e.g., new futures account has been created or recreated as a result of flip trade occurs with the position.
`updated`	Futures account or position has been updated.
`closed`	Futures account has been closed.

Report reason values:

Status	Description
`status`	Response to an account information request.
`created`	Position has been created.
`updated`	Position account has been changed as a result of any order report, e.g., `new`, `canceled`, `filled`, and so on.
`marginChanged`	Futures account has been changed as a result of any requested change of the `margin_balance`.
`openTrade`	Opening trade has been executed.
`closeTrade`	Closing trade has been executed.
`flipTrade`	The position has been flipped as a result of the opposite order execution with a quantity exceeding the position quantity (quantity has changed sign).
`closed`	The position quantity has been set to `"0"` (zero) as a result of the closing trade.
`liquidated`	The position has been liquidated.
`liquidationTrade`	Liquidation order has been placed.
`fundingTaken`	The interest rate has been paid.
`deleveraged`	The position has changed because of ADL activation.

Get Active Futures Orders

Notification report

{
  "jsonrpc": "2.0",
  "result": [
    {
      "id": 583583708580,
      "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
      "symbol": "BTCUSDT_PERP",
      "side": "sell",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.00001",
      "quantity_cumulative": "0",
      "price": "80000.00",
      "post_only": false,
      "reduce_only": false,
      "created_at": "2021-07-02T01:32:15.732Z",
      "updated_at": "2021-07-02T01:32:15.732Z",
      "margin_mode": "isolated",
      "report_type": "status"
    }
  ],
  "id": 1234
}

Method: futures_get_orders

Returns the user's active orders.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Place New Futures Order

Request:

{
  "method": "futures_new_order",
  "params": {
    "symbol": "BTCUSDT_PERP",
    "side": "buy",
    "quantity": "0.00001",
    "price": "30000",
    "client_order_id": "2d42e072e4f34846954509c955303e11"
  },
  "id": 1238
}

Notification. Futures Order report:

{
  "jsonrpc": "2.0",
  "method": "futures_order",
  "params": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "margin_mode": "isolated",
    "report_type": "new"
  }
}

Notification. Futures Account report:

{
  "jsonrpc": "2.0",
  "method": "futures_account",
  "params": {
    "symbol": "BTCUSDT_PERP",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.080706742356",
        "reserved_orders": "0.027375000000",
        "reserved_positions": "0.049647514286"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT_PERP",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "30218.68",
        "price_liquidation": "29611.12",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:41:07.18Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "updated"
  }
}

Success response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "margin_mode": "isolated",
    "report_type": "new"
  },
  "id": 1238
}

Example error response:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  },
  "id": 123
}

Method: futures_new_order

Creates a new Futures order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`client_order_id`	String	Optional. Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`symbol`	String	Contract code.
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Must be set to `market`, `stopMarket`, or `takeProfitMarket` if `price` was left unspecified. Accepted values: `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket` Default value: `limit`
`time_in_force`	String	Optional. Accepted values: `GTC`, `IOC`, `FOK`, `Day`, `GTD` Default value: `FOK` — `type` is `market`, `stopMarket`, `takeProfitMarket`; `GTC` — `type` is `limit`, `stopLimit`, `takeProfitLimit`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required for limit types.
`stop_price`	Number	Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
`expire_time`	DateTime	Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol's tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise. Default: `false` Conditions: `quantity` is omitted.
`margin_mode`	String	Optional. Margin mode. Accepted values: `isolated`, `cross` Default: `isolated`

Create New Futures Order List

Request:

{
  "method": "futures_new_order_list",
  "params": {
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "orders": [
      {
        "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
        "symbol": "ETHBTC_PERP",
        "side": "buy",
        "type": "limit",
        "time_in_force": "GTC",
        "quantity": "0.063",
        "price": "0.046016",
        "reduce_only": false,
        "post_only": false
      },
      {
        "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
        "symbol": "ETHBTC_PERP",
        "side": "sell",
        "type": "stopMarket",
        "time_in_force": "GTC",
        "quantity": "0.063",
        "stop_price": "0.044050",
        "price": "0.044016",
        "reduce_only": false,
        "post_only": false
      }
    ]
  },
  "id": 123
}

Success response:

{
  "jsonrpc": "2.0",
  "result":
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z",
    "margin_mode": "isolated"
  }
  "id": 123
}

{
  "jsonrpc": "2.0",
  "result":
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z",
    "margin_mode": "isolated"
  }
  "id": 123
}

Example error response:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  },
  "id": 123
}

Method: futures_new_order_list

Creates a new futures order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`order_list_id`	String	Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to `client_order_id` of the first order in the request.
`contingency_type`	String	Order list type. Accepted values: `oneCancelOther` (OCO) — all orders in the set should be canceled if one of them was executed; `oneTriggerOther` (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other; `oneTriggerOneCancelOther` (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
`orders`	[]Order	Orders in the list. There must be 2 or 3 orders for `allOrNone`/`oneCancelOther`/`oneTriggerOther` and 3 — for `oneTriggerOneCancelOther`. Placing any other number of orders will result in an error.

Order model consists of:

Name	Type	Description
`client_order_id`	String	Optional. Must be different from the identifiers of other orders in the list. If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`symbol`	String	Symbol code. Must be the same for all orders in an `oneTriggerOneCancelOther` order list (placing orders in different order books is not supported).
`side`	String	Trade side. Accepted values: `sell`, `buy`
`type`	String	Optional. Order type. Accepted values: for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `limit`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`; for `oneTriggerOneCancelOther` — `limit`, `market`, `stopLimit`, `stopMarket`, `takeProfitLimit`, `takeProfitMarket`. Default value: `limit`
`time_in_force`	String	Optional. Time in Force instruction. Accepted values: for `oneCancelOther` (and secondary orders in `oneTriggerOneCancelOther`) — `GTC`, `IOC` (except `limit` orders), `FOK` (except `limit` orders), `Day`, `GTD`; for `oneTriggerOneCancelOther` — `GTC`, `IOC`, `FOK`, `Day`, `GTD`.
`quantity`	Number	Order quantity.
`price`	Number	Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	The price level that triggers order activation. Required if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`expire_time`	DateTime	Date of order expiration. Required if `time_in_force` is `GTD`.
`strict_validate`	Boolean	Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's `tick_size` and `quantity_increment`.
`post_only`	Boolean	Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
`reduce_only`	Boolean	Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
`close_position`	Boolean	Flag indicating a stop market order must close a margin position when executed or be canceled otherwise. Default: `false` Conditions: `quantity` is omitted.
`margin_mode`	String	Optional. Margin mode. Accepted values: `isolated`, `cross` Default: `isolated`

Cancel Futures Order

Request:

{
  "method": "futures_cancel_order",
  "params": {
    "client_order_id": "2d42e072e4f34846954509c955303e11"
  },
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT_PERP",
    "side": "buy",
    "status": "canceled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:46:06.016Z",
    "margin_mode": "isolated",
    "report_type": "canceled"
  },
  "id": 1240
}

Method: futures_cancel_order

Cancels an existing order.

Cancel/Replace a Futures Order

Request:

{
  "method": "futures_replace_order",
  "params": {
    "quantity": "0.00001",
    "price": "32000",
    "client_order_id": "2d42e072e4f34846954509c955303e12",
    "new_client_order_id": "2d42e072e4f34846954509c955303e13"
  },
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583593326663,
    "client_order_id": "2d42e072e4f34846954509c955303e13",
    "symbol": "BTCUSDT_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "32000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:48:21.882Z",
    "updated_at": "2021-07-02T01:49:51.003Z",
    "margin_mode": "isolated",
    "original_client_order_id": "2d42e072e4f34846954509c955303e12",
    "report_type": "replaced"
  },
  "id": 1239
}

The Cancel/Replace request is used to change the parameters of an existing order or to revise the quantity or price attribute of an open order.

Do not use this request to cancel the quantity remaining in an outstanding order. Use the Cancel request message for this purpose.

It is stipulated that a newly entered order cancels a prior order that has been entered but not yet executed.

Method: futures_replace_order

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`client_order_id`	String	Identifier of the order being replaced.
`new_client_order_id`	String	Optional. `client_order_id` for a new order. Uniqueness must be guaranteed until the last order with the same `client_order_id` becomes inactive (canceled, expired, or fully executed) and some time after that.
`quantity`	Number	New order quantity.
`price`	Number	Optional. Order price. Required if `type` is `limit`, `stopLimit`, or `takeProfitLimit`.
`stop_price`	Number	Optional. The price level that triggers order activation. Specified if `type` is `stopLimit`, `stopMarket`, `takeProfitLimit`, or `takeProfitMarket`.
`strict_validate`	Boolean	Optional. Price and quantity will be checked for the incrementation within tick size and quantity step. See symbol's `tick_size` and `quantity_increment`.

Cancel Futures Order

Request:

{
  "method": "futures_cancel_order",
  "client_order_id": "2d42e072e4f34846954509c955303e11",
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "method": "futures_order",
  "params": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT_PERP",
    "side": "buy",
    "status": "canceled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:46:06.016Z",
    "margin_mode": "isolated",
    "report_type": "canceled"
  }
}

Method: futures_cancel_order

Cancels an active futures order.

Requires the "Place/cancel orders" API key Access Right.

Get Futures Accounts

Request:

{
  "method": "futures_get_accounts",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "symbol": "ETHUSDT_PERP",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:20:25.118Z",
      "updated_at": "2021-07-01T21:20:25.118Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.002000000000",
          "reserved_orders": "0",
          "reserved_positions": "0"
        }
      ],
      "positions": null,
      "report_type": "status",
      "report_reason": "status"
    },
    {
      "symbol": "BTCUSDT_PERP",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T01:49:51.003Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.080706742356",
          "reserved_orders": "0.029200000000",
          "reserved_positions": "0.030699895239"
        }
      ],
      "positions": [
        {
          "id": 485264,
          "symbol": "BTCUSDT_PERP",
          "quantity": "0.00001",
          "margin_mode": "isolated",
          "price_entry": "33386.18",
          "price_margin_call": "30415.27",
          "price_liquidation": "29803.76",
          "pnl": "0",
          "created_at": "2021-07-01T21:43:19.727Z",
          "updated_at": "2021-07-02T01:49:51.003Z"
        }
      ],
      "report_type": "status",
      "report_reason": "status"
    }
  ]
}

Method: futures_get_accounts

Returns a list of futures accounts with details about open positions.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create/Update Futures Account

Request:

{
  "method": "futures_set_account",
  "params": {
    "margin_balance": "10.00",
    "symbol": "BTCUSDT_PERP",
    "leverage": "100",
    "margin_mode": "isolated"
  },
  "id": 1234
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "symbol": "BTCUSDT_PERP",
    "type": "isolated",
    "leverage": "100.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:54:46.636Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.070000000000",
        "reserved_orders": "0.029200000000",
        "reserved_positions": "0.030699895239"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT_PERP",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "31568.60",
        "price_liquidation": "30933.90",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:54:46.636Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "marginChanged"
  },
  "id": 1234
}

Method: futures_set_account

Adds a margin for the specified symbol meaning creating the corresponding position of the entire margin value.

Setting margin balance to zero will lead to closing the futures account and return of all formerly reserved funds to the trading account.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Contract code (e.g., `"BTCUSDT_PERP"`).
`margin_mode`	String	Margin mode. Accepted values: `isolated`, `cross`
`margin_balance`	Number	Amount of currency reserved.
`leverage`	Number	Optional. The ratio of borrowed funds to trader's initial margin.
`strict_validate`	Boolean	The value indicating whether the `margin_balance` is going to be checked for correct non-exponential format and currency precision.

Close Futures Position

Request:

{
  "method": "futures_close_position",
  "params": {
    "symbol": "BTCUSDT_PERP"
  },
  "id": 1243
}

Notification:

{
  "jsonrpc": "2.0",
  "method": "futures_account",
  "params": {
    "symbol": "BTCUSDT_PERP",
    "type": "isolated",
    "leverage": "100.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:57:21.752Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.067915777250",
        "reserved_orders": "0",
        "reserved_positions": "0"
      }
    ],
    "positions": null,
    "report_type": "closed",
    "report_reason": "closed"
  }
}

Method: futures_close_position

Closes a position for the specified symbol. This will result in canceling all open orders within the position.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name	Type	Description
`symbol`	String	Symbol code. Where base currency is the currency of funds reserved on the trading account for positions and quote currency is the currency of funds reserved on a margin account (e.g., `"BTCUSDT"`).
`margin_mode`	String	Optional. Margin mode. Accepted values: `isolated`, `cross` Default: `isolated`

Request

{
  "method": "futures_balance_subscribe",
  "params": {
    "mode": "updates"
  },
  "id": 123
}

Subscription result:

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 123
}

Notification Spot balance

{
  "jsonrpc": "2.0",
  "method": "futures_balance",
  "params": [
    {
      "currency": "BCN",
      "available": "100.000000000000",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "BTC",
      "available": "0.013634021",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "ETH",
      "available": "0",
      "reserved": "0.00200000",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    }
  ]
}

Method: futures_balance_subscribe, futures_balance_unsubscribe

Income methods: futures_balance

Subscribes to user's balances.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name	Type	Description
`mode`	String	Subscription mode. Accepted values: `updates` — messages arrive after balance updates. `batches` — messages arrive at equal intervals if there were any updates.

Response:

Name	Type	Description
`currency`	String	Currency code.
`available`	Number	Amount available for trading or transfer to wallet.
`reserved_margin`	Number	Amount reserved for margin trading.
`cross_margin_reserved`	Number	Amount reserved for margin trading funded by a cross–margin account.
`reserved`	Number	Total amount reserved for active orders and incomplete transfers to wallet.

Get Futures Trading Balances

Request:

{
  "method": "futures_balances",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "currency": "BCN",
      "available": "100.000000000",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "BTC",
      "available": "0.013634021",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "ETH",
      "available": "0",
      "reserved": "0.00200000",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    }
  ],
  "id": 123
}

Method: futures_balances

Returns all non-zero trading balances.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Futures Trading Balance

Request:

{
  "method": "futures_balance",
  "params": {
    "currency": "USDT"
  },
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "currency": "USDT",
    "available": "100.000000000",
    "reserved": "0",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  },
  "id": 123
}

Method: futures_balance

Returns trading balance for a single currency.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Futures Fees

Request:

{
  "method": "futures_fees",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "symbol": "BTCUSDT_PERP",
      "take_rate": "0.001",
      "make_rate": "-0.0001"
    },
    {
      "symbol": "ETHBTC_PERP",
      "take_rate": "0.001",
      "make_rate": "-0.0001"
    }
  ],
  "id": 123
}

Method: futures_fees

Returns fees for all available symbols.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Futures Fee

Request:

{
  "method": "futures_fee",
  "params": {
    "symbol": "BTCUSDT_PERP"
  },
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "symbol": "BTCUSDT_PERP",
      "take_rate": "0.001",
      "make_rate": "-0.0001"
    }
  ],
  "id": 123
}

Method: futures_fee

Returns fee for the contract specified.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Socket Wallet Management

Description

WebSocket Account API uses the same authorization approach as described in the Socket Session Authentication section.

API provides the following tools to manage a general account:

a subscription to the transactions:
- any sequenced transaction changes such as creating or updating.
a balance request;
a transaction history request.

Method: subscribe_transactions and the corresponding unsubscription method: unsubscribe_transactions

Income method: transaction_update

A full transaction model description can be found in the "Get Transactions History" section.

A subscription to the transactions has to be used rather than the transaction polling.

A transaction notification occurs each time the transaction has been changed, such as creating a transaction, updating the pending state (e.g., the hash assigned) or completing a transaction. This is the easiest way to track deposits or develop real-time asset monitoring.

Subscription request:

wscat -c wss://api.trade.mandala.exchange/api/3/ws/wallet

{
  "method": "subscribe_transactions",
  "params": {},
  "id": 7652
}

Subscription result:

{
  "result": true,
  "id": 7652
}

Notification. Updated Transaction:

{
  "method": "transaction_update",
  "params": {
    "id": 50844835,
    "created_at": "2024-04-22T21:03:04.111Z",
    "updated_at": "2024-04-22T21:04:41.487Z",
    "status": "SUCCESS",
    "type": "WITHDRAW",
    "subtype": "BLOCKCHAIN",
    "native": {
      "tx_id": "27fa7f14-ca49-42fd-834a-4ce630d069d2",
      "index": 1071885589,
      "currency": "ETH",
      "amount": "0.01042",
      "fee": "0.00958",
      "hash": "0xfb0ba568213d11230cd34d62fddd1cc1fe11fdc173l4f2007b0e47a06ad73d20",
      "address": "0xd959463c3fcb222124bb7bb642d6a6573a6c5aba",
      "confirmations": 20
    },
    "operation_id": "99e78bf4-a708-43a3-ab18-e8e7618cd891"
  }
}

Method: subscribe_wallet_balances and the corresponding unsubscription method: unsubscribe_wallet_balances

Income methods: wallet_balances, wallet_balance_update

This subscription aims to provide an easy way to be informed of the current balance state.

If the state has been changed or potentially changed, the wallet_balance_update event will come with the actual state.

Please be aware that only non-zero values are present.

Event wallet_balances arrives after each successful subscription.

Subscription request:

{
  "method": "subscribe_wallet_balances",
  "params": {},
  "id": 7653
}

Subscription result:

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 7653
}

Notification. Balance snapshot:

{
  "jsonrpc": "2.0",
  "method": "wallet_balances",
  "params": [
    {
      "currency": "BTC",
      "available": "0.00005821",
      "reserved": "0"
    },
    {
      "currency": "ETH",
      "available": "11",
      "reserved": "0"
    }
  ]
}

Notification. Balance update:

{
  "jsonrpc": "2.0",
  "method": "wallet_balance_update",
  "params": {
    "currency": "BTC",
    "available": "0.10005821",
    "reserved": "0"
  }
}

Request Wallet Balance

Request:

{
  "method": "wallet_balances",
  "params": {},
  "id": 5543
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "currency": "BTC",
      "available": "0.00005821",
      "reserved": "0"
    },
    {
      "currency": "ETH",
      "available": "11",
      "reserved": "0"
    }
  ],
  "id": 5543
}

Request:

{
  "method": "wallet_balance",
  "params": {
    "currency": "BTC"
  },
  "id": 5543
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "currency": "BTC",
    "available": "0.00005821",
    "reserved": "0"
  },
  "id": 5543
}

Methods: wallet_balances, wallet_balance

Get all wallet balances or balance for a single asset.

Please note that the method returns non-zero balances only.

Get Transactions

Request:

{
  "method": "transactions",
  "params": {
    "limit": 10,
    "offset": 0,
    "sort": "desc",
    "from": "2020-01-31T00:00:00.000Z",
    "till": "2021-07-31T22:33:00.555Z",
    "statuses": "SUCCESS",
    "currencies": "ETH,BTC"
  },
  "id": 7655
}

Response:

{
  "jsonrpc": "2.0",
  "result":
  [
    {
      "id": 18155514,
      "created_at": "2023-05-31T05:40:38.732Z",
      "updated_at": "2023-05-31T05:40:38.77Z",
      "last_activity_at": "2024-04-30T15:42:12.274495Z",
      "status": "SUCCESS",
      "type": "TRANSFER",
      "subtype": "WALLET_TO_SPOT",
      "native":
      {
        "tx_id": "7a04e62c-563c-4797-8eeb-ea8e3fa354d3",
        "index": 153796572,
        "currency": "USDT",
        "amount": "0.01"
      },
      "operation_id": "55b58d62-959d-2b96-51b1-035f87e55885"
    },
    {
      "id": 716817,
      "created_at": "2024-04-12T11:34:00.766Z",
      "updated_at": "2024-04-12T11:43:59.88Z",
      "last_activity_at": "2024-04-30T15:42:12.274495Z",
      "status": "PENDING",
      "type": "WITHDRAW",
      "subtype": "BLOCKCHAIN",
      "native":
      {
        "tx_id": "80f890f7-7f49-4d69-af39-73d1ee539663",
        "index": 94582527,
        "currency": "BTC",
        "amount": "0.001",
        "fee": "0.00146454",
        "address": "3E8WKmTJzaTsBc4",
        "confirmations": 0
      }
    },
    {
      "id": 36497,
      "created_at": "2024-04-19T13:10:16.238Z",
      "updated_at": "2024-04-19T13:10:16.245Z",
      "status": "SUCCESS",
      "type": "DEPOSIT",
      "subtype": "UNCLASSIFIED",
      "native":
      {
        "tx_id": "cda7121b-de8f-4554-8ba7-c6beabfd9a88",
        "index": 44204086,
        "currency": "BTC",
        "amount": "0.2"
      }
    }
  ],
  "id": 1408
}

Method: transactions

All parameters are optional.

Parameters:

Name	Type	Description
`from`	DateTime	Interval initial value (inclusive). The value type depends on `order_by`.
`till`	DateTime	Interval end value (inclusive). The value type depends on `order_by`.
`types`	String	Comma-separated transaction types.
`subtypes`	String	Comma-separated transaction subtypes.
`statuses`	String	Comma-separated transaction statuses. Accepted values: `CREATED`, `PENDING`, `FAILED`, `SUCCESS`, `ROLLED_BACK`
`currencies`	String	Comma-separated currency codes.
`id_from`	Number	Index interval initial value. Accepted values: `0` or greater
`id_till`	Number	Index interval end value. Accepted values: `0` or greater
`tx_ids`	String	Comma-separated transaction identifiers.
`order_by`	String	The field the entries sorted by. Accepted values: `id`, `created_at`, `updated_at`, `last_activity_at`, `ID`, `CREATED_AT`, `UPDATED_AT`, `LAST_ACTIVITY_AT` Default value: `created_at` Cannot be `id` or `ID` if `from` and (or) `till` are provided.
`sort`	String	Sort direction. Accepted values: `DESC`, `ASC` Default value: `DESC`
`limit`	Number	Default value: `100` Maximum value: `1000`
`offset`	Number	Default value: `0` Maximum value: `100000`
`group_transactions`	Boolean	Flag indicating whether the returned transactions will be parts of a single operation. Default value: `false`

For response fields, refer to description of GET /api/3/wallet/transactions endpoint.

Errors

The same set of custom error codes is applicable to both REST and Socket APIs.

Market Data

Custom code	HTTP status code	Reason
`2002`	`400`	Provided currency or symbol not found.
`10001`	`400`	Any of: - missing required parameter; - invalid value of a numeric parameter.

Authentication

Custom code	HTTP status code	Reason
`1002`	`401`	Any of: - invalid API key; - user is not allowed to perform the requested operation.
`1002`	`401`	Any of: - invalid API key; - user is not allowed to perform the requested operation; - invalid time window value; - invalid HMAC signature format; - invalid HMAC signature value.
`1004`	`401`	Provided parameters do not meet any supported authentication scheme.
`1004`	`401`	Any of: - missing required parameters; - the maximum time window is exceeded.

Trading

Custom code	HTTP status code	Reason
`500`	`500`	Unclassified internal error.
`500`	`500`	Any of: - the position symbol is not found when returning the response; - a margin balance currency is not found when returning the response.
`2024`	`400`	Invalid margin mode.
`10025`	`400`	No margin account for a given instrument is found.
`20032`	`400`	Requested position is not open (has `0` quantity).
`20034`	`400`	The position price has reached the margin-call mark and open orders are no longer allowed.
`20040`	`400`	Margin trading is forbidden for the user. Any of: - the user is not found; - user verification level does not allow margin trading; - the user is suspected of fraudulent activity.
`20041`	`400`	The value of the order exceeds the margin isolated for the position.
`20042`	`400`	The value of the existing order exceeds the margin isolated for the position.
`20047`	`400`	Order placing exceeds the central counterparty balance limit.
`20048`	`400`	Provided Time-In-Force instruction is invalid or the combination of the instruction and the order type is not allowed.
`20049`	`400`	Provided order type is invalid.
`10024`	`400`	Invalid leverage value.
`504`	`504`	Operation has expired before completion.
`504`	`504`	Operation was canceled.
`1003`	`403`	Any of: - insufficient API key permissions; - provided IP address is not in the white list; - the user is not eligible for the given liquidity pool due to the configuration.
`1003`	`403`	The user is not allowed to place new orders in the given market.
`2001`	`400`	The symbol featured in the request has not been found.
`2002`	`400`	Provided currency has not been found. Any of: - the currency is disabled; - the currency is unavailable for a given market.
`2010`	`400`	Invalid quantity value. Any of: - quantity is not a decimal with a dot as the separator; - maximum bit depth is exceeded.
`2011`	`400`	Quantity is less or equal to zero or the quantity increment.
`2012`	`400`	Invalid quantity format.
`2016`	`400`	Orders in the order list are on symbols that are unacceptable in combination for the given type. Any of: - for `allOrNone`—all symbols must be different; - for `oneTriggerOneCancelOther`—all symbols must be the same.
`2017`	`400`	The number of an order in the order list violates the conditions for its contingency type.
`2020`	`400`	Invalid price value. Any of: - price is not a decimal with a dot as the separator; - maximum bit depth is exceeded; - price is less or equal to zero.
`2022`	`400`	Invalid price format.
`10001`	`400`	Any of: - invalid JSON payload; - invalid form payload; - specified parameters are mutually exclusive; - a required parameter is missing; - the value of a parameter is invalid; - pair parameters have different formats; - provided value does not match the currency precision while the strict-validate mode is enabled.
`10021`	`404`	User is disabled.
`20002`	`400`	Canceled or replaced order has not been found or the user has no active or parked orders.
`20003`	`400`	Turnover limit is exceeded meaning trading is disabled for the user.
`20008`	`400`	Provided client order identifier is user in an active order or has been used lately.
`20009`	`400`	Provided parameters for a new order are the as of the replaced one.
`20010`	`400`	Trades on the given symbol are suspended.
`20044`	`400`	Trading on the requested market is not available.
`20045`	`400`	Fat finger limit is exceeded. If a replace request is rejected, it cancels the original order without placing a new one.
`20046`	`400`	Trades on the given symbol are suspended.
`20080`	`400`	The order met its expiration time before it might be processed.

Wallet Management

Custom code	HTTP status code	Reason
`503`	`503`	Any of: - swaps are disabled; - swaps are unavailable.
`400`	`400`	Swaps from the source currency are disabled.
`400`	`400`	Swaps from the target currency are disabled.
`400`	`400`	Provided amount is below the limit.
`400`	`400`	Provided amount is above the limit.
`400`	`400`	The amount of operation exceeds a daily, hourly, weekly, or monthly limit.
`400`	`400`	Available balance is insufficient for execution of the operation.
`400`	`400`	Swaps on the provided currency pair are not supported.
`10001`	`400`	Provided currencies cannot be swapped because there is no way to exchange via intermediate pair.
`10001`	`400`	Market depth is insufficient for producing a rate.
`10001`	`400`	OTC trade will be unlikely executed due to high market volatility.
`400`	`400`	The rate under the provided rate identifier is no longer valid.
`400`	`400`	Invalid request body.
`408`	`408`	The request has been canceled.
`429`	`429`	Rate limits are exceeded.
`500`	`500`	Internal error. Any of: - unclassified internal error; - user bank account is blocked; - transaction(s) for the requested operation have not been created; - transaction(s) for the requested operation have been rolled back.
`500`	`500`	Funds needed for execution of the operation are locked.
`502`	`502`	Unclassified error while connecting the authentication service.
`503`	`503`	Any of: - withdrawals are disabled; - unclassified internal error.
`600`	`400`	Operations on the requested currency are not allowed. Any of: - currency is disabled; - operations of the given type are disabled for the currency; - operations on the needed account types are disabled for the currency; - conversion is not allowed for the provided currencies.
`602`	`400`	User is in the blacklist and can no longer make withdrawals.
`604`	`400`	Operation amount in total with locked amount exceeds available balance.
`1003`	`403`	Any of: - currency settings forbid the requested operation; - the user has insufficient permissions for the operation; - requested operation is forbidden for the user; - insufficient API key permissions; - provided IP address is not in the white list; - the user is not eligible for the given currency by the configuration; - provided operation parameters are forbidden by the configuration; - a withdrawal operation failed to pass pre-AML checks.
`22001`	`400`	Acquiring provider is not set up for a broker.
`1006`	`403`	Current permission scope in the authentication service is insufficient.
`1007`	`403`	Current permission scope in the authentication service is insufficient.
`2002`	`400`	Currency is not found. Any of: - requested network is not found; - requested currency is not found; - no currency provided while the network is specified; - requested network is disabled; - operations relating to the request are disabled for the currency; - currencies featured in an operation are not found.
`10001`	`400`	Any of: - invalid JSON payload; - invalid form payload; - invalid payload format; - invalid parameter value; - invalid parameter format; - specified parameters are mutually exclusive; - a required parameter is missing; - the value of a parameter is invalid; - provided value is not unique; - in an update request, no parameters provided.
`10001`	`400`	Operation amount is too low. Any of: - provided amount is lesser than the currency precision (bit depth); - fees are included in the final amount, and the amount is lesser than fees.
`20001`	`400`	Available balance is insufficient for execution of the operation.
`20003`	`400`	The amount of operation exceeds a daily, hourly, weekly, or monthly limit.
`20004`	`404`	Any of: - a transaction has failed to create; - the requested transaction is not found.
`20005`	`400`	The requested withdrawal is not found.
`20006`	`400`	Transaction associated with the operation was complete before being committed or rolled back.
`20007`	`400`	Transaction associated with the operation has been rolled-back or failed.
`20011`	`400`	Receiver deposit address has an invalid format.
`20012`	`400`	Any of: - an internal transfer recipient did not complete the registration; - recipient payment identifier is of an invalid format.
`20014`	`400`	The internal transfer is directed to the sender of the request. Any of: - off-chain operations are disabled; - the receiver is not a valid target for an off-chain operation.
`20018`	`400`	Withdrawals are unavailable due to the current configuration. Any of: - internal withdrawals are disabled; - in-chain withdrawals are disabled.
`22004`	`404`	User is not found.
`22008`	`504`	Gateway timeout exceeded.
`20090`	`403`	Verification level is insufficient for the given operation.