Schema

Enums

Request fields whose restrictions say "use integer value of the enum" use the integer value. REST and WebSocket response fields use the corresponding status string unless stated otherwise.

OrderSideEnum

Status String	Integer Value	Description
BUY	1	Buy order
SELL	2	Sell order

OrderTypeEnum

Status String	Integer Value	Description
LIMIT	1	Limit order
MARKET	2	Market order

TimeInForceEnum

Status String	Integer Value	Description
GTC	1	Good Til Canceled. An order stays on the book unless canceled.
FOK	2	Fill or Kill (not supported yet). Expires if not fully filled immediately.
IOC	3	Immediate Or Cancel. Fills as much as possible before expiring.
GTX	4	Post Only. Expires if the order would be filled immediately.

TransferAssetTypeEnum

Status String	Integer Value	Description
EVM_DEPOSIT	0	Indicate this transfer is a deposit from the evm chain.
PERPS_DEPOSIT	1	Indicate this transfer is a deposit from the perps chain.
EVM_WITHDRAW	2	Indicate this transfer is a withdrawal to the evm chain.
PERPS_WITHDRAW	3	Indicate this transfer is a withdrawal to the perps chain.
INTERNAL	4	Indicate this transfer is an internal transfer.
SPOT_WITHDRAW	5	Indicate this transfer is a withdrawal to the spot chain.
SPOT_DEPOSIT	6	Indicate this transfer is a deposit to the spot chain.

APIKeyTypeEnum

Status String	Integer Value	Description
EVM	1	Use evm private key as secret key and evm address as public key.

APIKeyPermissionEnum

permissions is a bit mask. A bit value of 1 means the permission is disabled. If permissions is omitted, all permissions are enabled.

Status String	Bit Index	Bit Value	Description
TRADE	0	1	Place, replace, modify, and cancel orders; schedule cancels; update perps leverage, margin, and collateral.
CANCEL	1	2	Cancel orders and schedule cancels.
WITHDRAW	2	4	Withdraw from spot or perps to EVM or the other engine.
TRANSFER	3	8	Sub-account and internal transfers within spot or perps.

SignatureTypeEnum

Status String	Integer Value	Description
EIP712	1	EIP-712 signature with engine-specific domain.
EIP712_UNIVERSAL	2	EIP-712 signature with universal domain for cross-engine user actions such as AddAPIKey, AddPermissionedAPIKey, and ApproveBuilderFee.

OrderStatusEnum

Status String	Integer Value	Description
NEW	1	The order has been accepted into the engine.
PARTIALLY_FILLED	2	The order is partially filled in the engine.
FILLED	3	The order is fully filled in the engine.
CANCELED	4	The order has been canceled by the user.
REJECTED	5	The order has been rejected and was not processed.
EXPIRED	6	The order expired according to order rules (FOK, IOC, etc.)
TRIGGERED	10	perps only, for triggered TP/SL orders

DcaOrderStatusEnum

Status String	Integer Value	Description
ACTIVE	1	Waiting for or continuing scheduled executions.
CANCELLED	2	Cancelled by the user or system.
TERMINATED	3	Stopped after three consecutive execution failures.
PRUNED	4	Removed when the account state is pruned.

ExecutionTypeEnum

Status String	Integer Value	Description
NEW	1	The order has been accepted into the engine.
PARTIALLY_FILLED	2	The order is partially filled in the engine.
FILLED	3	The order is fully filled in the engine.
CANCELED	4	The order has been canceled by the user.
REJECTED	5	The order has been rejected and was not processed.
MODIFIED	6	The order has been modified, only reduce size.
EXPIRED	7	The order was canceled according to the order type's rules (e.g. LIMIT FOK orders with no fill, LIMIT IOC or MARKET orders that partially fill)
REPLACED	8	The order has been amended, both size and price changed.

OrderModifierEnum - perps only

Status String	Integer Value	Description
NORMAL	1	Normal order.
STOP	2	Stop order.
BRACKET	3	Normal order in order with TP/SL group.
ATTACHED_STOP	4	Stop order in order with TP/SL group.

MarginModeEnum - perps only

Status String	Integer Value	Description
ISOLATED	1	Isolated margin mode.
CROSS	2	Cross margin mode.

PositionSideEnum - perps only

Status String	Integer Value	Description
BOTH	1	Oneway mode.
LONG	2	Hedge mode. not supported in order placement yet
SHORT	3	Hedge mode. not supported in order placement yet

StopTypeEnum - perps only

Status String	Integer Value	Description
STOP_LOSS	1	Stop loss order.
TAKE_PROFIT	2	Take profit order.

TriggerTypeEnum - perps only

Status String	Integer Value	Description
LAST_PRICE	1	Trigger by last trade price. not supported in order placement yet
MARK_PRICE	2	Trigger by mark price.
INDEX_PRICE	3	Trigger by index price. not supported in order placement yet

Hex String

A string starts with 0x, the rest parts consist of 0 to 9, a to z and A to Z.

Decimal String

The canonical form of a decimal string is a standardized representation that removes ambiguity and allows for direct comparison. Key rules include removing the optional plus sign, prohibiting exponential notation, and ensuring there is at least one digit to the left and right of the decimal point.

Examples

Original String	Canonical Form	Reason
00123	123	Remove leading zeros.
+32.1	32.1	Remove the leading plus sign.
32.100	32.1	Remove trailing zeros.
0.500	0.5	Remove trailing zeros.
1.234e+2	123.4	Convert from exponential notation and remove trailing zeros.
001.230	1.23	Remove leading zeros and trailing zeros.

REST Types

Exchange Types

Common Types

BuilderParams

Builder parameters embedded in signed write requests.

Name	Type	Required	Restrictions	Description
id	uint64	true	non-zero	Builder account ID
fee	uint64	true	none	Requested builder fee rate in tenths of a basis point. 10 requests 1 bp of the fill notional. The actual rate is subject to the user's approval and the engine cap.

AddAPIKeyRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	Target primary or subaccount ID
name	string	true	should match ^[0-9a-zA-Z_-]{1,36}$	Name of API key
type	APIKeyTypeEnum	true	use integer value of the enum	Type of API key
publicKey	HexString	true	none	Public key bytes in hex
expiresAt	uint64	true	none	Timestamp in milliseconds.
builder	BuilderParams	false	none	Optional builder fee approval to include with this API key.

AddPermissionedAPIKeyRequest

Use this request body to create an API key with selected permissions disabled. The builder field is not supported in this request. permissions must disable TRADE, CANCEL, or both; enabling both TRADE and CANCEL is not supported.

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	Target primary or subaccount ID
name	string	true	should match ^[0-9a-zA-Z_-]{1,36}$	Name of API key
type	APIKeyTypeEnum	true	use integer value of the enum	Type of API key
publicKey	HexString	true	valid EVM address	API key public key
expiresAt	uint64	true	none	Timestamp in milliseconds.
permissions	uint64	true	bit mask	Permission mask. A set bit disables the corresponding APIKeyPermissionEnum.

ApproveBuilderFeeRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	Primary account ID of the user
builderID	uint64	true	non-zero	Builder account ID
maxFeeRate	uint64	true	0 to 2000	Maximum builder fee rate in tenths of basis points. 0 clears it. Spot orders are capped at 2000 (2%); Perps at 200 (0.2%).

RevokeAPIKeyRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	Target primary or subaccount ID
name	string	true	should match ^[0-9a-zA-Z_-]{1,36}$	Name of the API key to revoke

TransferAssetRequest

Name	Type	Required	Restrictions	Description
id	uint64	true	none	The unique identifier for this transfer request.
fromAccountID	uint64	true	none	The account ID of sender.
toAccountID	uint64	true	none	The account ID of receiver.
coinID	uint64	true	none	The coinID to send.
amount	DecimalString	true	positive value	The amount of coin to send.
type	TransferAssetTypeEnum	true	use integer value of the enum	Type of transfer

ReplaceOrderRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	The account ID
orders	Array<ReplaceParams>	true	non-empty	List of non-empty order replacement

ReplaceParams

