English
NAV
console python

Authentication

Private endpoints require authentication; public endpoints do not.

Authenticated Endpoint Parameters

For advanced network diagnostics, include cdn-request-id in your request headers. Ensure each value is unique per request. Use these parameters for authentication: |

Ensure the timestamp follows this rule: server_time - recv_window <= timestamp < server_time + 1000. Here, server_time refers to Mufex server time.

1. Construct: timestamp + api-key + [recv_window] + [queryString(order not needed) | jsonBodyString]

2. Sign the constructed string from step 1 using HMAC_SHA256, then convert to a hexadecimal string to get the 'sign' parameter.

Create A Request

An example for how to generate string for signature

GET /private/v1/trade/orders?symbol=BTCUSDT HTTP/1.1
Host: api.mufex.finance
-H 'MF-ACCESS-SIGN-TYPE: 2' \
-H 'MF-ACCESS-SIGN: eb431d99a1a203a434a82ac3ea8e107b5f94a967e9aaf922c41e84fb3ec9df78' \
-H 'MF-ACCESS-API-KEY: {api key}' \
-H 'MF-ACCESS-TIMESTAMP: 1658384431891' \
-H 'MF-ACCESS-RECV-WINDOW: 5000'

Message format for POST requests:

POST /private/v1/trade/cancel HTTP/1.1
Host: api.mufex.finance
-H 'MF-ACCESS-SIGN-TYPE: 2' \
-H 'MF-ACCESS-SIGN: c822337e76e30505e41b87a55af291e074f59f9496ba12ca2a57dc04fe65a178' \
-H 'MF-ACCESS-API-KEY: {api key}' \
-H 'MF-ACCESS-TIMESTAMP: 1658385589135' \
-H 'MF-ACCESS-RECV-WINDOW: 5000' \
-H 'Content-Type: application/json' \
-d '{
  "category": "option"
}'

3. Add the 'sign' parameter to the request header and execute the HTTP request. Be aware that GET and POST requests have distinct message formats. See the provided examples for clarity.

Examples of the Signature Algorithm

Market Data

Get Order Book

Request Example

curl GET 'https://api.mufex.finance/public/v1/market/order-book?symbol=BTCUSDT'

Response Example

{
    "code": 0,
    "message": "OK",
    "data":  {
        "s": "BTCUSDT",
        "b": [
            [
                "28806",
                "0.06"
            ],
            [
                "28807",
                "5.005"
            ]
        ],
        "a": [
            [
                "29004",
                "0.001"
            ],
            [
                "29012",
                "0.017"
            ]
        ],
        "ts": 1653638043149,
        "u": 0
    },
    "ext_info": {},
    "time": 1679034720118
}

Get the orderbook. Each side has a depth of 25.

Enable 200 orders for orderbook API

HTTP Request

GET /public/v1/market/order-book

Request Parameters

Parameter Required Type Comment
symbol true string Symbol
limit false int 25 by default, 200 is max. If option, only 25 is available

Response Parameters

Parameter Type Comment
s string Symbol
b array Buyer. Order by price asc
a array Seller. Order by price asc
ts integer Timestamp(ms)
u string 0

Get Kline

Request Example

curl GET 'https://api.mufex.finance/public/v1/market/kline?category=linear&symbol=BTCUSDT&interval=D&start=1652112000000&end=1652544000000'

Response Example

{
    "code": 0,
    "message": "OK",,
    "data": {
      "category":"linear",
      "symbol":"BTCUSDT",
      "interval":"1",
      "list":[
      [
      "1621162800000",
      "49592.43",
      "49644.91",
      "49342.37",
      "49349.42",
      "1451.59",
      "2.4343353100000003"
      ]
    ]
    },
    "ext_info": {},
    "time": 1669802294719
}

Get kline.

HTTP Request

GET /public/v1/market/kline

Request Parameters

parameter Required Type Comment
category true string default:linear
symbol true string Symbol
interval true string Kline interval. enum: 1 3 5 15 30 60 120 240 360 720 "D" "M" "W"
start true integer Start timestamp point for result, in milliseconds
end true integer End timestamp point for result, in milliseconds
limit false integer Limit for data size per page, max size is 1500. Default as showing 200 pieces of data per page

Response Parameters

Parameter Type Comment
category string default:linear
symbol string Symbol
list string[] an array of individual candles, Sort in reverse order by start, The default collation within the array is start, open, high, low, close, volume, turnover

Ticker Info For Symbol

Request Example

curl GET 'https://api.mufex.finance/public/v1/market/tickers?category=linear&symbol=BTCUSDT'

Response Example

{
    "code": 0,
    "message": "OK",
    "data":  {
        "category": "linear",
        "list": [
            {
                "symbol": "BTCUSDT",
                "bidPrice": "19255",
                "askPrice": "19255.5",
                "lastPrice": "19255.50",
                "lastTickDirection": "ZeroPlusTick",
                "prevPrice24h": "18634.50",
                "price24hPcnt": "0.033325",
                "highPrice24h": "19675.00",
                "lowPrice24h": "18610.00",
                "prevPrice1h": "19278.00",
                "markPrice": "19255.00",
                "indexPrice": "19260.68",
                "openInterest": "48069.549",
                "turnover24h": "4686694853.047006",
                "volume24h": "243730.252",
                "fundingRate": "0.0001",
                "nextFundingTime": "1663689600000"
            }
        ]
    },
    "ext_info": {},
    "time": 1663670053454
}


Get all latest information for symbol

HTTP Request

GET /public/v1/market/tickers

Request Parameters

Parameter Required Type Comment
category true string If category is not passed, then return ""For now, default:linear
symbol false string Symbol name.

Response Parameters

Parameter Type Comment
category string If category is not passed, then return ""
price24hPcnt string Percentage change of market price relative to 24h
nextFundingTime string Next settlement time of capital cost
indexPrice string Index_price
prevPrice24h string Price of 24 hours ago
openInterest string Open interest
volume24h string Trading volume in the last 24 hours
symbol string Symbol
lastTickDirection string Direction of price change
lastPrice string Latest transaction price
bidPrice string Best bid price
turnover24h string Turnover in the last 24 hours
askPrice string Best ask price
fundingRate string Funding rate
highPrice24h string The highest price in the last 24 hours
prevPrice1h string Hourly market price an hour ago
markPrice string Mark price
lowPrice24h string Lowest price in the last 24 hours

Get Instrument Info

Request Example

curl GET 'https://api.mufex.finance/public/v1/instruments?category=linear&symbol=BTCUSDT'

Response Example

{
    "code": 0,
    "message": "OK",
    "data":  {
        "category": "linear",
        "list": [
            {
                "symbol": "BTCUSDT",
                "contractType": "LinearPerpetual",
                "status": "Trading",
                "baseCoin": "BTC",
                "quoteCoin": "USDT",
                "launchTime": "1584230400000",
                "deliveryTime": "0",
                "deliveryFeeRate": "",
                "priceScale": "2",
                "leverageFilter": {
                    "minLeverage": "1",
                    "maxLeverage": "100.00",
                    "leverageStep": "0.01"
                },
                "priceFilter": {
                    "minPrice": "0.50",
                    "maxPrice": "999999.00",
                    "tickSize": "0.50"
                },
                "lotSizeFilter": {
                    "maxTradingQty": "100.000",
                    "minTradingQty": "0.001",
                    "qtyStep": "0.001",
                    "postOnlyMaxOrderQty": "1000.000"
                },
                "unifiedMarginTrade": true,
                "fundingInterval": 480,
                "settleCoin": "USDT"
            }
        ],
        "nextPageCursor": ""
    },
    "ext_info": {},
    "time": 1670838442302
}

Query launched instruments info list

HTTP Request

GET /public/v1/instruments

Request Parameters

parameter Required Type Comment
category true string If category is not passed, then return ""For now, default:linear
symbol false string Symbol
limit false string Limit for data size per page, max size is 1000. Default as showing 500 pieces of data per page.It's not sorted by time.
cursor false string API pass-through

Response Parameters

