Perps REST API
Perps Market Endpoints
Query symbols
GET ${PERPS_ENDPOINT}/markets/symbols
Get perpetual contract information for all symbols.
curl -X GET ${PERPS_ENDPOINT}/markets/symbols \
-H 'Accept: application/json'Query Parameters
symbol
string
false
Symbol name, e.g. BTC-USD
Response
Query coins
GET ${PERPS_ENDPOINT}/markets/coins
Get information for all coins.
curl -X GET ${PERPS_ENDPOINT}/markets/coins \
-H 'Accept: application/json'Query Parameters
coin
string
false
Coin name, e.g. vUSDC
Response
Query tickers
GET ${PERPS_ENDPOINT}/markets/tickers
Get 24hr rolling window price change statistics for all perpetual symbols.
Query Parameters
symbol
string
false
Symbol name, e.g. BTC-USD
Response
Query mini tickers
GET ${PERPS_ENDPOINT}/markets/miniTickers
Get 24hr rolling window price change statistics for all perpetual symbols.
Query Parameters
symbol
string
false
Symbol name, e.g. BTC-USD
Response
Query mark prices
GET ${PERPS_ENDPOINT}/markets/mark-prices
Mark price information for symbols.
Query Parameters
symbol
string
false
Symbol name, e.g. BTC-USD
Response
Query book tickers
GET ${PERPS_ENDPOINT}/markets/bookTickers
Best price/qty on the order book for symbols.
Query Parameters
symbol
string
false
Symbol name, e.g. BTC-USD
Response
Query order book
GET ${PERPS_ENDPOINT}/markets/{symbol}/orderbook
Get order book depth for a perpetual symbol.
Path Parameters
symbol
string
true
Symbol name, e.g. BTC-USD
Query Parameters
limit
uint32
false
Depth limit. Default: 10, Max: 1000
Response
Query candles/klines
GET ${PERPS_ENDPOINT}/markets/{symbol}/klines
Get candlestick/kline data for a perpetual symbol.
Path Parameters
symbol
string
true
Symbol name, e.g. BTC-USD
Query Parameters
interval
string
true
Kline interval: 1m, 5m, 15m, 30m, 1h, 4h, 1D, 1W, 1M
startTime
uint64
false
Start time in milliseconds
endTime
uint64
false
End time in milliseconds
limit
uint32
false
Number of klines to return. Default: 500, Max: 1000
Response
Query recent trades
GET ${PERPS_ENDPOINT}/markets/{symbol}/trades
Get recent public trades for a perpetual symbol.
Path Parameters
symbol
string
true
Symbol name, e.g. BTC-USD
Query Parameters
limit
uint32
false
Number of trades to return. Default: 50, Max: 500
Response
Perps Account Endpoints
Query balances
GET ${PERPS_ENDPOINT}/accounts/{userAddress}/balances
Get current account balance.
Path Parameters
userAddress
HexString
true
User EVM address
Query Parameters
accountID
uint64
false
The sub-account ID of the user. Primary account ID is used by default.
Response
Query open orders
GET ${PERPS_ENDPOINT}/accounts/{userAddress}/orders
Get all open orders for an account.
Path Parameters
userAddress
HexString
true
User EVM address
Query Parameters
symbol
string
false
Filter by symbol name
accountID
uint64
false
The sub-account ID of the user. Primary account ID is used by default.
Response
Query open positions
GET ${PERPS_ENDPOINT}/accounts/{userAddress}/positions
Get all open positions for an account.
Path Parameters
userAddress
HexString
true
User EVM address
Query Parameters
accountID
uint64
false
The sub-account ID of the user. Primary account ID is used by default.
Response
Query state for frontend
GET ${PERPS_ENDPOINT}/accounts/{userAddress}/state
Get comprehensive account state for UI initialization. Includes balances, positions, open orders, and sync metadata.
Path Parameters
userAddress
HexString
true
User EVM address
Query Parameters
accountID
uint64
false
The sub-account ID of the user. Primary account ID is used by default.
Response
Query API Keys
GET ${PERPS_ENDPOINT}/accounts/{userAddress}/api-keys
Get list of API keys.
Path Parameters
userAddress
HexString
true
User EVM address
Query Parameters
accountID
uint64
false
The sub-account ID of the user. Primary account ID is used by default.
name
string
false
The name of the API key.
Response
Query fee rate
GET ${PERPS_ENDPOINT}/accounts/{userAddress}/fee-rate
Get the current maker/taker fee rates for the account, including fee tier, staking tier, and maker rebate tier. Optionally pass a symbol to include the symbol-level fee discount.
Path Parameters
userAddress
HexString
true
User EVM address
Query Parameters
accountID
uint64
false
The sub-account ID of the user. Primary account ID is used by default.
symbol
string
false
Symbol name, e.g. BTC-USD. When provided, the symbol-level fee discount is applied.
Response
Query order history
GET ${PERPS_ENDPOINT}/accounts/{userAddress}/orders/history
Get historical orders (filled, canceled, expired) for an account.
Path Parameters
userAddress
HexString
true
User EVM address
Query Parameters
accountID
uint64
false
The sub-account ID of the user. Primary account ID is used by default.
symbol
string
false
Filter by symbol name
startTime
uint64
false
Start time in milliseconds
endTime
uint64
false
End time in milliseconds
limit
uint32
false
Number of orders to return. Default: 50, Max: 500
Response
Query position history
GET ${PERPS_ENDPOINT}/accounts/{userAddress}/positions/history
Get historical positions (closed) for an account.
Path Parameters
userAddress
HexString
true
User EVM address
Query Parameters
accountID
uint64
false
The sub-account ID of the user. Primary account ID is used by default.
symbol
string
false
Filter by symbol name
startTime
uint64
false
Start time in milliseconds
endTime
uint64
false
End time in milliseconds
limit
uint32
false
Number of positions to return. Default: 50, Max: 500
Response
Query trades
GET ${PERPS_ENDPOINT}/accounts/{userAddress}/trades
Get historical trade executions for an account.
Path Parameters
userAddress
HexString
true
User EVM address
Query Parameters
accountID
uint64
false
The sub-account ID of the user. Primary account ID is used by default.
symbol
string
false
Filter by symbol name
orderID
uint64
false
Filter by order ID
startTime
uint64
false
Start time in milliseconds
endTime
uint64
false
End time in milliseconds
limit
uint32
false
Number of trades to return. Default: 100, Max: 1000
Response
Query funding history
GET ${PERPS_ENDPOINT}/accounts/{userAddress}/fundings
Get historical funding payments (paid or received) for an account.
Path Parameters
userAddress
HexString
true
User EVM address
Query Parameters
accountID
uint64
false
The sub-account ID of the user. Primary account ID is used by default.
symbol
string
false
Filter by symbol name
positionID
uint64
false
Filter by position ID
startTime
uint64
false
Start time in milliseconds
endTime
uint64
false
End time in milliseconds
limit
uint32
false
Number of trades to return. Default: 100, Max: 1000
Response
Transfer asset to spot
POST ${PERPS_ENDPOINT}/accounts/transfers
Transfer assets between accounts.
Auth: signed write
Request Body
See TransferAssetRequest in Schema
Additional Information:
Number of decimal places of
transfer.amountshould not exceed coin precision. That istransfer.amount % 10^{-coin.precision} = 0.The
transfer.amountmust be a positive value.Number of decimal places of
transfer.amountshould not exceed coin precision.Transfer asset to spot chain:
transfer.toAccountID=999,transfer.type=SPOT_WITHDRAWTransfer assets to the EVM chain is not supported yet.
Internal transfer between perps chains is not supported yet.
The request is rejected when margin check failed.
Response
data
ResponseData
Response data when code is 0.
ResponseDataNameTypeRequiredDescriptioniduint64trueIdentifier for this transfer request. Same as
idinTransferAssetRequest.
Perps Trading Endpoints
Place multiple orders
POST ${PERPS_ENDPOINT}/trade/orders
Submit one or more perpetual orders in a single signed payload.
Auth: signed write
Request Body
Find PerpsNewOrderRequest and PerpsOrderItem in Schema
Additional Information:
Basic Validation
The batch cannot be empty.
The length of batch should less than or equals to
100.The
order[i].clOrdIDmust match^[0-9a-zA-Z_-]{1,36}$.The
order[i].clOrdIDmust be unique among open orders. Reuse is allowed only after the previous order is filled.For limit order
order[i].timeInForcecan beGTC,IOC,GTX.provide both
order[i].priceandorder[i].quantity, do not sendorder[i].funds.
For Market order
order[i].timeInForcemust beIOC.Provide either
order.quantityororder[i].funds, not both.order[i].fundsonly available for market buy orders.order[i].priceoptional for slippage protection.
The order will be rejected if basic validation failed.
Price filter
The decimal precision of order price should not exceed
symbol.pricePrecision. That isorder[i].price % 10^{-symbol.pricePrecision} = 0.The order price must be multiple of
symbol.tickSize. That isorder[i].price % symbol.tickSize = 0.If
symbol.minPriceis not0, the order price should greater than or equals tosymbol.minPrice.If
symbol.maxPriceis not0, the order price should less than or equals tosymbol.maxPrice.The decimal precision of order stop price should not exceed
symbol.pricePrecision. That isorder[i].stopPrice % 10^{-symbol.pricePrecision} = 0.The order stop price must be multiple of
symbol.tickSize. That isorder[i].stopPrice % symbol.tickSize = 0.If
symbol.minPriceis not0, the order stop price should greater than or equals tosymbol.minPrice.If
symbol.maxPriceis not0, the order stop price should less than or equals tosymbol.maxPrice.The order will be rejected if price filter check failed.
Lot size filter
The decimal precision of order quantity should not exceed
symbol.quantityPrecision. That isorder[i].quantity % 10^{-symbol.quantityPrecision} = 0.The order quantity must be multiple of
symbol.stepSize. That isorder[i].quantity % symbol.stepSize = 0.If
symbol.minQuantityis not0, the order quantity should greater than or equals tosymbol.minQuantity.If
symbol.maxQuantityis not0, the order quantity should less than or equals tosymbol.maxQuantity.The order will be rejected if lot size filter check failed.
Market lot size filter
This is an additional check for market order.
If
symbol.marketMinQuantityis not0, the order quantity should greater than or equals tosymbol.marketMinQuantity.If
symbol.marketMaxQuantityis not0, the order quantity should less than or equals tosymbol.marketMaxQuantity.The order will be rejected if market lot filter check failed.
Notional filter
For limit order, the order notional is
order[i].price * order[i].quantity.For market order with
order[i].fundsprovided, the order notional isorder[i].funds.For market order without
order[i].funds, the order notional is estimated assymbol.lastTradePrice * order[i].quantity.If
symbol.minNotionalis not0, the order notional should greater than or equals tosymbol.minNotional.If
symbol.maxNotionalis not0, the order notional should less than or equals tosymbol.maxNotional.The order will be rejected if notional filter check failed.
Margin check
The order will be rejected if account margin is not enough to place the order.
Other price limitation for non-TP/SL orders.
for limit buy orders, the order price should less than or equal to
symbol.markPrice * (1 + symbol.buyLimitUpRatio). Otherwise, the order is rejected.for limit sell orders, the order price should greater than or equal to
symbol.markPrice * (1 - symbol.sellLimitDownRatio). Otherwise, the order is rejected.for market buy orders without price, the final execution price is bounded by
symbol.indexPrice * (1 + symbol.marketDeviationRatio). If price is provided, the final execution price is bounded bymin(order[i].price, symbol.indexPrice * (1 + symbol.marketDeviationRatio))for market sell orders without price, the final execution price is bounded by
symbol.indexPrice * (1 - symbol.marketDeviationRatio). If price is provided, the final execution price is bounded bymax(order[i].price, symbol.indexPrice * (1 - symbol.marketDeviationRatio))
For order with TP/SL
The length of batch should be
2or3.The
orders[0].modifier = BRACKET,orders[1 or 2].modifier = ATTACHED_STOP.The
orders[0].reduceOnly = false,orders[1 or 2].reduceOnly = true.The
orders[1 or 2].stopPrice,orders[1 or 2].stopType,orders[1 or 2].triggerTypeare provided.Only one of
orders[1]andorders[2]is take profit order.Only one of
orders[1]andorders[2]is stop loss order.
For Position with TP/SL
The user has a position with this symbol.
The
orders[i].modifier = STOP.The
orders[i].reduceOnly = true.The
orders[i].stopPrice,orders[i].stopType,orders[i].triggerTypeare provided.For TP/SL without quantity, it is treated as global TP/SL. When triggered, generated order will have full position size as quantity.
For TP/SL without order and position (standalone TP/SL)
orders[i].modifier = STOPorders[i].reduceOnly = falseThe
orders[i].stopPrice,orders[i].stopType,orders[i].triggerTypeare provided.
Response
data
Array<ResponseData>
Response data when code is 0.
ResponseDataNameTypeRequiredDescriptioncodeint32trueResponse status code,
0for success and other code for failure.clOrdIDstringtrueClient order id; same as
clOrdIDinPerpsNewOrderRequest.errorstringfalseError description for individual order. Only provided when code is not
0.orderIDuint64falseOrder id. Only provided when the code is
0.
The length of the response result array is usually the same as the length of batched request.
Important: Some errors are a deterministic function of the payload itself, and these are instead returned earlier as part of pre-validation. In this case, only one error is returned for the entire payload, as some of these errors do not apply to a specific order.
For API users that use batching, it's recommended to handle the case where a single error is returned for a batch of multiple orders. In this case, the response could be duplicated n times before being sent to the callback function, as the whole batch was rejected for this same reason.
Cancel multiple orders
DELETE ${PERPS_ENDPOINT}/trade/orders
Cancel one or more orders by order ID or client order ID.
Auth: signed write
Request Body
Find PerpsCancelOrderRequest and PerpsCancelItem in Schema
Additional Information:
The batch cannot be empty.
The length of batch should less than or equals to
100.The
cancel[i].clOrdIDshould match^[0-9a-zA-Z_-]{1,36}$, if provided.Provide either
cancel[i].orderIDorcancel[i].clOrdID, but not both.
Response
data
Array<ResponseData>
Response data when code is 0.
ResponseDataNameTypeRequiredDescriptioncodeint32trueResponse status code,
0for success and other code for failure.clOrdIDstringtrueClient order id; same as
clOrdIDinPerpsCancelOrderRequest.errorstringfalseError description for individual order. Only provided when code is not
0.orderIDuint64falseOrder id. Only provided when the code is
0.
The length of the response result array is usually the same as the length of batched request.
Important: Some errors are a deterministic function of the payload itself, and these are instead returned earlier as part of pre-validation. In this case, only one error is returned for the entire payload, as some of these errors do not apply to a specific order.
For API users that use batching, it's recommended to handle the case where a single error is returned for a batch of multiple orders. In this case, the response could be duplicated n times before being sent to the callback function, as the whole batch was rejected for this same reason.
Replace multiple orders
POST ${PERPS_ENDPOINT}/trade/orders/replace
Replace/modify existing orders atomically.
Auth: signed write
Request Body
See ReplaceOrderRequest in Schema
Additional Information:
Basic Validation
The batch cannot be empty.
The length of batch should less than or equals to
100.Only limit
GTCand limitGTXcan be replaced.Only non-TP/SL order with status
NEWandPARTIALLY_FILLEDcan be replaced.Either
replace.origOrderIDorreplace.origClOrdIDshould be provided, but not both.At least one of
replace.priceandreplace.quantityshould be provided.
Price filter
The decimal precision of replacement price should not exceed
symbol.pricePrecision, if provided. That isreplace.price % 10^{-symbol.pricePrecision} = 0.The replacement price must be multiple of
symbol.tickSize. That isreplace.price % symbol.tickSize = 0.If
symbol.minPriceis not0, the replacement price should greater than or equals tosymbol.minPrice.If
symbol.maxPriceis not0, the replacement price should less than or equals tosymbol.maxPrice.The replacement will be rejected if price filter check failed.
Lot size filter
The decimal precision of replacement quantity should not exceed
symbol.quantityPrecision. That isreplace.quantity % 10^{-symbol.quantityPrecision} = 0.The replacement quantity must be multiple of
symbol.stepSize. That isreplace.quantity % symbol.stepSize = 0.If
symbol.minQuantityis not0, the replacement quantity should greater than or equals tosymbol.minQuantity.If
symbol.maxQuantityis not0, the replacement quantity should less than or equals tosymbol.maxQuantity.The replacement will be rejected if lot size filter check failed.
Notional filter
The replacement notional is
replace.price * replace.quantity. Ifreplace.pricenot provided,order.priceis used. Ifreplace.quantitynot provided,order.quantityis used.If
symbol.minNotionalis not0, the replacement notional should greater than or equals tosymbol.minNotional.If
symbol.maxNotionalis not0, the replacement notional should less than or equals tosymbol.maxNotional.The replacement will be rejected if notional filter check failed.
Margin check
The replacement will be rejected if account margin is not enough to replace the order.
Response
data
Array<ResponseData>
Response data when code is 0.
ResponseDataNameTypeRequiredDescriptioncodeint32trueResponse status code,
0for success and other code for failure.clOrdIDstringtrueClient order id; same as
clOrdIDinReplaceParams.errorstringfalseError description for individual order. Only provided when code is not
0.orderIDuint64falseOrder id of the replaced order. Only provided when the code is
0.
The length of the response result array is usually the same as the length of batched request.
Important: Some errors are a deterministic function of the payload itself, and these are instead returned earlier as part of pre-validation. In this case, only one error is returned for the entire payload, as some of these errors do not apply to a specific order.
For API users that use batching, it's recommended to handle the case where a single error is returned for a batch of multiple orders. In this case, the response could be duplicated n times before being sent to the callback function, as the whole batch was rejected for this same reason.
Modify TP/SL order
POST ${PERPS_ENDPOINT}/trade/orders/modify
Replace/modify an existing TP/SL order.
Auth: signed write
Request Body
See ModifyOrderRequest in Schema
Additional Information:
The order must be a TP/SL order.
Provide either
modify.orderIDorcmodify.lOrdID, but not both.Provide at least one of
modify.price,modify.quantity, ormodify.stopPrice.The
modify.priceandmodify.stopPricemust pass price filter.The
modify.quantitymust pass lot size filter and market lot size filter.The
modify.priceandmodify.quantitymust pass notional filter.
Response
No endpoint-specific
datapayload.
Schedule cancel orders
POST ${PERPS_ENDPOINT}/trade/orders/schedule-cancel
Schedule a cancel-all operation at a future time. Omitting the time clears the scheduled cancel.
Auth: signed write
Request Body
See ScheduleCancelRequest in Schema
accountID
uint64
true
Account identifier.
scheduledTimestamp
uint64
false
Unix timestamp in milliseconds when the cancel-all should be triggered.
Additional Information:
The scheduled time must be at least
5seconds after the current time.When triggered, all open orders are canceled and a trigger count increments (max
10per day, resets at00:00 UTC).Omitting
scheduledTimestampremoves the scheduled cancel.
Response
No endpoint-specific
datapayload.
Update leverage
POST ${PERPS_ENDPOINT}/trade/leverage
Update leverage and margin mode for a symbol.
Auth: signed write
Request Body
See UpdateLeverageRequest in Schema
Additional Information:
The leverage must less than or equals to
symbol.maxLeverage.The request is rejected when this account has open orders or open positions on this symbol.
Response
No endpoint-specific
datapayload.
Update isolated margin
POST ${PERPS_ENDPOINT}/trade/margin
Add or remove margin from an isolated position.
Auth: signed write
Request Body
See UpdateMarginRequest in Schema
Additional Information:
Number of decimal places of
transfer.amountshould not exceed coin (vUSDC) precision. That istransfer.amount % 10^{-coin.precision} = 0.The
transfer.amountmust be a non-zero value.The request is rejected when margin check failed.
Response
No endpoint-specific
datapayload.
Last updated