Name	Type	Required	Restrictions	Description
symbolID	uint64	true	none	The symbol ID
clOrdID	string	true	should match ^[0-9a-zA-Z_-]{1,36}$	The unique identifier for this replacement request.
origOrderID	uint64	false	none	The unique identifier of the order to be replaced.
origClOrdID	string	false	should match ^[0-9a-zA-Z_-]{1,36}$	The client-provided identifier of the order to be replaced.
price	DecimalString	false	none	The new price for the order
quantity	DecimalString	false	none	The new quantity for the order

NewDcaOrderRequest

Shared by Spot and Perps. Spot plans require a USDC-quoted symbol.

Name	Type	Required	Restrictions	Description
accountID	uint64	true	non-zero	Primary account or sub-account that owns the plan and provides funds or margin.
symbolID	uint64	true	non-zero	Trading symbol ID; Spot requires USDC as the quote coin.
side	OrderSideEnum	true	1 (BUY), 2 (SELL)	Side of each child execution order.
amount	DecimalString	true	at least 10 USDC; canonical string; symbol limits and settlement precision apply	USDC notional for each BUY or SELL execution. See amount and funding for Spot and Perps behavior.
schedule	DcaSchedule	true	see below	Recurring UTC schedule.
minPrice	DecimalString	false	positive canonical string; <= maxPrice when both set	Inclusive lower bound on the reference price for attempting an execution.
maxPrice	DecimalString	false	positive canonical string; >= minPrice when both set	Inclusive upper bound on the reference price for attempting an execution.
randomize	bool	false	defaults to false; must be false for interval	Randomize calendar execution within the selected UTC hour. The amount stays fixed.
immediate	bool	false	defaults to false	Request an initial attempt without waiting for the scheduled time; later attempts follow schedule.

Price bounds use the order-book midpoint for Spot and mark price for Perps. See execution rules.

Include both boolean fields in signed parameters, even when false. See Authentication & Signing for serialization and signing.

DcaSchedule

Name	Type	Required	Description
kind	string	true	interval, daily, weekly, biweekly or monthly.
hour	uint32	true	Interval duration in hours for interval; UTC hour of day, 0–23, for calendar schedules. Include midnight as 0.
day	uint32	false	Provide a weekday for weekly/biweekly or day of month for monthly; omit for interval and daily.

Allowed hour and day values for each schedule kind:

kind	hour	day
interval	1, 4, 8, 12 hours	omitted
daily	0–23 UTC	omitted
weekly / biweekly	0–23 UTC	1–7, Monday=1, Sunday=7
monthly	0–23 UTC	1–31

See schedules and examples for execution timing.

CancelDcaOrderRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	non-zero	Primary account or sub-account that owns the plan.
symbolID	uint64	true	non-zero	Trading symbol of the plan.
orderID	uint64	true	non-zero	Parent plan ID returned by creation or plan queries. Child execution order IDs cannot be used here.

ScheduleCancelRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	The account ID
scheduledTimestamp	uint64	false	none	none

Spot only types

BatchNewOrderRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	none
orders	Array<BatchNewOrderItem>	true	non-empty	List of non-empty orders
builder	BuilderParams	false	none	Optional builder for every order in the batch

BatchNewOrderItem

Name	Type	Required	Restrictions	Description
symbolID	uint64	true	none	none
clOrdID	string	true	should match ^[0-9a-zA-Z_-]{1,36}$	none
side	OrderSideEnum	true	use integer value of the enum	none
type	OrderTypeEnum	true	use integer value of the enum	none
timeInForce	TimeInForceEnum	true	use integer value of the enum	none
price	DecimalString	false	none	none
quantity	DecimalString	false	none	none
funds	DecimalString	false	none	market buy orders only

BatchCancelOrderRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	none
cancels	Array<BatchCancelOrderItem>	true	non-empty	List of non-empty order cancellations

BatchCancelOrderItem

Name	Type	Required	Restrictions	Description
symbolID	uint64	true	none	none
clOrdID	string	true	should match ^[0-9a-zA-Z_-]{1,36}$	The unique identifier for this cancellation request.
orderID	uint64	false	none	The unique identifier of the order to be canceled.
origClOrdID	string	false	should match ^[0-9a-zA-Z_-]{1,36}$	The client-provided identifier of the order to be canceled.

NewTwapOrderRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	The account ID
symbolID	uint64	true	none	Symbol ID
side	OrderSideEnum	true	use integer value of the enum	Order side
quantity	DecimalString	true	positive value	TWAP total quantity
minutes	uint64	true	5 to 1440	TWAP duration in minutes
randomize	bool	true	none	Whether to randomize slices

CancelTwapOrderRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	The account ID
symbolID	uint64	true	none	Symbol ID
orderID	uint64	true	non-zero	TWAP order ID

Perps only types

PerpsNewOrderRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	The account ID
symbolID	uint64	true	none	Symbol ID
orders	Array<PerpsOrderItem>	true	non-empty	List of orders to submit
builder	BuilderParams	false	none	Optional default builder for every order

PerpsOrderItem

Name	Type	Required	Restrictions	Description
clOrdID	string	true	should match ^[0-9a-zA-Z_-]{1,36}$	Client order ID (unique per account)
modifier	OrderModifierEnum	true	use integer value of the enum	Order modifier
side	OrderSideEnum	true	use integer value of the enum	Order side
type	OrderTypeEnum	true	use integer value of the enum	Order type
timeInForce	TimeInForceEnum	true	use integer value of the enum	Time in force
price	DecimalString	false	none	none
quantity	DecimalString	false	none	none
funds	DecimalString	false	none	Market buy orders only
stopPrice	DecimalString	false	none	Trigger price for TP/SL
stopType	StopTypeEnum	false	use integer value of the enum	Stop type for TP/SL
triggerType	TriggerTypeEnum	false	use integer value of the enum	For TP/SL; only MARK_PRICE supported
reduceOnly	bool	true	none	Reduce-only flag
positionSide	PositionSideEnum	true	use integer value of the enum	Only BOTH is supported

PerpsNewTwapOrderRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	The account ID
symbolID	uint64	true	none	Symbol ID
side	OrderSideEnum	true	use integer value of the enum	Order side
quantity	DecimalString	true	positive value	TWAP total quantity
minutes	uint64	true	5 to 1440	TWAP duration in minutes
randomize	bool	true	none	Whether to randomize slices
reduceOnly	bool	true	none	Reduce-only flag

PerpsCancelOrderRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	The account ID
cancels	Array<PerpsCancelItem>	true	non-empty	List of orders to cancel

PerpsCancelItem

Name	Type	Required	Restrictions	Description
symbolID	uint64	true	none	Symbol ID
orderID	uint64	false	none	The order ID to cancel
clOrdID	string	false	should match ^[0-9a-zA-Z_-]{1,36}$	The client order ID

ModifyOrderRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	Account ID
symbolID	uint64	true	none	Symbol ID
orderID	uint64	false	none	Order to be replaced
clOrdID	string	false	should match ^[0-9a-zA-Z_-]{1,36}$	Client-provided identifier to replace
price	DecimalString	false	none	The new price
quantity	DecimalString	false	none	The new quantity
stopPrice	DecimalString	false	none	The new stop price

UpdateLeverageRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	The account ID
symbolID	uint64	true	none	Symbol ID
leverage	uint32	true	none	Leverage level
marginMode	MarginModeEnum	true	use integer value of the enum	1=ISOLATED, 2=CROSS

UpdateMarginRequest

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	The account ID
symbolID	uint64	true	none	Symbol ID
amount	DecimalString	true	non-zero	Amount to add (positive) or remove (negative)

UpdateCollateralRequest

Testnet only. This request is currently supported on testnet environments only.

Name	Type	Required	Restrictions	Description
accountID	uint64	true	none	The account ID
coinID	uint64	true	non-USDC coin only	Coin ID of the collateral asset. 0 is rejected.
amount	DecimalString	true	non-zero, precision	Amount to add (positive) or remove (negative).

REST Response

Succeed Response

Properties