Parameter Type Comment
symbol string Symbol
contractType string Contract type. Future or Perpetual only
status string Symbol status
baseCoin string Base coin. Like 'BTC' in BTC-USDT.
quoteCoin string Quote coin. Like 'USDT' in BTC-USDT.
settleCoin string Settle coin. Like 'BTC' in BTCUSD
launchTime string Launch time
priceScale string Price scale
>leverageFilter minLeverage string Min. leverage
>leverageFilter maxLeverage string Max. leverage
>leverageFilter leverageStep string Modification to leverage
>priceFilter minPrice string Min. order price
>priceFilter maxPrice string Max. order price
>priceFilter tickSize string Tick size
>lotSizeFilter maxOrderQty string Max trade quantity per order
>lotSizeFilter minOrderQty string Min trade quantity per order
>lotSizeFilter qtyStep string Min. order quantity increment
>lotSizeFilter postOnlyMaxOrderQty string The max order qty allowed when timeInforce=PostOnly
fundingInterval integer Funding fee interval
nextPageCursor string API pass-through

Get Risk Limit

Request Example

curl GET 'https://api.mufex.finance/public/v1/position-risk?category=linear&symbol=BTCUSDT'

Response Example

{
    "code": 0,
    "message": "OK",
    "data":  {
        "category": "linear",
        "list": [
            {
                "id": 1,
                "symbol": "BTCUSDT",
                "limit": "2000000",
                "maintainMargin": "0.005",
                "initialMargin": "0.01",
                "section": [
                    "1",
                    "3",
                    "5",
                    "10",
                    "25",
                    "50",
                    "80"
                ],
                "isLowestRisk": 1,
                "maxLeverage": "100.00"
            }
        ]
    },
    "ext_info": {},
    "time": 1669802294719
}

Get Risk Limit

HTTP Request

GET /public/v1/position-risk

Request Parameters

Parameter Required Type Comment
category true string If category is not passed, then return ""For now, default:linear
symbol true string Symbol

Response Parameters

Parameter Type Comment
category string If category is not passed, then return ""For now, default:linear
id number Risk ID
symbol string Symbol
limit string Risk Limit
maintainMargin string Maintain margin
initialMargin string Initial margin
section string Section
isLowestRisk number Is lowest risk. 0: No; 1: Yes
maxLeverage string Max leverage

Get Public Trading History

Request Example

curl GET 'https://api.mufex.finance/public/v1/market/trades?category=linear&symbol=BTCUSDT&limit=1'

Response Example

{
    "code": 0,
    "message": "OK",
    "data":  {
        "category": "linear",
        "list": [
            {
                "execId": "0efadcdc-f1dd-5847-9185-2f0b40e81cc7",
                "symbol": "BTCUSDT",
                "price": "16871.00",
                "size": "0.006",
                "side": "Buy",
                "time": "1669802293550"
            }
        ]
    },
    "ext_info": {},
    "time": 1669802294719
}

Get recent trades.

HTTP Request

GET /public/v1/market/trades

Request Parameters

Parameter Required Type Comment
category true string If category is not passed, then return ""For now, default:linear
symbol true string Symbol
limit false int Limit for data size per page, max size is 1000. Default as showing 500 pieces of data per page.It's not sorted by time.

Response Parameters

Parameter Type Comment
category string If category is not passed, then return ""For now, default:linear
execId string Latest data id
symbol string Symbol
price number Trade price
size number Order quantity
side string Side. Buy Sell
time string Executed timestamp(ms)

Account Data Endpoints

The following account data endpoints require authentication.

Trade

Create Order/ Close Order

Request Example

curl --location --request POST 'https://api.mufex.finance/private/v1/trade/create' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: f02a18137c25c40d64b2c474f575c01a62ba076124946d38619238e19c86a2f2' \
--header 'MF-ACCESS-API-KEY: XXXXXXXXXX' \
--header 'MF-ACCESS-TIMESTAMP: 1658884339826' \
--header 'MF-ACCESS-RECV-WINDOW: 5000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "symbol": "ETHUSDT",
    "side": "Sell",
    "positionIdx": 2,
    "orderType": "Limit",
    "qty": "0.5",
    "price": "1450",
    "triggerDirection": 2,
    "triggerPrice": "1500",
    "triggerBy": "MarkPrice",
    "timeInForce": "GoodTillCancel",
    "orderLinkId": "a003",
    "takeProfit": "1100",
    "stopLoss": "1700",
    "reduce_only": false,
    "closeOnTrigger": false,
    "pzLinkId": "49e5e569-dc26-4263-8feb-77f543637002"
}'

Response Example

{
    "code":0,
        "message":"OK",
        "data": {
        "orderId":"a09a43f1-7a65-4255-8758-034103447a4e",
        "orderLinkId":""
    },
    "ext_info":null,
        "time":1658850321861
}

Market price active order: A traditional market price order which will be filled at the best available price. price is not required for this type of order.

Limit price active order: You can set an execution price for your order. Only when the last traded price reaches the order price will the system will fill your order.

Take profit/Stop loss: You may only set a TP/SL conditional order upon opening the position. Once you hold a position, any new active order requests which contain TP/SL data will be accepted but TP/SL data will be ignored. tpTriggerBy/slTriggerBy default to LastPrice. Passing values to the takeProfit or stopLoss parameters in this endpoint will create conditional orders managed by the system, which will be be automatically cancelled if the position is closed.

Order quantity: This parameter indicates the quantity of perpetual contracts you want to buy or sell. For the minimum unit of qty increase or decrease, please refer to the lotSizeFilter field in the Query Symbol endpoint. Note: The allowed max trade quantity of PostOnly is 5 times bigger than normal orders.

Order price: If it is a stop order, this parameter is required. When there is no position, the long should be higher than 10% of the market price and less than 1 million. For the minimum unit of price movement, please refer to the priceFilter field in the Query Symbol endpoint.

Custom order ID: You may customise order IDs for active orders. We will link it to the system order ID, and return the unique system order ID to you after the active order is created successfully. You may use this order ID or your custom order ID to cancel your active order. The customised order ID should be unique, with a maximum length of 36 characters.

Each account can hold up to 500 active orders yet to be filled entirely simultaneously. This is per instrument, so it's possible to have, for example, 300 active orders on the BTCUSDT instrument and 280 active orders on the ETHUSDT instrument.

HTTP Request

POST /private/v1/trade/create

Request Parameters

Parameter Required Type Comment
symbol true string Symbol
side true string Buy
positionIdx true integer Position idx, used to identify positions in different position modes.
1-Buy side of both side mode
2-Sell side of both side mode
orderType true string Active order type
qty true string Quantity. If USDT perp, qty is in cryptocurrency.
price false string Order price. Required if you submit a limit order
triggerDirection false integer Trigger direction. Mainly used in conditional order. Trigger the order when market price rises to triggerPrice or falls to triggerPrice. 1: rise; 2: fall
triggerPrice false string Trigger price
triggerBy false string Trigger price type
tpTriggerBy false string Take profit trigger price type, default: LastPrice
slTriggerBy false string Stop loss trigger price type, default: LastPrice
timeInForce true string Time in force
orderLinkId false string Unique user-set order ID. Maximum length of 36 characters
takeProfit false string Take profit price, only take effect upon opening the position
stopLoss false string Stop loss price, only take effect upon opening the position
reduceOnly false bool What is a reduce-only order? True means your position can only reduce in size if this order is triggered. When reduce_only is true, take profit/stop loss cannot be set
closeOnTrigger false bool What is a close on trigger order? For a closing order. It can only reduce your position, not increase it. If the account has insufficient available balance when the closing order is triggered, then other active orders of similar contracts will be cancelled or reduced. It can be used to ensure your stop loss reduces your position regardless of current available margin.
pzLinkId false string Unique separate position link ID.

Response Parameters

Parameter Type Comment
orderId string Order ID
orderLinkId string Unique user-set order ID. Maximum length of 36 characters

Get Order List

Request Example

curl --location --request GET 'https://api.mufex.finance/private/v1/trade/orders?symbol=BTCUSDT&orderStatus=Filled' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: 61df2c2de39cfce40fe334e503de4a61e26a95aebec690b9b482e4feb31cb088' \
--header 'MF-ACCESS-API-KEY: {api key}' \
--header 'MF-ACCESS-TIMESTAMP: 1658899014497' \
--header 'MF-ACCESS-RECV-WINDOW: 5000'

Response Example

