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
andtill
filters are optional now; - added new filters:
order_by
andsort
.
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
andGET /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
.
- added
POST /api/3/wallet/crypto/withdraw
:- added
network_code
request body field.
- added
GET /api/3/wallet/transactions
:- added
networks
request parameter; - added
network_code
response field innative
object; - added
protocol_code
response field innative
object.
- added
GET /api/3/wallet/crypto/address
:- added
network_code
request parameter; - added
network_code
response field.
- added
POST /api/3/wallet/crypto/address
:- added
network_code
request body field; - added
network_code
response field.
- added
GET /api/3/wallet/crypto/address/recent-deposit
:- added
network_code
request parameter; - added
network_code
response field.
- added
GET /api/3/wallet/crypto/address/recent-withdraw
:- added
network_code
request parameter; - added
network_code
response field.
- added
GET /api/3/wallet/crypto/fee/estimate
:- added
network_code
request parameter.
- added
GET /api/3/wallet/crypto/fee/levels
:- added
network_code
request parameter.
- added
GET /api/3/buy-crypto/provider/{provider_id}/order
:- added
network_code
request body field.
- added
POST /api/3/buy-crypto/provider/{provider_id}/order
:- added
target_network_code
request parameter.
- added
POST /api/3/wallet/crypto/fees/estimate
:- added
network_code
request body field; - added
networkCode
response field.
- added
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 bysubscribe_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 socketmargin_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 socketfutures_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¤cy=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
orto_currency
.
API call: POST /api/3/wallet/swap/rate/fixed - Calculate the value of
expected_price
asamount_from
divided byamount_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, ornull
value if included. If it is not included it is assumed to be a notification. The value SHOULD NOT benull
.
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.
Subscribe to Trades
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) |
Subscribe to Candles
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) |
Subscribe to Converted Candles
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) |
Subscribe to Price Rates
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. |
Subscribe to Price Rates in Batches
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. |
Subscribe to Mini Ticker
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. |
Subscribe to Mini Ticker in Batches
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. |
Subscribe to Ticker
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. |
Subscribe to Ticker in Batches
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. |
Subscribe to Full Order Book
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. |
Subscribe to Partial Order Book
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. |
Subscribe to Partial Order Book in Batches
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. |
Subscribe to Top of Book
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. |
Subscribe to Top of Book in Batches
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. |
Subscribe to Futures Information
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
Subscribe to Reports
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.
Subscribe to Spot Balances
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.
Subscribe to Reports
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.
Subscribe to Reports
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 |
Subscribe to Futures Balances
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.
Subscribe to Transactions
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"
}
}
Subscribe to Wallet Balances
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. |