Name	Type	Required	Restrictions	Description
code	int32	true	none	Always 0
data	Object	true	none	Check format in each endpoint
timestamp	uint64	true	none	The timestamp in milliseconds when this response is just sent.

Examples

{
  "code": 0,
  "data": null,
  "timestamp": 1767501757000
}

Error Response

Properties

Name	Type	Required	Restrictions	Description
code	int32	true	none	Error code. Always negative.
error	string	true	none	Error message
timestamp	uint64	true	none	The timestamp in milliseconds when this response is just sent.

Examples

{
  "code": -1,
  "error": "nonce is invalid",
  "timestamp": 1767501757000
}

User Rate Limit

UserRateLimit

Name	Type	Required	Description
userID	uint64	true	Internal user ID
cumulativeTxNum	uint64	true	Cumulative transaction/action count used for transaction quota
cumulativeCancelNum	uint64	true	Cumulative cancel count used for cancel quota
cumulativeVolume	DecimalString	true	Cumulative trading volume in USDC
transactionQuota	int64	true	Total transaction/action quota, including trading volume and base override
transactionQuotaUsed	uint64	true	Cumulative transactions/actions used
transactionQuotaRemaining	int64	true	Remaining transaction/action quota. Returns 0 when exhausted
transactionQuotaOverridden	bool	true	Whether a configured transaction limit override replaces the default base quota
cancelQuota	int64	true	Total cancel quota
cancelQuotaUsed	uint64	true	Cumulative cancels used
cancelQuotaRemaining	int64	true	Remaining cancel quota. Returns 0 when exhausted

Announcement

AnnouncementArticle

Name	Type	Required	Description
id	int64	true	Announcement ID
externalId	string	true	External announcement identifier
style	string	true	Announcement style
title	string	true	Announcement title
label_names	Array<string>	true	Announcement labels. Empty array when no labels.
startTime	int64	true	Start time in milliseconds
endTime	int64	true	End time in milliseconds
createdAt	int64	true	Creation time in milliseconds
updatedAt	int64	true	Last update time in milliseconds

AnnouncementList

Name	Type	Required	Description
articles	Array<AnnouncementArticle>	true	Announcement summaries
page	int	true	Current page number
size	int	true	Page size
count	int64	true	Total number of announcements

AnnouncementDetail

AnnouncementDetail includes all fields from AnnouncementArticle, plus:

Name	Type	Required	Description
body	string	true	Announcement body

Symbol

SpotSymbol

Name	Type	Required	Description
id	uint64	true	Unique symbol ID
name	string	true	Unique symbol name, e.g. vBTC_vUSDC
displayName	string	true	Display name for UI, e.g. BTC/USDC
baseCoinID	uint64	true	Base coin ID
baseCoin	string	false	Base coin name
baseCoinPrecision	uint8	false	Base coin precision
quoteCoinID	uint64	true	Quote coin ID
quoteCoin	string	false	Quote coin name
quoteCoinPrecision	uint8	false	Quote coin precision
pricePrecision	int32	true	Decimal precision of order price. Price filter parameters.
tickSize	DecimalString	true	Tick size of order price. Price filter parameters.
minPrice	DecimalString	true	Minimum order price. Price filter parameters.
maxPrice	DecimalString	true	Maximum order price. Price filter parameters.
quantityPrecision	int32	true	Decimal precision of order quantity. Lot size filter parameters.
stepSize	DecimalString	true	Step size of order quantity. Lot size filter parameters.
minQuantity	DecimalString	true	Minimum order quantity. Lot size filter parameters.
maxQuantity	DecimalString	true	Maximum order quantity. Lot size filter parameters.
marketMinQuantity	DecimalString	true	Minimum order quantity in market order. Market lot size filter parameters.
marketMaxQuantity	DecimalString	true	Maximum order quantity in market order. Market lot size filter parameters.
minNotional	DecimalString	true	Minimum order notional value. Notional filter parameters.
maxNotional	DecimalString	true	Maximum order notional value. Notional filter parameters.
buyLimitUpRatio	DecimalString	true	Limit order price limitation parameters
sellLimitDownRatio	DecimalString	true	Limit order price limitation parameters
marketDeviationRatio	DecimalString	true	Market order price limitation parameters
makerFee	DecimalString	true	Default maker fee ratio
takerFee	DecimalString	true	Default taker fee ratio
status	string	true	TRADING, HALT

PerpsSymbol

Name	Type	Required	Description
id	uint64	true	Symbol ID
name	string	true	Symbol name, e.g. BTC-USD
displayName	string	true	Symbol name in UI
baseCoin	string	true	Base asset
quoteCoinID	uint64	true	Settlement coin ID
quoteCoin	string	true	Settlement coin name
quoteCoinPrecision	uint8	true	Settlement coin precision
pricePrecision	int32	true	Decimal precision of order price. Price filter parameters.
tickSize	DecimalString	true	Tick size of order price. Price filter parameters.
minPrice	DecimalString	true	Minimum order price. Price filter parameters.
maxPrice	DecimalString	true	Maximum order price. Price filter parameters.
quantityPrecision	int32	true	Decimal precision of order quantity. Lot size filter parameters.
openInterestCap	DecimalString	false	Open interest capacity in base coin
openInterestCapUSD	DecimalString	false	Open interest capacity in quote coin
stepSize	DecimalString	true	Step size of order quantity. Lot size filter parameters.
minQuantity	DecimalString	true	Minimum order quantity. Lot size filter parameters.
maxQuantity	DecimalString	true	Maximum order quantity. Lot size filter parameters.
marketMinQuantity	DecimalString	true	Minimum order quantity in market order. Market lot size filter parameters.
marketMaxQuantity	DecimalString	true	Maximum order quantity in market order. Market lot size filter parameters.
minNotional	DecimalString	true	Minimum order notional value. Notional filter parameters.
maxNotional	DecimalString	true	Maximum order notional value. Notional filter parameters.
buyLimitUpRatio	DecimalString	true	Limit order price limitation parameters
sellLimitDownRatio	DecimalString	true	Limit order price limitation parameters
marketDeviationRatio	DecimalString	true	Market order price limitation parameters
maxLeverage	uint32	true	Maximum leverage allowed
initLeverage	uint32	true	Initial leverage
marginTiers	Array<MarginTier>	true	Supported margin tiers
fundingInterval	uint32	true	Funding interval in seconds; must be a multiple of 3600.
interestRate	DecimalString	true	8h interest rate; always 0.0001
maxFundingRate	DecimalString	true	Maximum funding rate per funding interval
minFundingRate	DecimalString	true	Minimum funding rate per funding interval
makerFee	DecimalString	true	Default maker fee ratio
takerFee	DecimalString	true	Default taker fee ratio
status	string	true	Symbol status: TRADING, HALT

MarginTier

Name	Type	Required	Description
maxNotionalValue	DecimalString	true	Maximum notional value for this tier
maintenanceMarginRate	DecimalString	true	Maintenance margin rate for this tier
maxLeverage	uint32	true	Maximum leverage allowed in this tier
maintenanceDeduction	DecimalString	true	Maintenance deduction amount

Coin

SpotCoin

Name	Type	Required	Description
id	uint64	true	Unique coin ID
name	string	true	Unique coin name, e.g. vBTC, vUSDC
precision	uint8	true	Coin decimal precision

PerpsCoin

Name	Type	Required	Description
id	uint64	true	Unique coin ID
name	string	true	Unique coin name
precision	uint8	true	Coin decimal precision
marginRatio	DecimalString	true	Margin ratio of this coin
price	DecimalString	false	Current oracle price of this coin

Ticker

SpotTicker

Name	Type	Required	Description
symbol	string	true	Symbol name
lastPx	DecimalString	true	Last trade price
lastSz	DecimalString	false	Last trade quantity
openPx	DecimalString	true	Open price
highPx	DecimalString	true	High price
lowPx	DecimalString	true	Low price
vwap	DecimalString	false	Weighted average price
change	DecimalString	true	Price change
changePct	number	true	Price change percent
volume	DecimalString	true	Total traded base asset volume
quoteVolume	DecimalString	true	Total traded quote asset volume
bidPx	DecimalString	true	Best bid price
bidSz	DecimalString	true	Best bid quantity
askPx	DecimalString	true	Best ask price
askSz	DecimalString	true	Best ask quantity
openTime	uint64	true	Statistics open time in milliseconds
closeTime	uint64	true	Statistics close time in milliseconds