{
    "code": 0,
    "message": "OK",
    "data":  {
        "list": [
            {
                "symbol": "BTCUSDT",
                "side": "Buy",
                "orderType": "Market",
                "price": "0.3431",
                "qty": "65",
                "reduceOnly": true,
                "timeInForce": "ImmediateOrCancel",
                "orderStatus": "Filled",
                "leavesQty": "0",
                "leavesValue": "0",
                "cumExecQty": "65",
                "cumExecValue": "21.3265",
                "cumExecFee": "0.0127959",
                "lastPriceOnCreated": "0.0000",
                "rejectReason": "EC_NoError",
                "orderLinkId": "",
                "createdTime": "1657526321499",
                "updatedTime": "1657526321504",
                "orderId": "ac0a8134-acb3-4ee1-a2d4-41891c9c46d7",
                "stopOrderType": "UNKNOWN",
                "takeProfit": "0.0000",
                "stopLoss": "0.0000",
                "tpTriggerBy": "UNKNOWN",
                "slTriggerBy": "UNKNOWN",
                "triggerPrice": "0.0000",
                "closeOnTrigger": true,
                "triggerDirection": 0,
                "positionIdx": 2
        ],
        "nextPageCursor": "K0crQkZRL0MyQVpiN0tVSDFTS0RlMk9DemNCWHZaRHp3aFZ4Y1Yza2MyWT0="
    },
    "ext_info": {},
    "time": 1658899014975
}

Interface:

Access my order list.

As order creation/cancellation is asynchronous, the data returned from the interface may be delayed. To access order information in real-time, call the interface enquiring information on open orders in real-time.

HTTP Request

GET /private/v1/trade/orders

Request Parameters

Parameter Required Type Comment
orderId false string Order ID
orderLinkId false string Unique user-set order ID. Maximum length of 36 characters
symbol true string Symbol
orderStatus false string Query list of orders in designated states. If this parameter is not passed, the orders in all states shall be enquired by default.
orderFilter false string Conditional order or active order
limit false integer Limit for data size per page, max size is 50. Default as showing 20 pieces of data per page
cursor false string Page turning mark

Response Parameters

Parameter Type Comment
list> symbol string Symbol
list> side string Side
list> orderType string Order type
list> price string Order price
list> qty string Quantity. If USDT perp, qty is in cryptocurrency.
list> reduceOnly bool true means close order, false means open position
list> timeInForce string Time in force
list> orderStatus string Order status
list> leavesQty string Number of unfilled contracts from the order's size
list> leavesValue string The estimated value corresponding to the number of remaining orders
list> cumExecQty string Cumulative qty of trading
list> cumExecValue string Cumulative value of trading
list> cumExecFee string Cumulative trading fees
list> lastPriceOnCreated string Last execution price
list> rejectReason string Reason order is rejected
list> createdTime string Creation time (when the order_status was Created)
list> updatedTime string Update time
list> orderLinkId string Unique user-set order ID. Maximum length of 36 characters
list> orderId string Order ID
list> stopOrderType string Conditional order type
list> triggerDirection integer Trigger direction. Mainly used in conditional order. Trigger the order when market price rises to triggerPrice or falls to triggerPrice. 1: rise; 2: fall
list> closeOnTrigger bool Is close on trigger order
list> takeProfit string Take profit price
list> stopLoss string Stop loss price
list> tpTriggerBy string Trigger type of take profit. LastPrice in default. If it is USDC order, type is MarkPrice in default.
list> slTriggerBy string Trigger type of stop loss. LastPrice in default. If it is USDC order, type is MarkPrice in default.
list> triggerBy string The price type of trigger price
list> triggerPrice string If stopOrderType is TrailingProfit, triggerPrice means activate price. Otherwise, it is trigger price.
list> positionIdx integer Position idx, used to identify positions in different position modes:
1-Buy side of both side mode
2-Sell side of both side mode
nextPageCursor string Next page cursor

Cancel order

Request Example

curl --location --request POST 'https://api.mufex.finance/private/v1/trade/cancel' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: c9f2c118e40040fc3a12c9400816a26e475ce2f7995248a3625d92be3454b9f1' \
--header 'MF-ACCESS-API-KEY: {api key}' \
--header 'MF-ACCESS-TIMESTAMP: 1658900794413' \
--header 'MF-ACCESS-RECV-WINDOW: 5000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "symbol": "XRPUSDT",
  "orderLinkId": null,
  "orderId": "4030430d-1dba-4134-ac77-3d81c14aaa00"
}'

Response Example

{
    "code":0,
    "message":"OK",
    "data": {
      "orderId": "4030430d-1dba-4134-ac77-3d81c14aaa00",
      "orderLinkId": ""
  },
  "ext_info":null,
    "time":1658850321861
}

Interface:

Cancel order. orderId or orderLinkId is required.

orderId - Once you have successfully created an order, the system will send you the unique 36-character order ID.

You can cancel the order not filled or not completely filled. You cannot cancel orders that are completely filled.

HTTP Request

POST /private/v1/trade/cancel

Request Parameters

Parameter Required Type Comment
symbol true string Symbol
orderId false string Order ID. Required if not passing orderLinkId
orderLinkId false string Unique user-set order ID. Required if not passing orderId

Response Parameters

Parameter Type Comment
orderId string Order ID
orderLinkId string Unique user-set order ID

Replace order

Request Example

curl --location --request POST 'https://api.mufex.finance/private/v1/trade/replace' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: 78c358649d431bb30dfc35e5a3cd99128b5f23faf04c15765b3d894f2930e8f5' \
--header 'MF-ACCESS-API-KEY: {api key}' \
--header 'MF-ACCESS-TIMESTAMP: 1658902610018' \
--header 'MF-ACCESS-RECV-WINDOW: 5000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "symbol":"XRPUSDT",
    "orderId":"db8b74b3-72d3-4264-bf3f-52d39b41956e",
    "orderLinkId": null,
    "qty": "15",
    "price": "0.4"
}'

Response Example

{
    "code": 0,
        "message": "OK",
        "data":  {
        "orderId": "db8b74b3-72d3-4264-bf3f-52d39b41956e",
            "orderLinkId": "x002"
    },
    "ext_info": {},
    "time": 1658902610749
}

Replace order can modify/amend your orders.

HTTP Request

POST /private/v1/trade/replace

Request Parameters

Parameter Required Type Comment
orderId false string Order ID. Required if not passing orderLinkId
orderLinkId false string Unique user-set order ID. Required if not passing orderId
symbol true string Symbol
qty false string New order quantity. Do not pass this field if you don't want modify it
price false string New order price. Do not pass this field if you don't want modify it

Response Parameters

Parameter Type Comment
order_id string Order ID
orderLinkId string Unique user-set order ID. Maximum length of 36 characters

Get Open Order

Request Example

curl --location --request GET 'https://api.mufex.finance/private/v1/trade/activity-orders?symbol=XRPUSDT' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: e3a1e4b88dfc2730c987fb3253dd3e09bc05cf68ae4d9d9d71a8235c44cb1f02' \
--header 'MF-ACCESS-API-KEY: {api key}' \
--header 'MF-ACCESS-TIMESTAMP: 1658902846749' \
--header 'MF-ACCESS-RECV-WINDOW: 5000' \
--header 'Content-Type: application/json'

Response Example

{
  "code": 0,
  "message": "OK",
  "data":  {
    "list": [
      {
        "symbol": "XRPUSDT",
        "orderId": "db8b74b3-72d3-4264-bf3f-52d39b41956e",
        "side": "Sell",
        "orderType": "Limit",
        "stopOrderType": "Stop",
        "price": "0.4000",
        "qty": "15",
        "timeInForce": "GoodTillCancel",
        "orderStatus": "UnTriggered",
        "triggerPrice": "0.1000",
        "orderLinkId": "x002",
        "createdTime": "1658901865082",
        "updatedTime": "1658902610748",
        "takeProfit": "0.2000",
        "stopLoss": "1.6000",
        "tpTriggerBy": "UNKNOWN",
        "slTriggerBy": "UNKNOWN",
        "triggerBy": "MarkPrice",
        "reduceOnly": false,
        "leavesQty": "15",
        "leavesValue": "6",
        "cumExecQty": "0",
        "cumExecValue": "0",
        "cumExecFee": "0",
        "triggerDirection": 2
      }
    ],
    "nextPageCursor": ""
  },
  "ext_info": {},
  "time": 1658902847238
}

Query real-time order information. If only orderId or orderLinkId are passed, a single order will be returned; otherwise, returns up to 500 unfilled orders

.

Ordered by createdTime in descending order.

HTTP Request

GET /private/v1/trade/activity-orders

Request Parameters