PerpsTicker

Name	Type	Required	Description
symbol	string	true	Symbol name
lastPx	DecimalString	true	Last trade price
lastSz	DecimalString	false	Last trade quantity
vwap	DecimalString	false	Weighted average price
change	DecimalString	false	Price change
changePct	number	false	Price change percent
openPx	DecimalString	true	Open price
highPx	DecimalString	true	High price
lowPx	DecimalString	true	Low price
volume	DecimalString	true	Total traded base asset volume
quoteVolume	DecimalString	true	Total traded quote asset volume
bidPx	DecimalString	true	Best bid price
bidSz	DecimalString	true	Best bid quantity
askPx	DecimalString	true	Best ask price
askSz	DecimalString	true	Best ask quantity
fundingRate	DecimalString	true	Current funding rate
nextFundingTime	uint64	true	Next funding time in milliseconds
indexPrice	DecimalString	true	Current index price
markPrice	DecimalString	true	Current mark price
openInterest	DecimalString	true	Current open interest
openTime	uint64	true	Statistics open time in milliseconds
closeTime	uint64	true	Statistics close time in milliseconds

Mini Ticker

MiniTicker

Name	Type	Required	Description
symbol	string	true	Symbol name
lastPx	DecimalString	true	Last trade price
openPx	DecimalString	true	Open price
highPx	DecimalString	true	High price
lowPx	DecimalString	true	Low price
volume	DecimalString	true	Total traded base asset volume
quoteVolume	DecimalString	true	Total traded quote asset volume
openTime	uint64	true	Statistics open time in milliseconds
closeTime	uint64	true	Statistics close time in milliseconds

Mark Price Ticker (perps only)

MarkPriceTicker

Name	Type	Required	Description
symbol	string	true	Symbol name
fundingRate	DecimalString	true	Current funding rate
nextFundingTime	uint64	true	Next funding time in milliseconds
indexPrice	DecimalString	true	Current index price
markPrice	DecimalString	true	Current mark price
openInterest	DecimalString	true	Current open interest

Book Ticker

BookTicker

Name	Type	Required	Description
symbol	string	true	Symbol name
bidPx	DecimalString	true	Best bid price
bidSz	DecimalString	true	Best bid quantity
askPx	DecimalString	true	Best ask price
askSz	DecimalString	true	Best ask quantity

Orderbook

OrderBook

Name	Type	Required	Description
blockTime	uint64	true	Block time in milliseconds
blockHeight	uint64	true	Block number
updateID	uint64	true	Last update ID for sync
bids	Array<[price, qty]>	true	Bid levels (price, quantity pairs)
asks	Array<[price, qty]>	true	Ask levels (price, quantity pairs)

Candle/KLines

RPCKline

Name	Type	Required	Description
t	uint64	true	Kline open time in milliseconds
o	DecimalString	true	Open price
h	DecimalString	true	High price
l	DecimalString	true	Low price
c	DecimalString	true	Close price
v	DecimalString	true	Base asset volume
q	DecimalString	true	Quote asset volume
n	uint64	false	Number of trades

Market Trades

Trade

Name	Type	Required	Description
t	uint64	true	Trade ID
T	uint64	true	Trade time in milliseconds
s	string	true	Symbol name
p	DecimalString	true	Price
q	DecimalString	true	Quantity
S	OrderSideEnum	true	Side: BUY or SELL
bi	uint64	false	Buyer account ID
si	uint64	false	Seller account ID

User Balance

SpotAccountBalances

Name	Type	Required	Description
blockTime	uint64	true	Block time in milliseconds
blockHeight	uint64	true	Block number
balances	Array<SpotBalance>	true	List of non zero balances

SpotBalance

Name	Type	Required	Description
id	uint64	true	Unique coin ID
coin	string	true	Coin name
total	DecimalString	true	Total balance (including locked)
locked	DecimalString	true	Locked balance in open orders

PerpsAccountBalance

Name	Type	Required	Description
blockTime	uint64	true	Block time in milliseconds
blockHeight	uint64	true	Block number
balances	Array<PerpsBalance>	true	List of non zero balances

PerpsBalance

Name	Type	Required	Description
id	uint64	true	Coin ID
coin	string	true	Coin name
total	DecimalString	true	The wallet balance
collateral	DecimalString	true	The collateral amount, only used by non-USDC assets
marginRatio	DecimalString	true	The margin ratio of this coin
price	DecimalString	false	The oracle price of this coin in USD

User Order

OrderBuilder

Name	Type	Required	Description
builderID	uint64	true	Builder account ID
feeRate	uint64	true	Builder fee rate in tenths of basis points. A value of 10 is 1 bp.

SpotAccountOpenOrder

Name	Type	Required	Description
blockTime	uint64	true	Block time in milliseconds
blockHeight	uint64	true	Block number
orders	Array<SpotOrder>	true	List of open orders

SpotOrder

Name	Type	Required	Description
orderID	uint64	true	Order ID
clOrdID	string	false	Client order ID
symbol	string	true	Symbol name
side	OrderSideEnum	true	Order side
type	OrderTypeEnum	true	Order type
timeInForce	TimeInForceEnum	false	Time in force
price	DecimalString	false	Order price
origQty	DecimalString	false	Original quantity
funds	DecimalString	false	Original quote funds
executedQty	DecimalString	true	Executed quantity
executedValue	DecimalString	true	Cumulative quote quantity
marginFrozen	DecimalString	true	Margin frozen by this order
builder	OrderBuilder	false	Builder attached to this order
status	OrderStatusEnum	true	Order status
createdAt	uint64	false	Order creation time in milliseconds
updatedAt	uint64	false	Order update time in milliseconds

PerpsAccountOpenOrder

Name	Type	Required	Description
blockTime	uint64	true	Block time in milliseconds
blockHeight	uint64	true	Block number
orders	Array<PerpsOrder>	true	List of open orders

PerpsOrder

Name	Type	Required	Description
orderID	uint64	true	Order ID
clOrdID	string	false	Client order ID
symbol	string	true	Symbol name
side	OrderSideEnum	true	Order side
type	OrderTypeEnum	true	Order type
timeInForce	TimeInForceEnum	false	Time in force
price	DecimalString	false	Order price
origQty	DecimalString	false	Original quantity
funds	DecimalString	false	Order Original funds
executedQty	DecimalString	true	Executed quantity
executedValue	DecimalString	true	Cumulative quote quantity
marginFrozen	DecimalString	true	Margin frozen by this order
builder	OrderBuilder	false	Builder attached to this order
status	OrderStatusEnum	true	Order status
createdAt	uint64	false	Order creation time in milliseconds
updatedAt	uint64	false	Order update time in milliseconds
positionSide	PositionSideEnum	true	Position side
reduceOnly	boolean	true	Reduce only flag
stopPrice	DecimalString	false	Stop price for TP/SL
stopType	StopTypeEnum	false	Stop type for TP/SL
triggerType	TriggerTypeEnum	false	Trigger type for TP/SL
positionID	uint64	false	Position ID this order is associated with (for position TP/SL)
primaryOrderID	uint64	false	Primary order ID this stop is attached to (for attached stops)
attachedOrderIDs	Array<uint64>	false	Order IDs of stops attached to this order (TP/SL)

User Position (perps only)

PerpsAccountOpenPosition

Name	Type	Required	Description
blockTime	uint64	true	Block time in milliseconds
blockHeight	uint64	true	Block number
positions	Array<Position>	true	List of open positions

Position

Name	Type	Required	Description
id	uint64	true	Position ID
symbol	string	true	Symbol name
marginMode	MarginModeEnum	true	Margin mode
positionSide	PositionSideEnum	true	Position side. Always BOTH for now.
size	DecimalString	true	Position size. Negative means short, positive means long.
initialMargin	DecimalString	true	Position initial margin. If isolated, this is also isolated margin.
avgEntryPrice	DecimalString	true	Average position entry price
cumOpenCost	DecimalString	true	Cumulative position open cost
cumTradingFee	DecimalString	true	Cumulative trading fee
cumFundingFee	DecimalString	true	Cumulative funding fee: positive received, negative paid. Default: "0".
cumClosedSize	DecimalString	true	Total closed size during the position lifetime
avgClosePrice	DecimalString	true	Average position close price
maxSize	DecimalString	true	Max position size during the position lifetime
realizedPnL	DecimalString	true	Realized profit and loss, includes trading fees and liquidation loss
leverage	uint32	true	Position leverage
active	bool	true	The position is active/working
isTakenOver	bool	true	Whether the position is taken over by liquidator
takeOverPrice	DecimalString	true	Mark price when taken over.
createdAt	uint64	true	Position creation timestamp, in milliseconds
updatedAt	uint64	true	Position updated timestamp, in milliseconds

• If position side is BOTH, then positive position size is LONG, negative position size is SHORT, zero position size means position is closed.

• If position side is LONG or SHORT. The position size is positive or zero, zero means position is closed.

• For now, position side is always BOTH.

User Funding (perps only)

PerpsUserFunding

Name	Type	Required	Description
symbol	string	true	Symbol name
positionID	uint64	true	Position ID
positionSide	PositionSideEnum	true	LONG or SHORT
fundingFee	DecimalString	true	Funding fee (negative = received)
feeCoin	string	true	The name of the fee coin
timestamp	uint64	true	Funding time in milliseconds

User API Key

APIKey

Name	Type	Required	Description
name	string	true	API key name
type	APIKeyTypeEnum	true	API key type. String value of the enum.
publicKey	HexString	true	Public key (hex string)
expiresAt	uint64	true	Expiration timestamp (milliseconds)
permissions	uint64	false	Permission mask. A set bit disables the corresponding APIKeyPermissionEnum.

AccountAPIKeys

Name	Type	Required	Description
spot	Array<APIKey>	true	Spot API keys for the account
perps	Array<APIKey>	true	Perps API keys for the account

User Subaccounts

Subaccount

Name	Type	Required	Description
id	uint64	true	Account ID
evmAddress	HexString	true	Account EVM address

UserSubaccounts

Name	Type	Required	Description
userID	uint64	true	Internal user ID
primaryAccountID	uint64	true	Primary trading account ID
subaccounts	Array<Subaccount>	true	Subaccounts owned by this user

User Builder

Builder

Name	Type	Required	Description
userID	uint64	true	Internal user ID
builderID	uint64	true	Builder account ID
feeRate	uint64	true	Builder fee rate in tenths of basis points. A value of 10 is 1 bp.

Builders

Name	Type	Required	Description
spot	Array<Builder>	true	Spot builder approvals for the user
perps	Array<Builder>	true	Perps builder approvals for the user

BuilderFeeStats

Returned by Builder Fee Summary for cumulative Spot and Perps statistics.

Name	Type	Required	Description
address	HexString	false	Builder account owner's address.
name	string	true	Builder display name.
builderCode	string	true	Builder trading account ID, encoded as an unsigned 64-bit decimal string.
userCount	string	true	User count associated with the builder, encoded as an unsigned 64-bit decimal string.
builderFee	DecimalString	true	Builder fees earned.
tradeCount	string	true	Number of fills attributed to the builder, encoded as an unsigned 64-bit decimal string.
tradeVolume	DecimalString	true	Traded notional attributed to the builder.

BuilderFeeDailyStats

Returned by Builder Fee Daily Chart for each UTC day's Spot and Perps activity.

Name	Type	Required	Description
date	string	true	UTC date in YYYY-MM-DD format.
userCount	string	true	User count associated with the builder, encoded as an unsigned 64-bit decimal string.
builderFee	DecimalString	true	Builder fees earned that day.
tradeCount	string	true	Number of fills attributed to the builder that day, encoded as an unsigned 64-bit decimal string.
tradeVolume	DecimalString	true	Traded notional attributed to the builder that day.

User TWAP

AccountTwapOrders

Name	Type	Required	Description
blockTime	uint64	true	Block time in milliseconds
blockHeight	uint64	true	Block number
twaps	Array<TwapOrder>	true	List of active TWAP orders

TwapOrder

Name	Type	Required	Description
symbol	string	true	Symbol name
orderID	uint64	true	TWAP order ID
quantity	DecimalString	true	TWAP total quantity
side	OrderSideEnum	true	Order side as BUY or SELL
minutes	uint64	true	TWAP duration in minutes
randomize	bool	true	Whether slices are randomized
reduceOnly	bool	true	Reduce-only flag
executedQty	DecimalString	true	Executed quantity
executedValue	DecimalString	true	Executed notional value
createdAt	uint64	true	Creation time in milliseconds
nextActiveAt	uint64	true	Next activation time in milliseconds
active	bool	true	Whether this TWAP is active

TwapOrderResponse

Name	Type	Required	Description
orderID	uint64	true	TWAP order ID

User DCA

AccountDcaOrders

Name	Type	Required	Description
blockTime	uint64	true	Unix timestamp in milliseconds of the block represented by this snapshot.
blockHeight	uint64	true	Block height represented by this snapshot.
dcas	Array<DcaOrder>	true	Plans with status ACTIVE for the selected account.

DcaOrder

Name	Type	Required	Description
symbol	string	true	Trading symbol name.
orderID	uint64	true	Parent plan ID, used to cancel the plan and link its child fills.
amount	DecimalString	true	Configured USDC notional for each BUY or SELL execution.
side	OrderSideEnum	true	Execution side, returned as BUY or SELL.
schedule	DcaSchedule	true	Recurring UTC schedule in the same format as creation.
minPrice	DecimalString	false	Configured inclusive lower reference-price bound; omitted when unset.
maxPrice	DecimalString	false	Configured inclusive upper reference-price bound; omitted when unset.
randomize	bool	true	Whether calendar executions are randomized within the selected hour.
immediate	bool	true	Whether an immediate first attempt was requested, independently of its outcome.
executedQty	DecimalString	true	Total base quantity actually filled across child execution orders.
executedValue	DecimalString	true	Sum of filled quantity multiplied by fill price across child orders, excluding fees.
failures	uint32	true	Current consecutive execution failure count.
createdAt	uint64	true	Plan creation time as a Unix timestamp in milliseconds.
nextActiveAt	uint64	true	Next scheduled trigger as a Unix timestamp in milliseconds. Processing can occur later.
status	DcaOrderStatusEnum	true	Plan lifecycle status; see DcaOrderStatusEnum.

DcaOrderResponse

The data object returned by a create/cancel request.

Name	Type	Required	Description
code	int32	true	0 for an accepted result
orderID	uint64	false	Parent plan ID returned when the request succeeds.
error	string	false	Error text when present

Fee Rate

FeeRate

Name	Type	Required	Description
makerFeeRate	DecimalString	true	Effective maker fee rate after discounts. Negative values indicate a maker rebate.
takerFeeRate	DecimalString	true	Effective taker fee rate after discounts.
feeTier	int	true	Fee tier (0-6) determined by the user's 14-day weighted trading volume.
stakingTier	int	true	Staking tier (0-6) determined by the user's SOSO token staking amount.
makerRebateTier	int	true	Maker rebate tier (0-3) determined by the user's share of global 14-day maker volume.

User Trade

UserTrade

Name	Type	Required	Description
symbol	string	true	Symbol name
tradeID	uint64	true	Trade ID
orderID	uint64	true	Order ID
clOrdID	string	true	Client Order ID
side	OrderSideEnum	true	Trade side: BUY or SELL
price	DecimalString	true	Trade price
quantity	DecimalString	true	Trade quantity
fee	DecimalString	false	Total fee charged on this fill, including the builder fee
builderFee	DecimalString	false	Actual builder fee component already included in fee
feeCoin	string	false	Commission asset
isMaker	bool	false	Whether trade was maker
time	uint64	true	Trade time in milliseconds