Parameter Required Type Comment
symbol false string Symbol name.
orderId false string Order ID
orderLinkId false string Unique user-set order ID
orderFilter false string Conditional order or active order
limit false number Limit for data size per page, max size is 50. Default as showing 20 pieces of data per page
cursor false string Page turning mark

Response Parameters

Parameter Type Comment
> symbol string Symbol
> orderId string Order ID
> side string Side
> orderType string Order type
> triggerDirection integer Trigger direction. Mainly used in conditional order. Trigger the order when market price rises to triggerPrice or falls to triggerPrice. 1: rise; 2: fall
> price string Order price
> qty string Quantity. If USDT perp, qty is in cryptocurrency.
> timeInForce string Time in force
> orderStatus string Order status
> triggerPrice string Trigger price
> triggerBy string Trigger price type
> tpTriggerBy string Take profit trigger price type, default: LastPrice
> slTriggerBy string Stop loss trigger price type, default: LastPrice
> orderLinkId string Unique user-set order ID. Maximum length of 36 characters
> createdTime string Creation time (when the order_status was Created)
> updatedTime string Update time
> takeProfit string Take profit price
> stopLoss string Stop loss price
> reduce_only bool true means close order, false means open position
> cumExecQty string Cumulative qty of trading
> cumExecValue string Cumulative value of trading
> cumExecFee string Cumulative trading fees
> leavesQty string Number of unfilled contracts from the order's size
> leavesValue string The estimated value corresponding to the number of remaining orders
nextPageCursor string API pass-through

Get User Trade Records

Request Example

curl --location --request GET 'https://api.mufex.finance/private/v1/trade/fills?symbol=BTCUSDT' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: a7358fb068bf66570e7ecf063e39a6dbd11f1d5572ba79a63d5996221d864585' \
--header 'MF-ACCESS-API-KEY: XXXXXXXXXXXX' \
--header 'MF-ACCESS-TIMESTAMP: 1658911518042' \
--header 'MF-ACCESS-RECV-WINDOW: 5000'

Response Example

{
    "code": 0,
        "message": "OK",
        "data":  {
        "list": [
            {
                "symbol": "BTCUSDT",
                "execFee": "0.00293025",
                "execId": "16bff97b-0e04-4303-82b5-1b1134f15695",
                "execPrice": "0.00",
                "execQty": "0.001",
                "execType": "Funding",
                "execValue": "29.30248",
                "feeRate": "0.0001",
                "lastLiquidityInd": "UNKNOWN",
                "leavesQty": "0.000",
                "orderId": "1690588800-BTCUSDT-139688-Buy",
                "orderLinkId": "",
                "orderPrice": "0.00",
                "orderQty": "0.000",
                "orderType": "UNKNOWN",
                "stopOrderType": "UNKNOWN",
                "side": "Buy",
                "execTime": "1690588800000",
                "closedSize": "0.000",
                "crossSeq": "41019846"
            },
            {
                "symbol": "BTCUSDT",
                "execFee": "0.00293787",
                "execId": "d9439111-d9ee-4cf3-90e1-85e8f148b6a3",
                "execPrice": "0.00",
                "execQty": "0.001",
                "execType": "Funding",
                "execValue": "29.3787",
                "feeRate": "0.0001",
                "lastLiquidityInd": "UNKNOWN",
                "leavesQty": "0.000",
                "orderId": "1690560000-BTCUSDT-139688-Buy",
                "orderLinkId": "",
                "orderPrice": "0.00",
                "orderQty": "0.000",
                "orderType": "UNKNOWN",
                "stopOrderType": "UNKNOWN",
                "side": "Buy",
                "execTime": "1690560000000",
                "closedSize": "0.000",
                "crossSeq": "40849025"
            }
        ],
            "nextPageCursor": ""
    },
    "ext_info": {},
    "time": 1658911518442
}

Get user's trading records. The results are ordered in descending order (the first item is the latest). Returns records up to 2 years old.

HTTP Request

GET /private/v1/trade/fills

Request Parameters

Parameter Required Type Comment
orderId false string Order ID. If null, all executed orders are returned
symbol true string Symbol
startTime false number Start timestamp in millisecond
endTime false number End timestamp in millisecond
execType false string Execution type
limit false integer Limit for data size per page, max size is 200. Default as showing 50 pieces of data per page.
cursor false string Page turning mark

Response Parameters

Parameter Type Comment
list> symbol string Symbol
list> execFee string Transaction fee
list> execId string Transaction ID
list> execPrice string Transaction price
list> execQty string Transaction qty
list> execType string Exec type
list> execValue string Transaction value
list> feeRate string Maker or taker fee rate
list> lastLiquidityInd string Only valid while exec_type is Trade, AdlTrade, BustTrade
list> leavesQty string Number of unfilled contracts from the order's size
list> orderId string Order ID
list> orderLinkId string Unique user-set order ID. Maximum length of 36 characters
list> orderPrice string Order price
list> orderQty string Order qty
list> orderType string Order type
list> stopOrderType string Conditional order type
list> side string Side
list> execTime string Time of trade (unit: ms)
list> closedSize string The corresponding closing size of the closing order
list> crossSeq int64 cross seq
nextPageCursor string Next page cursor

Account

Get Position (real-time)

Request Example

curl --location --request GET 'https://api.mufex.finance/private/v1/account/positions?symbol=ETHUSDT' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: b0818cb2f91264ffd712db0c8f8648041b2c5eed643200aa63e4141c7aa12500' \
--header 'MF-ACCESS-API-KEY: {api key}' \
--header 'MF-ACCESS-TIMESTAMP: 1658904877491' \
--header 'MF-ACCESS-RECV-WINDOW: 5000' \
--header 'Content-Type: application/json' \
--data-raw ''

Response Example

{
    "code": 0,
        "message": "OK",
        "data":  {
        "list": [
            {
                "positionIdx": 0,
                "riskId": 11,
                "symbol": "ETHUSDT",
                "side": "None",
                "size": "0.00",
                "positionValue": "0",
                "entryPrice": "0",
                "tradeMode": 1,
                "autoAddMargin": 0,
                "leverage": "10",
                "positionBalance": "0",
                "liqPrice": "0.00",
                "bustPrice": "0.00",
                "takeProfit": "0.00",
                "stopLoss": "0.00",
                "trailingStop": "0.00",
                "unrealisedPnl": "0",
                "createdTime": "1659943372099",
                "updatedTime": "1669470547908",
                "tpSlMode": "Full",
                "riskLimitValue": "900000",
                "activePrice": "0.00",
                "markPrice": "1205.02",
                "cumRealisedPnl": "0.00",
                "positionMM": "",
                "positionIM": "",
                "positionStatus": "Normal",
                "sessionAvgPrice": "0.00",
                "pzLinkId": "",
                "isSeparatePz": false

            }
        ],
            "separateList": []
            "category": "linear",
            "nextPageCursor": ""
    },
    "ext_info": {},
    "time": 1670836410404
}

{
    "code": 0,
    "message": "OK",
    "data": {
    "list": [],
        "category": "",
        "nextPageCursor": "",
        "separateList": [
        {
            "positionIdx": 1,
            "riskId": "0",
            "symbol": "BTCUSDT",
            "side": "Buy",
            "size": "0.001",
            "positionValue": "57.6742",
            "entryPrice": "57674.2",
            "tradeMode": 0,
            "autoAddMargin": 0,
            "leverage": "10",
            "positionBalance": "5.76742",
            "liqPrice": "0.1",
            "bustPrice": "0.1",
            "takeProfit": "0.0",
            "stopLoss": "0.0",
            "trailingStop": "0.0",
            "unrealisedPnl": "-0.9374",
            "createdTime": "1726017294861",
            "updatedTime": "1726026707029",
            "tpSlMode": "Partial",
            "riskLimitValue": "0",
            "activePrice": "0.0",
            "markPrice": "56736.8",
            "cumRealisedPnl": "-0.03460452",
            "positionMm": "",
            "positionIm": "",
            "positionStatus": "Normal",
            "sessionAvgPrice": "0.0",
            "pzLinkId": "3c582eef-33e9-41b4-98c5-37278c735576",
            "isSeparatePz": true
        }
    ]
},
    "ext_info": {},
    "time": 1726026707032
}

Interface:

Accessing personal list of positions. Users can access information about their open positions through this interface, such as the quantity and wallet balance.

HTTP Request

GET /private/v1/account/positions

Request Parameters

Parameter Required Type Comment
symbol false string Symbol name.
settleCoin false string Settle coin. Either symbol or settleCoin is required. If both are passed, symbol is used first.
limit false integer Limit for data size per page. [1, 50]. Default:20
cursor false string Page turning mark

Response Parameters

Parameter Type Comment
positionIdx integer Position idx, used to identify positions in different position modes:
1-Buy side of both side mode
2-Sell side of both side mode
riskId integer Risk limit ID
riskLimitValue string Position upper limit corresponding to the current risk limit ID
symbol string Symbol
side string Side
size string Position qty
positionValue string Position value
entryPrice string Average opening price
markPrice string Update time
tradeMode integer Cross/isolated mode. 0: cross margin mode; 1: isolated margin mode
autoAddMargin integer Whether or not auto-margin replenishment is enabled
leverage string In Isolated Margin mode, the value is set by the user. In Cross Margin mode, the value is the max leverage at current risk level
positionBalance string Position balance
liqPrice string Liquidation price
bustPrice string Bust price
positionStatus string Update time
sessionAvgPrice string Settlement price
takeProfit string Take profit price
stopLoss string Stop loss price
trailingStop string Trailing stop (the distance from the current price)
unrealisedPnl string unrealised pnl
tpSLMode string TrailingProfit or StopLoss mode Full or Partial
activePrice string Trailing stop trigger price. Trailing stop will only be triggered when this price is touched (trailing stop will be immediately triggered by default).
positionIM string Position Initial margin. Empty String under Portfolio Margin mode
positionMM string Position Maintenance margin. Empty String under Portfolio Margin mode
cumRealisedPnl string Accumulatively realized P&L
pzLinkId false string
createdTime string Creation time (when the order_status was Created)
updatedTime string Update time
nextPageCursor string Next page cursor

Switch Cross/Isolated Margin

Request Example

curl --location --request POST 'https://api.mufex.finance/private/v1/account/set-isolated' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: f178bda84f8a3fa971338b7424cce2204824c0114f196650b2516962371e3902' \
--header 'MF-ACCESS-API-KEY: XXXXXXXXXX' \
--header 'MF-ACCESS-TIMESTAMP: 1658908531694' \
--header 'MF-ACCESS-RECV-WINDOW: 5000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "symbol":"XRPUSDT",
    "tradeMode": 1,
    "buyLeverage": "5",
    "sellLeverage": "5"
}'

Response Example

{
    "code": 0,
        "message": "OK",
        "data":  {},
    "ext_info": {},
    "time": 1658908532580
}

Switch cross margin mode/isolated margin mode

HTTP Request

POST /private/v1/account/set-isolated

Request Parameters

Parameter Required Type Comment
symbol true string Symbol
tradeMode true integer Cross/isolated mode. 0: cross margin mode; 1: isolated margin mode
buyLeverage false string (0, max leverage of corresponding risk limit]. For one-way mode, make sure that buyLeverage is equal to sellLeverage
sellLeverage false string (0, max leverage of corresponding risk limit]. For one-way mode, make sure that buyLeverage is equal to sellLeverage

Response Parameters

Parameter Type Comment

Switch Separate Position Mode

Request Example

curl --location --request POST 'https://api.mufex.finance/private/v1/account/switch-separate-position' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: f178bda84f8a3fa971338b7424cce2204824c0114f196650b2516962371e3902' \
--header 'MF-ACCESS-API-KEY: XXXXXXXXXX' \
--header 'MF-ACCESS-TIMESTAMP: 1658908531694' \
--header 'MF-ACCESS-RECV-WINDOW: 5000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "coin": "USDT",
    "isSeparatePz": true
}'

Response Example

{
        "code": 0, 
        "message": "Success",
        "data":  {},
        "ext_info": {},
        "time": 1658908532580
}

Switch Separate Position Mode

HTTP Request

POST /private/v1/account/switch-separate-position

Request Parameters

Parameter Required Type Comment
coin true string COIN (USDT)
isSeparatePz true bool Is Separate Position Mode

Response Parameters

Parameter Type Comment

Set Leverage

Request Example

curl --location --request POST 'https://api.mufex.finance/private/v1/account/set-leverage' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: f178bda84f8a3fa971338b7424cce2204824c0114f196650b2516962371e3902' \
--header 'MF-ACCESS-API-KEY: XXXXXXXXXX' \
--header 'MF-ACCESS-TIMESTAMP: 1658908531694' \
--header 'MF-ACCESS-RECV-WINDOW: 5000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "symbol":"XRPUSDT",
    "buyLeverage": "5",
    "sellLeverage": "5"
}'

Response Example

{
    "code": 0,
        "message": "OK",
        "data":  {},
    "ext_info": {},
    "time": 1658908532580
}

Set Leverage

HTTP Request

POST /private/v1/account/set-leverage

Request Parameters

Parameter Required Type Comment
symbol true string Symbol
buyLeverage true string (0, max leverage of corresponding risk limit]. For one-way mode, make sure that buyLeverage is equal to sellLeverage
sellLeverage true string (0, max leverage of corresponding risk limit]. For one-way mode, make sure that buyLeverage is equal to sellLeverage

Response Parameters

Parameter Type Comment

Get Closed Profit and Loss

Request Example

curl --location --request GET 'https://api.mufex.finance/private/v1/account/closed-pnl?symbol=XRPUSDT&startTime=1658764800000&endTime=1658937600000' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: eb16a696924a92a3a47d769caf44d7373eca9ed6a644384ff6e8cd729ee9f7b1' \
--header 'MF-ACCESS-API-KEY: XXXXXXXXXXXX' \
--header 'MF-ACCESS-TIMESTAMP: 1658914264517' \
--header 'MF-ACCESS-RECV-WINDOW: 5000'

Response Example

{
    "code": 0,
        "message": "OK",
        "data":  {
        "list": [
            {
                "symbol": "XRPUSDT",
                "orderId": "3834da81-2b9c-4f5b-a558-05091f26deda",
                "side": "Buy",
                "qty": "50",
                "orderPrice": "0.3541",
                "orderType": "Market",
                "execType": "Trade",
                "closedSize": "50",
                "cumEntryValue": "16.68",
                "avgEntryPrice": "0.3336",
                "cumExitValue": "16.865",
                "avgExitPrice": "0.3373",
                "closedPnl": "-0.2034435",
                "fillCount": "1",
                "leverage": "10",
                "createdAt": "1658914152212"
            }
        ],
            "nextPageCursor": "R21aYkRjQ0haRmcxeFJBanZNYm1Db01RWWdyV3YzZmdkUVNXUmtXdGpMMD0="
    },
    "ext_info": {},
    "time": 1658914264892
}

Get user's closed profit and loss records. The results are ordered in descending order (the first item is the latest).

HTTP Request

GET /private/v1/account/closed-pnl

Request Parameters

Parameter Required Type Comment
symbol true string Symbol
startTime false number Start timestamp point for result, in seconds
endTime false number End timestamp point for result, in seconds
limit false integer Limit for data size per page, max size is 200. Default as showing 50 pieces of data per page.
cursor false string Page turning mark

Response Parameters

Parameter Type Comment
list> orderId string Order ID of the closing order
list> symbol string Symbol
list> side string Side of the closing order
list> qty string Order qty
list> orderPrice string Order price
list> orderType string Order type
list> execType string Exec type
list> closedSize string Closed size
list> cumEntryValue string Closed position value
list> avgEntryPrice string Average entry price
list> cumExitValue string Cumulative trading value of position closing orders
list> avgExitPrice string Average exit price
list> closedPnl string Closed Profit and Loss
list> fillCount string The number of fills in a single order
list> leverage string In Isolated Margin mode, the value is set by the user. In Cross Margin mode, the value is the max leverage at current risk level
list> createdAt string Creation time (when the order_status was Created)
nextPageCursor string Next page cursor

Get Wallet Balance

Request Example

curl --location --request GET 'https://api.mufex.finance/private/v1/account/balance?coin=BTC' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: f8f516355e0c59b28d429b13b4ea6a350d02f9c96e2f9fd1be235863e8c1834c' \
--header 'MF-ACCESS-API-KEY: {api key}' \
--header 'MF-ACCESS-TIMESTAMP: 1658736635286' \
--header 'MF-ACCESS-RECV-WINDOW: 5000'

Response Example