WebSocket Types

Misc types

WsPingRequest

interface WsPingRequest {
  op: "ping";
}

WsPingResponse

// send when server receive WsPingRequest from client
interface WsPingResponse {
  op: "pong";
}

WsErrorResponse

// for unexpected error, like Invalid JSON
interface WsErrorResponse {
  op: "error";
  error: string; // Error message
  connID: string; // WebSocket connection ID
}

WsSubscriptionRequest

interface WsSubscriptionRequest {
  op: "subscribe" | "unsubscribe";
  id: number | null; // Optional client originated request identifier sent as acknowledgment in the response.
  params: WsSubscriptionParams;
}

WsSubscriptionResponse

interface WsSubscriptionResponse {
  op: "subscribe" | "unsubscribe";
  id: number | null; // Optional client originated request identifier sent as acknowledgment in the response.
  result: WsSubscriptionResult | null;
  success: boolean; // Indicates if the request was successfully processed by the engine.
  error: string | null; // Condition: If success is false. Error message.
  connID: string; // WebSocket connection ID
  time_in: number; // The timestamp when the subscription was received on the wire, just prior to parsing data, in milliseconds.
  time_out: number; // The timestamp when the acknowledgement was sent on the wire, just prior to transmitting data, in milliseconds.
}

WsSubscriptionParams

type WsSubscriptionParams =
  | WsTickerSubscriptionParams
  | WsAllTickerSubscriptionParams
  | WsMiniTickerSubscriptionParams
  | WsAllMiniTickerSubscriptionParams
  | WsBookTickerSubscriptionParams
  | WsAllBookTickerSubscriptionParams
  | WsMarkPriceSubscriptionParams
  | WsAllMarkPriceSubscriptionParams
  | WsCoinPriceSubscriptionParams
  | WsAllCoinPriceSubscriptionParams
  | WsL2BookSubscriptionParams
  | WsL4BookSubscriptionParams
  | WsCandleSubscriptionParams
  | WsTradeSubscriptionParams
  | WsUserFrontendStateSubscriptionParams
  | WsAccountUpdateSubscriptionParams
  | WsOrderUpdateSubscriptionParams
  | WsUserTradeSubscriptionParams
  | WsUserEventSubscriptionParams;

WsSubscriptionResult

type WsSubscriptionResult =
  | WsTickerSubscriptionResult
  | WsAllTickerSubscriptionResult
  | WsMiniTickerSubscriptionResult
  | WsAllMiniTickerSubscriptionResult
  | WsBookTickerSubscriptionResult
  | WsAllBookTickerSubscriptionResult
  | WsMarkPriceSubscriptionResult
  | WsAllMarkPriceSubscriptionResult
  | WsCoinPriceSubscriptionResult
  | WsAllCoinPriceSubscriptionResult
  | WsL2BookSubscriptionResult
  | WsL4BookSubscriptionResult
  | WsCandleSubscriptionResult
  | WsTradeSubscriptionResult
  | WsUserFrontendStateSubscriptionResult
  | WsAccountUpdateSubscriptionResult
  | WsOrderUpdateSubscriptionResult
  | WsUserTradeSubscriptionResult
  | WsUserEventSubscriptionResult;

WsTickerSubscriptionParams

interface WsTickerSubscriptionParams {
  channel: "ticker";
  symbols: Array<string>; // A list of currency pairs
}

WsTickerSubscriptionResult

interface WsTickerSubscriptionResult {
  channel: "ticker";
  symbol: string;
}

WsAllTickerSubscriptionParams

interface WsAllTickerSubscriptionParams {
  channel: "allTicker";
}

WsAllTickerSubscriptionResult

type WsAllTickerSubscriptionResult = WsAllTickerSubscriptionParams;

WsMiniTickerSubscriptionParams

interface WsMiniTickerSubscriptionParams {
  channel: "miniTicker";
  symbols: Array<string>; // A list of currency pairs
}

WsMiniTickerSubscriptionResult

interface WsMiniTickerSubscriptionResult {
  channel: "miniTicker";
  symbol: string;
}

WsAllMiniTickerSubscriptionParams

interface WsAllMiniTickerSubscriptionParams {
  channel: "allMiniTicker";
}

WsAllMiniTickerSubscriptionResult

type WsAllMiniTickerSubscriptionResult = WsAllMiniTickerSubscriptionParams;

WsBookTickerSubscriptionParams

interface WsBookTickerSubscriptionParams {
  channel: "bookTicker";
  symbols: Array<string>; // A list of currency pairs
}

WsBookTickerSubscriptionResult

interface WsBookTickerSubscriptionResult {
  channel: "bookTicker";
  symbol: string;
}

WsAllBookTickerSubscriptionParams

interface WsAllBookTickerSubscriptionParams {
  channel: "allBookTicker";
}

WsAllBookTickerSubscriptionResult

type WsAllBookTickerSubscriptionResult = WsAllBookTickerSubscriptionParams;

WsMarkPriceSubscriptionParams

interface WsMarkPriceSubscriptionParams {
  channel: "markPrice";
  symbols: Array<string>; // A list of currency pairs
}

WsMarkPriceSubscriptionResult

interface WsMarkPriceSubscriptionResult {
  channel: "markPrice";
  symbol: string;
}

WsAllMarkPriceSubscriptionParams

interface WsAllMarkPriceSubscriptionParams {
  channel: "allMarkPrice";
}

WsAllMarkPriceSubscriptionResult

type WsAllMarkPriceSubscriptionResult = WsAllMarkPriceSubscriptionParams;

WsCoinPriceSubscriptionParams

interface WsCoinPriceSubscriptionParams {
  channel: "coinPrice";
  coins: Array<string>; // A list of coin names
}

WsCoinPriceSubscriptionResult

interface WsCoinPriceSubscriptionResult {
  channel: "coinPrice";
  coin: string;
}

WsAllCoinPriceSubscriptionParams

interface WsAllCoinPriceSubscriptionParams {
  channel: "allCoinPrice";
}

WsAllCoinPriceSubscriptionResult

type WsAllCoinPriceSubscriptionResult = WsAllCoinPriceSubscriptionParams;

WsL2BookSubscriptionParams

interface WsL2BookSubscriptionParams {
  channel: "l2Book";
  symbol: string;
  tickSize: string; // supported tickSizes are symbol.tickSize * (1, 2, 5, 10, 100, 1000)
}

WsL2BookSubscriptionResult

type WsL2BookSubscriptionResult = WsL2BookSubscriptionParams;

WsL4BookSubscriptionParams

interface WsL4BookSubscriptionParams {
  channel: "l4Book";
  symbol: string;
  level: number | null; // Possible values: [10, 25, 100, 500, 1000], Default 10
}

WsL4BookSubscriptionResult

interface WsL4BookSubscriptionResult {
  channel: "l4Book";
  symbol: string;
  level: number;
}

WsCandleSubscriptionParams

interface WsCandleSubscriptionParams {
  channel: "candle";
  symbol: string;
  // Case-sensitive. Day/week are lowercase; only month is uppercase ("1M").
  // spot:  "1m", "3m", "5m", "15m", "30m", "1h", "4h", "6h", "8h", "12h", "1d", "3d", "1w", "1M"
  // perps: "1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w", "1M"
  interval: string;
}

WsCandleSubscriptionResult

type WsCandleSubscriptionResult = WsCandleSubscriptionParams;

WsTradeSubscriptionParams

interface WsTradeSubscriptionParams {
  channel: "trade";
  symbols: Array<string>;
}

WsTradeSubscriptionResult

type WsTradeSubscriptionResult = WsTradeSubscriptionParams;

WsUserFrontendStateSubscriptionParams

interface WsUserFrontendStateSubscriptionParams {
  channel: "accountState";
  user: string;
  accountID: number | null; // default is primary account ID of the user
}

WsUserFrontendStateSubscriptionResult