{
    "code": 0,
        "message": "OK",
        "data":  {
        "list": [
            {
                "coin": "BTC",
                "equity": "0.80319649",
                "walletBalance": "0.80319649",
                "positionMargin": "0",
                "availableBalance": "0.80319649",
                "orderMargin": "0",
                "occClosingFee": "0",
                "occFundingFee": "0",
                "unrealisedPnl": "0",
                "cumRealisedPnl": "0.00120039",
                "givenCash": "0",
                "serviceCash": "0"
            }
        ]
    },
    "ext_info": {},
    "time": 1658736635763
}

Get wallet balance info.

HTTP Request

GET /private/v1/account/balance

Request Parameters

Parameter Required Type Comment
coin false string currency alias. Returns all wallet balances if not passed. Multiple coins are allowed, separated by comma, like: USDT,USDC

Response Parameters

Parameter Type Comment
list> coin string Coin name
list> equity string User equity (wallet_balance + unrealised_pnl)
list> walletBalance string Wallet balance
list> positionMargin string Position margin
list> availableBalance string

In Isolated Margin Mode:

  available_balance = wallet_balance - (position_margin + occ_closing_fee + occ_funding_fee + order_margin)

In Cross Margin Mode:

  if unrealised_pnl > 0:
      available_balance = wallet_balance - (position_margin + occ_closing_fee + occ_funding_fee + order_margin)
  if unrealised_pnl < 0:
      available_balance = wallet_balance - (position_margin + occ_closing_fee + occ_funding_fee + order_margin) + unrealised_pnl
list> orderMargin string Pre-occupied order margin
list> occClosingFee string Position closing fee occupied (your opening fee + expected maximum closing fee)
list> occFundingFee string Pre-occupied funding fee: calculated from position qty and current funding fee
list> unrealisedPnl string unrealised pnl
list> cumRealisedPnl string Accumulated realised pnl (all-time total)
list> givenCash string Experience gold
list> serviceCash string Service cash is used for user's service charge

Get Trading Fee Rate

Instruction:

Get user trading fee rate

Request Example

curl --location --request GET 'https://api.mufex.finance/private/v1/account/trade-fee?symbol=ETHUSDT' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: e65aad8dd5459774ad21aaca77420947332fdbfe433bef959c6507ce2379999f' \
--header 'MF-ACCESS-API-KEY: XXXXXXXXXXXX' \
--header 'MF-ACCESS-TIMESTAMP: 1658739026859' \
--header 'MF-ACCESS-RECV-WINDOW: 5000'

Response Example

{
    "code": 0,
        "message": "OK",
        "data":  {
        "list": [
            {
                "symbol": "ETHUSDT",
                "takerFeeRate": "0.0009",
                "makerFeeRate": "0.0003"
            }
        ]
    },
    "ext_info": {},
    "time": 1658739027301
}

HTTP Request

GET /private/v1/account/trade-fee

Request Parameters

Parameter Required Type Comment
symbol false string Symbol

Response Parameters

Parameter Type Comment
list> symbol string Symbol
list> takerFeeRate string Taker fee rate
list> makerFeeRate string Maker fee rate

Get Wallet Fund Records

Request Example

curl --location --request GET 'https://api.mufex.finance/private/v1/account/bills?coin=USDT&walletFundType=RealisedPNL&limit=1' \
--header 'MF-ACCESS-SIGN-TYPE: 2' \
--header 'MF-ACCESS-SIGN: 591a44021fff458a6dfbba517755e1105066864d94c38a0ce84619ae51cf2313' \
--header 'MF-ACCESS-API-KEY: {api key}' \
--header 'MF-ACCESS-TIMESTAMP: 1658737208933' \
--header 'MF-ACCESS-RECV-WINDOW: 5000'

Response Example

{
    "code": 0,
        "message": "OK",
        "data":  {
        "list": [
            {
                "coin": "USDT",
                "type": "RealisedPNL",
                "amount": "500",
                "walletBalance": "2731.63599033",
                "execTime": "1658215763731"
            }
        ],
            "nextPageCursor": "elZpeUVCSCtFRk5pZjMrMU9reDdMdkpJS2VZdEpqczNHaExPUU5CazA0Yz0="
    },
    "ext_info": {},
    "time": 1658737209400
}

Get wallet fund records.

HTTP Request

GET /private/v1/account/bills

Request Parameters

Parameter Required Type Comment
startTime false string Start timestamp in milliseconds
endTime false string End timestamp in milliseconds.
coin false string Coin name
walletFundType false string Wallet fund type
limit false string Limit for data size per page, max size is 50. Default as showing 20 pieces of data per page
cursor false string Cursor

Response Parameters

Parameter Type Comment
list> coin string Coin type
list> type string Fund type
list> amount string Fund amount
list> wallet_balance string Wallet balance
list> exec_time string Transaction time
nextPageCursor string Next page cursor

API Rate Limit

The API rate limit is based on the rolling time window per second and UID. In other words, it's per second per UID. Every request to the API returns response header shown in the code panel:

// Response header

Content-Type: application/json; charset=utf-8
Content-Length: 957
MF-ACCESS-Limit: 5
MF-ACCESS-Limit-Status: 4
MF-ACCESS-Limit-Reset-Timestamp: 1665397625986

Rate Limits For All Private Endpoints

Limit Path
5 requests/second All private endpoints
1 requests/2 second batch requests

The rate limits for each private endpoint should be considered separately.

Order Limits

Max. number of unfilled orders supported under each trading pair:

How to Increase API Limits

WebSocket Data

Authentication

Authentication methods:

Second method: Apply for authentication after establishing a connection through auth request.

# based on: https://github.com/mufex-exchange/pybit/blob/master/pybit/_http_manager.py

import hmac
import json
import time
import websocket

ws_url = "wss://ws.mufex.finance/contract/private"

api_key = ""

# Authenticate with API.
ws.send(
    json.dumps({
        "op": "auth",
        "args": [api_key]
    })
)

# auth success response sample
{
    "success": true,
    "ret_msg": "success",
    "conn_id": "1a30f215-b7d2-4542-bac8-563a79963b35",
    "request": {
        "op": "auth",
        "args": [api_key]
    }
}

//sub
ws.send(
    json.dumps({
        "op": "subscribe",
        "args": ["contract.execution","contract.wallet"]
        "conn_id": "1a30f215-b7d2-4542-bac8-563a79963b35",
    })
)

ws = websocket.WebSocketApp(
    url=url,
    ...
)

WebSocket public channel:

WebSocket private channel:

Authentication examples are shown in the code block.

How to Send Heartbeat Packet

How to Send

ws.send('{"op":"ping"}');

Response Example

// pong response sample for usdt perp and inverse
{
    "success": true,
    "ret_msg": "pong",
    "conn_id": "1a30f215-b7d2-4542-bac8-563a79963b35",
    "req_id": "",
    "op": "ping"
}

How to Subscribe to Topics

Understanding Websocket Filters

How to subscribe with a filter

// Subscribing to the trade data for BTCUSD
ws.send('{"op":"subscribe","args":["trades-100.BTCUSDT"],"req_id": "customised_id"}}')

How to subscribe with multiple filters

// Example: Subscribing to the trade data for BTCUSD and XRPUSD
ws.send('{"op":"subscribe","args":["trades-100.BTCUSDT", "trades-100.ETHUSDT"],"req_id": "customised_id"}')

After establishing the connection, one can subscribe to a new topic by sending a JSON request. The specific formats are as follows:

ws.send('{"op": "subscribe", "args": ["topic.filter"],"req_id": "customised_id"}');

The topic indicates the data you would like to receive whilst the filter parses for the specific data you desire - for example, the symbol. The topic is mandatory but the filter is optional.

To subscribe to more than one topic, simply list multiple topics out, like so:

ws.send('{"op": "subscribe", "args": ["topic.filter", "topic.filter"],"req_id": "customised_id"}');

It is possible to use multiple filters for the same topic by splitting them with a pipe (|) - of course, these filters must all be applicable to the selected topic.

Response(ret_msg the reason of failure, but it keeps null with successful subscription): {"success":true,"ret_msg":"","conn_id": "{conn_id}"}

Unsubscribing From Websocket Topics

How to unsubscribe with a filter

// Unsubscribing from the trade data for ETHUSD
ws.send('{{"op":"unsubscribe","args":["books-25.BTCUSDT"]}')

You can dynamically subscribe and unsubscribe from topics (with or without filters) without websocket disconnection as follows:

ws.send('{"op": "unsubscribe", "args": ["topic.filter", "topic.filter"]});

Understanding Subscription Response

Subscription Response

{
  "success": true,
  "ret_msg": "",
  "conn_id": "0b12f925-0ab7-4ff8-afd4-c9661456b8fc",
  "request": {
    "op": "subscribe",
    "args": [
      "books-25.BTCUSDT"
    ]
  }
}

Each subscription will have a response. You can determine whether the subscription is successful based on the response.

Public Topics

orderbook

How to Subscribe

ws.send('{"op": "subscribe", "req_id": "10110001", "args": ["books-25.BTCUSDT","books-200.BTCUSDT"]}')

Snapshot Response Example - format of the first response

{
    "topic": "books-25.BTCUSDT",
    "type": "snapshot",
    "ts": 1668748553479,
    "data": {
        "s": "BTCUSDT",
        "b": [
            [
                "17053.00", //price
                "0.021" //size
            ],
            ....
            [
                "17016.50",
                "0.020"
            ],
        ],
        "a": [
            [
                "17054.00",
                "6.288"
            ],
            ....
            [
                "17166.50",
                "0.049"
            ]
        ]
    },
    "cs": 17550368
}

Delta Response Example - format of the responses following the snapshot response

{
    "topic": "books-25.BTCUSDT",
    "type": "delta",
    "ts": 1668748553556,
    "data": {
        "s": "BTCUSDT",
        "b": [],
        "a": [
            [
                "17168.00",
                "0.300"
            ],
            [
                "17070.00",
                "0"
            ]
        ]
    },
    "cs": 17550368,

}

instruction: Get different depth.
Once subscribe successfully, you will receive a snapshot. The data is ordered by order price, which bids is from highest to lowest and asks is from lowest to highest. Websocket will keep pushing delta message when orderbook is changed. If you receive a new snapshot data, it's necessary to reset your local orderbook.

type: snapshot=Full orderbook, delta=delta orderbook
reset=reset orderbook
If there is a problem in mufex end, it will re-send a snapshot, which is promised the latest and accurate.

25 level data, push frequency: 20ms
200 level data, push frequency: 100ms

Topic:
books-25.{symbol}
books-200.{symbol}

Response Parameters

Parameter Type Comment
topic string Topic name
type string snapshot/delta/reset
ts long timestamp(ms). The time that system generates the data.
data Object
>s string Symbol
>b array buyer
>>b[0][0] string Bid price
>>b[0][1] string Bid size
>a array seller
>>a[0][0] string Ask price
>>a[0][1] string Ask size 0:delete
cs number Cross sequence (internal value)

trade

How to Subscribe

ws.send('{"op": "subscribe", "req_id": "10110001", "args": ["trades-100.BTCUSDT"]}')

Response Example - format of all responses

{
{
  "topic": "trades-100.BTCUSDT",
  "type": "delta",
  "data": {
    "s": "BTCUSDT",
    "d": [
      [
        "0-",
        "26574.50",
        "0.25",
        "2023-03-17T13:32:02Z",
        "a",
        "9ca02a95-7b16-5967-a333-57e9aa654746",
        "0"
      ],
      [
        "-",
        "26573.00",
        "0.75",
        "2023-03-17T13:32:02Z",
        "a",
        "25a1e946-0e2c-5e5d-b486-c6247ff50cad",
        "0"
      ]
    ]
  },
  "cs": 16250033,
  "ts": 1679059922985128
}

}

instruction:
After subscription, you will be pushed delta trade message in real-time once there is an order filled.

Push frequency: 100ms

Topic:
trades-100.{symbol}

Response Parameters

Parameter Type Comment
topic string Topic name
type string snapshot/delta
data Object
>s string Symbol
>d array trade list
>>0 string Direction of price change
>>1 string Order price
>>2 string Position qty
>>3 long timestamp(ms). The time that the order is filled
>>4 string Direction of taker a:ask ,b:bid
>>5 string Trade ID
>>6 string "0"
cs number Cross sequence (internal value)
ts long timestamp(ms). The time that system generates the data.

ticker

How to Subscribe

ws.send('{"op": "subscribe", "req_id": "10110001", "args": ["tickers-100.BTCUSDT"]}')

Snapshot Response Example - format of the first response

{
    "topic": "tickers-100.BTCUSDT",
    "type": "snapshot",
    "data": {
        "s": "BTCUSDT",
        "p": "28214.50",
        "b1": "26754.00",
        "a1": "28201.00",
        "td": "0+",
        "p24": "27000.00",
        "pP": 44981,
        "h": "28580.00",
        "l": "27000.00",
        "p1": "28210.00",
        "to": "1482841986.627001",
        "v": "52683.009",
        "ft": "2023-03-22T16:00:00Z",
        "mp": "28179.66",
        "ip": "28179.66",
        "o": "0",
        "frgs": "0",
        "fr": 100,
        "pf": 100,
        "nh": 8,
        "ds": "0"
    },
    "cs": 17652420,
    "ts": 1679490241132846
}

Delta Response Example - format of the responses following the snapshot response

{
  "topic": "tickers-100.BTCUSDT",
  "type": "delta",
  "data": {
    "s": "BTCUSDT",
    "td": "0-",
    "pr": 79715,
    "to": "1618146770.2949994",
    "v": "63582.93699999",
    "fr": 100,
    "pf": 100
  },
  "cs": 16250032,
  "ts": 1679059922684958
}

Get latest information for symbol.

Push frequency: 100ms,100ms

Topic:

tickers-100.{symbol}

tickers-1000.{symbol}

Future response parameters

Parameter Type Comment shorthand
topic string Topic name
type string snapshot/delta
data Object
symbol string Symbol s
tickDirection string Direction of price change td
price24hPcnt string Percentage change of market price relative to 24h pP
lastPrice string Latest transaction price p
prevPrice24h string Price of 24 hours ago p24
highPrice24h string The highest price in the last 24 hours h
lowPrice24h string Lowest price in the last 24 hours l
markPrice string Mark price mp
indexPrice string Index_price ip
openInterest string Open interest. The update is not immediate - slowest update is 1 minute o
turnover24h string Turnover in the last 24 hours to
volume24h string Trading volume in the last 24 hours v
nextFundingTime string Next settlement time of capital cost (ms). Inverse futures is "" ft
fundingRate string Funding rate. Inverse futures is "" fr
bid1Price string Purchase price of the first order b1
ask1Price string Selling price of the first order a1
prevPrice1h string Hourly market price an hour ago p1
ReduceOnly string ReduceOnly Status ro
cs long Please ignore
ts long timestamp(ms). The time that system generates the data.

kline

How to Subscribe

ws.send('{"op":"subscribe","req_id": "10110001", "args":["candle.60.BTCUSDT"]}')

Response Example - format of all responses

{
    "topic": "candle.1.BTCUSDT",
    "data": [
        {
            "start": 1679544960,
            "end": 1679545020,
            "period": "1",
            "open": 27398,
            "close": 27409,
            "high": 27409,
            "low": 27390,
            "volume": "5.07",
            "turnover": "138909.63",
            "confirm": false,
            "cs": 17657145
        }
    ],
    "ts": 1679544971586546
}

Currently supported intervals:

Push frequency: 1-60s

Topic:

candle.{interval}.{symbol}

Response Parameters

Parameter Type Comment
topic string Topic name
data Object
>start integer Start timestamp point for result, in seconds
>end integer End timestamp point for result, in seconds
>period string Data refresh interval. Enum : 1 3 5 15 30 60 120 240 360 720 "D" "M" "W"
>open number Starting price
>close number Closing price
>high number Maximum price
>low number Minimum price
>volume string Trading volume
>turnover string Turnover
>confirm boolean Is confirm
cs number cross_seq
ts long timestamp(ms). The time that system generates the data.

Private Topics

position

How to Subscribe

ws.send('{"op":"subscribe","req_id": "10110001","args":["contract.position"]}');

Response Example - format of all responses

{
    "topic": "contract.position",
    "data": [
        {
            "userId": 139688,
            "symbol": "BCHUSDT",
            "size": 0.1,
            "side": "Buy",
            "positionValue": 28.35,
            "entryPrice": 283.5,
            "liqPrice": 0.01,
            "bustPrice": 0.01,
            "leverage": 10,
            "positionMargin": 427.80124,
            "takeProfit": 0,
            "tpTriggerBy": "UNKNOWN",
            "stopLoss": 0,
            "slTriggerBy": "UNKNOWN",
            "trailingStop": 0,
            "unrealisedPnl": -4.129,
            "autoAddMargin": 0,
            "cumRealisedPnl": -0.21757852,
            "positionStatus": "Normal",
            "adlRankIndicator": 2,
            "freeQty": 0.1,
            "tpSlMode": "Full",
            "riskId": 1,
            "isolated": false,
            "positionMode": "MergedSingle",
            "positionIdx": 0
        }
        ]
}

instruction:

Pushing the incremental volume only

Accessing personal position list. Current user's position holding information can be accessed through this interface, such as the quantity of position owned and wallet balance.

Topic:

contract.position

Response Parameters

Parameter Type Comment
userId string userId
symbol string Name of Contract
size float32 Position size
side string Direction
positionValue float32 Position value
entryPrice float32 Average entry value
liqPrice float32 Liquidation price
bustPrice float32 Bankruptcy price
leverage float32 Under the isolated margin mode, the value should be the leverage set by the user. Under the cross margin mode, the value should be the maximum leverage under the current risk limit. For contracts only, and not for options.
positionMargin float32 Position balance
unrealisedPnl string Unrealized P&L
cumRealisedPnl string Accumulatively realized P&L
autoAddMargin integer Auto add margin mode. 0: turn off, 1: turn on. It is invalid under cross margin mode
positionStatus string Update time
freeQty float32 freeQty
positionMode string positionMode
positionIdx integer The position idx is used to mark the position with different position modes: 0 - one-way mode; 1 - hedged position buy; 2 - hedged position sell.
riskId integer Risk ID
adlRankIndicator integer adlRankIndicator

execution

How to Subscribe

ws.send('{"op":"subscribe","req_id": "10110001","args":["contract.execution"]}');

Response Example - format of all responses

{
    "topic": "contract.execution",
    "data": [
        {
            "symbol": "BTCUSDT",
            "side": "Buy",
            "orderId": "789eb56a-c85d-11ed-a5d3-525400d110a3",
            "execId": "f7c92052-723e-5708-8afd-dce6608bad32",
            "orderLinkId": "",
            "execPrice": 28100,
            "orderQty": 1,
            "execType": "Trade",
            "execQty": 0.4,
            "execFee": -2.81,
            "leavesQty": 0.2,
            "isMaker": true,
            "execTime": "2023-03-22T02:58:51.906815Z",
            "updatedAtE9": 1690858192550670750,
        }
    ]
}

Instruction:

Get the user's filled history ranked by time in ascending order.

Topic:

contract.execution

Response Parameters

Parameter Type Comment
symbol string Name of Contract
side string Direction
orderId string Order ID
execId string Trading ID
orderLinkId string Institutional customized order ID
execPrice float32 Executed price
execQty float32 Executed quantity
execType string Execution type. Trade, Funding, AdlTrade, BustTrade
execFee float32 Trading fee
leavesQty string Remaining order quantity
execTime string Time of trade (unit: ms)
updatedAtE9 long updatedTime

order

How to Subscribe

ws.send('{"op":"subscribe","req_id": "10110001","args":["contract.order"]}');

Response Example - format of all responses

{
    "topic": "contract.order",
    "data": [
        {
            "userId": 139688,
            "symbol": "BTCUSDT",
            "orderId": "789eb56a-c85d-11ed-a5d3-525400d110a3",
            "orderLinkId": "",
            "side": "Buy",
            "orderType": "Limit",
            "price": 28100,
            "qty": 1,
            "leavesQty": 0.2,
            "lastExecPrice": 28100,
            "cumExecQty": 0.8,
            "cumExecValue": 22479.998,
            "cumExecFee": -5.62,
            "timeInForce": "GoodTillCancel",
            "orderStatus": "PartiallyFilled",
            "takeProfit": 0,
            "stopLoss": 0,
            "createTime": 1690855647288566156,
            "updateTime": 1690855647295584436,
            "reduceOnly": false,
            "closeOnTrigger": false,
            "positionIdx": 0
        }
    ]
}

Instruction:

Pushing incremental orders only. Merge active order with conditional order into one topic.

Topic:

contract.order

Response Parameters

Parameter Type Comment
userId string userId
symbol string Name of Contract
orderId string Order ID
orderLinkId string Institutional customized order ID
side string Direction
orderType string Order type
stopOrderType string Conditional order type
price float32 Order price
qty float32 Order quantity
leavesQty float32 Unfilled quantity
lastExecPrice float32 Filled price
cumExecQty float32 Total filled quantity
cumExecValue float32 Total order value of filled orders
timeInForce string Time in force
orderStatus string Order status
takeProfit string Take-profit price
stopLoss string Stop-loss price
createdTime string Time of Creation
updatedTime string Time of Update
reduceOnly bool Close position? True – close position, false – open position
closeOnTrigger bool Closed order? True – close order false – open order

wallet

How to Subscribe

ws.send('{"op": "subscribe", "req_id": "10110001", "args": ["contract.wallet"]}')

Response Example - format of all responses

{
    "topic": "contract.wallet",
    "data": [
        {
            "userId": 139688,
            "coin": "USDT",
            "equity": 3000527,
            "walletBalance": 3000819.5,
            "availableBalance": 2966554.8,
            "positionMargin": 30845.646,
            "orderMargin": 3419.0366,
            "unrealisedPnl": -292.469,
            "cumRealisedPnl": 819.33264
        }
    ]
}

Topic:

contract.wallet

Response Parameters

Parameter Type Comment
userId string userId
coin string Name of coin in wallet, such as BTC, ETH, USDT, and USDC.
equity float32 User assets
walletBalance float32 Wallet balance
availableBalance float32 Available balance
positionMargin float32 Position margin
orderMargin float32 Margin occupied by the current order
unrealisedPnl float32 Unrealized P&L
cumRealisedPnl float32 Accumulatively realized P&L

Enums Definitions

Below are the enumerator names for each endpoint's request and response parameters.

Side (side)

Category(category)

Symbol (symbol)

You can get all symbols with the Get Instrument Info endpoint.

Currency (currency/coin)

Contract Type(contractType)

Contract Status(status)

Account Type (from_account_type/to_account_type)

Wallet Fund Type (walletFundType / type)

Order Type (orderType)

Quantity (qty)

Price (price)

Time in Force (timeInForce)

Trigger Price Type (triggerBy)

Order (order)

This is used for sorting orders/trades in a specified direction.

Order Status (orderStatus/stopOrderStatus)

For Conditional Orders Only:

Cancel Type (cancelType)

Create Type (createType)

Exec Type (execType)

Liquidity Type (lastLiquidityInd)

Tick Direction Type (tickDirection)

It indicates price fluctuation relative to the last trade.

TP/SL mode (tpSlMode)

Take profit/stop loss mode

Candlestick interval (interval)

Date (startDate/endDate)

Follows the format: yyyy-mm-dd

Stop Order Type (stopOrderType)

Transaction-Log Type (type)

Order Filter (orderFilter)

Upgrade Result (result)

Errors

The Mufex API uses the following HTTP codes and error codes:

HTTP Code Meaning
200 Request is valid -- Your request is valid
403 Access denied -- You request too many times (refer to the IP rate limit)
404 Request path not found
Code Description
26200001 Server Timeout
26200002 Invalid Request: Check Timestamp and recv_window
26200003 Invalid api_key
20011005 API Key Not Found
26200004 Invalid Signature
26200005 Access Denied
26200006 Request Rate Exceeded
26200008 User Banned
26200010 IP Mismatch
26200016 Server Internal Error
26200018 IP Request Frequency Exceeded
26200014 Duplicate Request
14110001 Server Internal Error
14120001 Order Not Found
14120002 Quantity Must Be Greater Than Zero
14120003 Invalid Coin Selection
14120004 Idempotent Request
14120005 Parameter Error
14120006 Invalid Origin Header
14120007 Access Denied
14120008 User Banned
14120009 Non-unique order_link_id
14120010 Duplicate Order ID
14120011 Contract Count Exceeds Allowed Limit
14120012 Contract Count Significantly Above Limit
14120013 Order Price Out of Range
14120014 Missing Last Price
14120015 Order Price Out of Range
14120016 Duplicate Order Type
14120017 Position Not Found
14120018 Insufficient Wallet Balance
14120019 Action Denied: Position Undergoing Liquidation
14120020 Action Denied: Position Undergoing ADL
14120021 Invalid Position Status
14120022 Exit Order Error: qty != size