interface WsUserFrontendStateSubscriptionResult {
  channel: "accountState";
  user: string;
  accountID: number;
}

WsAccountUpdateSubscriptionParams

interface WsAccountUpdateSubscriptionParams {
  channel: "accountUpdate";
  user: string;
  accountID: number | null; // default is primary account ID of the user
}

WsAccountUpdateSubscriptionResult

interface WsAccountUpdateSubscriptionResult {
  channel: "accountUpdate";
  user: string;
  accountID: number;
}

WsOrderUpdateSubscriptionParams

interface WsOrderUpdateSubscriptionParams {
  channel: "accountOrderUpdate";
  user: string;
  accountID: number | null; // default is primary account ID of the user
  symbols: Array<string> | null; // default push all updates
}

WsOrderUpdateSubscriptionResult

interface WsOrderUpdateSubscriptionResult {
  channel: "accountOrderUpdate";
  user: string;
  accountID: number;
  symbol: string | null; // null for all symbol subscription
}

WsUserTradeSubscriptionParams

interface WsUserTradeSubscriptionParams {
  channel: "accountTrade";
  user: string;
  accountID: number | null; // default is primary account ID of the user
  symbols: Array<string> | null; // default push all updates
}

WsUserTradeSubscriptionResult

interface WsUserTradeSubscriptionResult {
  channel: "accountTrade";
  user: string;
  accountID: number;
  symbol: string | null; // default push all updates
}

WsUserEventSubscriptionParams

interface WsUserEventSubscriptionParams {
  channel: "accountEvent";
  user: string;
  accountID: number | null; // default is primary account ID of the user
}

WsUserEventSubscriptionResult

interface WsUserEventSubscriptionResult {
  channel: "accountEvent";
  user: string;
  accountID: number;
}

Ticker

WsTickerData

interface WsTickerData {
  s: string; // The symbol of the currency pair
  c: string; // Close price / Last Price within the past 24 hours
  Q: string; // Last traded quantity within the past 24 hours
  w: string; // 24-hour volume weighted average price.
  a: string; // Best ask price.
  A: string; // Best ask quantity.
  b: string; // Best bid price.
  B: string; // Best bid quantity.
  p: string; // 24-hour price change (in quote currency).
  P: number; // 24-hour price change (in percentage points).
  o: string; // Open price
  h: string; // High price
  l: string; // Low price
  v: string; // Total traded base asset volume
  q: string; // Total traded quote asset volume
  O: number; // Statistics open time
  C: number; // Statistics close time
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
}

Mini Ticker

WsMiniTickerData

interface WsMiniTickerData {
  s: string; // The symbol of the currency pair
  c: string; // Close price / Last Price within the past 24 hours
  o: string; // Open price
  h: string; // High price
  l: string; // Low price
  v: string; // Total traded base asset volume
  q: string; // Total traded quote asset volume
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
}

Book Ticker

WsBookTickerData

interface WsBookTickerData {
  s: string; // The symbol of the currency pair
  u: number; // order book updateID
  a: string; // Best ask price.
  A: string; // Best ask quantity.
  b: string; // Best bid price.
  B: string; // Best bid quantity.
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
}

Mark Price (perps only)

WsMarkPriceData

interface WsMarkPriceData {
  s: string; // The symbol of the currency pair
  oi: string; // Current open interest in base asset.
  p: string; // Current mark price
  i: string; // Current index price
  r: string; // Current estimated funding rate
  T: string; // Next funding time
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
}

Coin Price (perps only)

WsCoinPriceData

interface WsCoinPriceData {
  i: number; // The coin ID
  a: string; // The coin name
  p: string; // Current coin price
  mr: string; // Current margin ratio
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
}

Book Depth Snapshot

WsDepthSnapshotData

interface WsDepthSnapshotData {
  s: string; // The symbol of the currency pair
  u: number; // order book updateID
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
  a: Array<[string, string]>; // The list of levels in ask side. Tuple of <price, qty>.
  b: Array<[string, string]>; // The list of levels in bid side. Tuple of <price, qty>.
}

Book Depth Update

WsDepthUpdateData

interface WsDepthUpdateData {
  s: string; // The symbol of the currency pair
  U: number; // The first order book updateID
  u: number; // The last order book updateID
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
  a: Array<[string, string]>; // The list of updated ask side levels. Tuple of <price, qty>.
  b: Array<[string, string]>; // The list of updated bid side levels. Tuple of <price, qty>.
}

Candle / Kline

Candle

interface Candle {
  t: number; // Kline start time
  T: number; // Kline close time
  s: string; // Symbol
  i: string; // Interval
  o: string; // Open price
  c: string; // Close price
  h: string; // High price
  l: string; // Low price
  v: string; // Base asset volume
  q: string; // Quote asset volume
  n: number; // Number of trades
  x: boolean; // Is this kline closed?
}

Account Update

• Spot Account Update

WsSpotBalance

interface WsSpotBalance {
  i: number; // asset/coin id
  a: string; // asset/coin name
  t: string; // wallet balance, including locked by open orders
  l: string; // locked balance by open orders
}

WsTwapOrder

interface WsTwapOrder {
  s: string; // symbol
  i: number; // TWAP order ID
  S: OrderSideEnum; // order side
  q: string; // TWAP total quantity
  m: number; // TWAP duration in minutes
  r: boolean; // whether slices are randomized
  R: boolean; // reduce-only flag
  z: string; // executed quantity
  v: string; // executed notional value
  ct: number; // creation time in milliseconds
  nt: number; // next activation time in milliseconds
  a: boolean; // whether this TWAP is active
}

WsDcaOrder

interface WsDcaOrder {
  s: string; // symbol
  i: number; // DCA parent plan ID (uint64)
  a: string; // USDC notional per execution
  S: OrderSideEnum; // BUY or SELL
  sc: DcaSchedule; // UTC schedule
  lp?: string; // minPrice
  hp?: string; // maxPrice
  r: boolean; // randomize
  im: boolean; // immediate
  z: string; // cumulative executedQty
  v: string; // cumulative executedValue
  f: number; // current consecutive execution failures
  ct: number; // createdAt, milliseconds
  nt: number; // nextActiveAt, milliseconds
  st: DcaOrderStatusEnum;
}

sc uses DcaSchedule. Other fields follow the meanings in DcaOrder.

WsSpotAccountUpdate

interface WsSpotAccountUpdate {
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
  T: number; // The update time in milliseconds, the timestamp of the block where this update happens
  h: number; // the block height of this update
  B: Array<WsSpotBalance>; // List of updated balances
  TO: Array<WsTwapOrder>; // List of updated TWAP orders
  DO: Array<WsDcaOrder>; // Updated DCA plans
}

• Perp Account Update

WsPerpsBalanceLite

interface WsPerpsBalanceLite {
  i: number; // asset/coin id
  a: string; // asset/coin name
  wb: string; // wallet balance
  co: string; // collateral amount, only used by non-USDC assets
}

WsPerpsPositionLite

interface WsPerpsPositionLite {
  i: number; // position id
  s: string; // symbol
  sz: string; // position size.
  ep: string; // position entry Price
  iw: string | null; // isolated wallet balance (if isolated position)
  ps: PositionSideEnum; // position side
}
// If position side is `BOTH`, then positive position size is LONG, negative position size is SHORT, zero position size means position is closed.
// If position side is `LONG` or `SHORT`. The position size is positive or zero, zero means position is closed.
// For now, position side is always `BOTH`.

WsPerpsAccountUpdate

interface WsPerpsAccountUpdate {
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
  T: number; // The update time in milliseconds, the timestamp of the block where this update happens
  h: number; // the block height of this update
  B: Array<WsPerpsBalanceLite>; // List of updated balances
  P: Array<WsPerpsPositionLite>; // List of updated positions
  TO: Array<WsTwapOrder>; // List of updated TWAP orders
  DO: Array<WsDcaOrder>; // Updated DCA plans
}

Order Update

• Spot Order Update

WsSpotOrder

interface WsOrderBuilder {
  i: number; // builder account ID
  f: number; // builder fee rate in tenths of basis points
}

interface WsSpotOrder {
  s: string; // Symbol
  c: string; // Client Order ID
  i: number; // System-generated unique Order ID
  S: OrderSideEnum; // Order Side, "BUY" is buy, "SELL" is sell
  o: OrderTypeEnum; // Order Type, LIMIT or MARKET
  f: TimeInForceEnum; // Time In Force, GTC, IOC or GTX
  p: string; // Price in quote currency
  q: string; // original order size
  F: string | null; // original funds of this order
  X: OrderStatusEnum; // Current order status
  z: string; // Cumulative filled quantity = sum executed trade.sz
  v: string; // Cumulative filled value = sum executed trade.sz * trade.px
  M: string; // margin locked by this order
  b?: WsOrderBuilder; // builder attached to this order
  ct?: number; // order creation time in milliseconds
  ut?: number; // order update time in milliseconds
}

WsSpotOrderUpdate

type WsSpotOrderUpdate = WsSpotOrder & {
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
  T: number; // The update time in milliseconds, the timestamp of the block where this trade happens
  t: number | null; // Trade ID
  l: string | null; // Last executed quantity
  L: string | null; // Last executed price
  n: string | null; // Commission amount
  m: boolean | null; // whether this trade the maker side?
  x: ExecutionTypeEnum; // Current execution type
  r: string | null; // execution reason
};

• Perp Order Update

WsPerpsOrder

type WsPerpsOrder = WsSpotOrder & {
  ps: PositionSideEnum; // position side
  R: boolean; // Is this reduce only
  sp: string | null; // stop price
  st: StopTypeEnum | null; // stop type
  tt: TriggerTypeEnum | null; // trigger type

  pid: number | null; // Position ID this order is associated with (for position TP/SL)
  poid: number | null; // Primary order ID this stop is attached to (for attached stops)
  aoids: Array<number> | null; // Order IDs of stops attached to this order (TP/SL)
};

WsPerpsOrderUpdate

type WsPerpsOrderUpdate = WsPerpsOrder & {
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
  T: number; // The update time in milliseconds, the timestamp of the block where this trade happens
  t: number | null; // Trade ID
  l: string | null; // Last executed quantity
  L: string | null; // Last executed price
  n: string | null; // Commission amount
  m: boolean | null; // whether this trade the maker side?
  x: ExecutionTypeEnum; // Current execution type
  r: string | null; // execution reason
};

Market Trades

WsTrade

interface WsTrade {
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
  T: number; // The trade time in milliseconds, the timestamp of the block where this trade happens
  t: number; // Trade ID
  s: string; // Symbol
  S: OrderSideEnum; // If side is "BUY", buyer is the taker, seller is the maker. If side is "SELL", buyer is the maker, seller is the taker.
  p: string; // trade price
  q: string; // trade quantity
  bi: number; // Buyer Account ID
  si: number; // Seller Account ID
}

User Trades

• Spot

WsSpotUserTrade

interface WsSpotUserTrade {
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
  T: number; // The trade time in milliseconds, the timestamp of the block where this trade happens
  t: number; // Trade ID
  s: string; // Symbol
  i: number; // Order ID
  c: string; // Client Order ID
  S: OrderSideEnum; // order side
  p: string; // trade price
  q: string; // trade quantity
  f: string; // total fee charged on this fill, including the builder fee
  bf?: string; // actual builder fee component already included in f
  m: boolean; // whether this trade the maker side?
}

• Perps

WsPerpsUserTrade

type WsPerpsUserTrade = WsSpotUserTrade & {
  d: string; // used for frontend display, Long, Short, Close Long, Close Short, Long -> Short, Short -> Long
};

User Frontend State

• Spot

WsSpotState

interface WsSpotState {
  user: string; // User evm address
  aid: number; // Account ID
  uid: number; // User ID
  B: Array<WsSpotBalance>; // List of balances
  O: Array<WsSpotOrder>; // List of latest 100 open orders
  TO: Array<WsTwapOrder>; // List of TWAP orders
  DO: Array<WsDcaOrder>; // Active DCA plans
}

• Perps

WsPerpsBalance

interface WsPerpsBalance {
  i: number; // Coin ID
  a: string; // Coin Name
  wb: string; // The wallet balance
  co: string; // The collateral amount, only used by non-USDC assets
  mr: string; // The margin ratio of this coin in percentage
  px: string; // The oracle price of this coin in USD
}

WsPerpsPosition

interface WsPerpsPosition {
  i: number; // Position ID
  s: string; // Symbol
  m: MarginModeEnum; // Margin Mode, ISOLATED or CROSS
  ps: PositionSideEnum; // Position Side
  sz: string; // position size, positive is long, negative is short, zero means position closed
  iw: string | null; // Isolated margin for isolated positions
  ep: string; // Average position entry price
  co: string; // Cumulative position open cost
  cf: string; // Cumulative trading fee
  cc: string; // Total closed size during the position lifetime
  cp: string; // Average position close price
  ms: string; // Max position size during the position lifetime
  cr: string; // Realized profit and loss, also includes trading fee and liquidation loss
  ur: string; // Unrealized  profit and loss
  l: number; // Position Leverage
  lp: string; // Position liquidation price
}
// If position side is `BOTH`, then positive position size is LONG, negative position size is SHORT, zero position size means position is closed.
// If position side is `LONG` or `SHORT`. The position size is positive or zero, zero means position is closed.
// For now, position side is always `BOTH`.

WsPerpsSymbolConfig

interface WsPerpsSymbolConfig {
  s: string; // Symbol
  l: number; // leverage
  m: MarginModeEnum; // Margin Mode, ISOLATED or CROSS
}

WsPerpsBalanceDetailed

type WsPerpsBalanceDetailed = WsPerpsBalance & {
  iw: string | null; // isolated frozen margin for position or open orders, only for vUSDC
  aw: string; // available wallet balance for margin
  at: string; // available wallet balance for transfer / withdrawal
  wm: string; // wallet balance corresponding margin
  am: string; // available wallet balance corresponding margin
};

WsPerpsState

interface WsPerpsState {
  user: string; // user evm address
  aid: number; // Account ID
  uid: number; // User ID
  av: string; // Cross account value
  am: string; // available margin for cross position
  ami: string; // available margin for isolated position
  amw: string; // available margin for transfer
  im: string; // isolated frozen margin for position
  cm: string; // cross frozen margin for position
  oim: string; // isolated frozen margin for open position
  ocm: string; // cross frozen margin for open position
  B: Array<WsPerpsBalanceDetailed>; // List of balances
  O: Array<WsPerpsOrder>; // List of latest 100 open orders
  P: Array<WsPerpsPosition>; // List of open perps position
  TO: Array<WsTwapOrder>; // List of TWAP orders
  DO: Array<WsDcaOrder>; // Active DCA plans
  S: Array<WsPerpsSymbolConfig>; // List of touched symbol config
}

User Event

PerpsLiquidatedPosition

interface PerpsLiquidatedPosition {
  s: string; // symbol
  ps: PositionSideEnum; // position side
  sz: string; // position size, positive is long, negative is short
  mp: string; // mark price at liquidation
  lp: string | null; // actual liquidation price for this position.
}
// If position side is `BOTH`, then positive position size is LONG, negative position size is SHORT, zero position size means position is closed.
// If position side is `LONG` or `SHORT`. The position size is positive or zero, zero means position is closed.
// For now, position side is always `BOTH`.

WsUserLiquidation

// Perp only
// both liquidator and liquidated user will receive the same event.
interface WsUserLiquidation {
  E: number; // The timestamp when this event was sent on the wire, just prior to transmitting data, in milliseconds.
  type: "liquidation";
  lid: number; // liquidator account ID
  aid: number; // Account ID
  av: string; // Account value. for isolated positions this is the isolated margin
  mm: MarginModeEnum; // margin mode
  B: Array<WsPerpsBalanceLite>; // list of liquidated balances
  P: Array<PerpsLiquidatedPosition>; // list of liquidated positions
}

WsUserEvent

type WsUserEvent = WsUserLiquidation;