Ws order feed data v1

WSOrderFeedDataV1

Name Lite	Type	Required Default	Description
stream s	string	True	Stream name
selector s1	string	True	Primary selector
sequence_number sn	string	True	A sequence number used to determine message order within a stream. - If useGlobalSequenceNumber is false, this returns the gateway sequence number, which increments by one locally within each stream and resets on gateway restarts. - If useGlobalSequenceNumber is true, this returns the global sequence number, which uniquely identifies messages across the cluster. - A single cluster payload can be multiplexed into multiple stream payloads. - To distinguish each stream payload, a dedupCounter is included. - The returned sequence number is computed as: cluster_sequence_number * 10^5 + dedupCounter.
feed f	Order	True	The order object being created or updated
prev_sequence_number ps	string	True	The previous sequence number that determines the message order

Order

Order is a typed payload used throughout the GRVT platform to express all orderbook, RFQ, and liquidation orders.
GRVT orders are capable of expressing both single-legged, and multi-legged orders by default.
This increases the learning curve slightly but reduces overall integration load, since the order payload is used across all GRVT trading venues.
Given GRVT's trustless settlement model, the Order payload also carries the signature, required to trade the order on our ZKSync Hyperchain.

All fields in the Order payload (except id, metadata, and state) are trustlessly enforced on our Hyperchain.
This minimizes the amount of trust users have to offer to GRVT

Name Lite	Type	Required Default	Description
order_id oi	string	False 0	[Filled by GRVT Backend] A unique 128-bit identifier for the order, deterministically generated within the GRVT backend
sub_account_id sa	string	True	The subaccount initiating the order
is_market im	boolean	False false	If the order is a market order Market Orders do not have a limit price, and are always executed according to the maker order price. Market Orders must always be taker orders On STABLE_PERP a slippage bound is mandatory: limit_price must carry the signed bound (reference price ± the chosen slippage), otherwise the order is rejected with stablePerpRequiresPriceBound. is_market = false with a limit price behaves identically on STABLE_PERP; the flag is intent metadata only.
time_in_force ti	TimeInForce	True	Four supported types of orders: GTT, IOC, AON, FOK: PARTIAL EXECUTION = GTT / IOC - allows partial size execution on each leg FULL EXECUTION = AON / FOK - only allows full size execution on all legs TAKER ONLY = IOC / FOK - only allows taker orders MAKER OR TAKER = GTT / AON - allows maker or taker orders Exchange only supports (GTT, IOC, FOK) RFQ Maker only supports (GTT, AON), RFQ Taker only supports (IOC, FOK)
post_only po	boolean	False false	If True, Order must be a maker order. It has to fill the orderbook instead of match it. If False, Order can be either a maker or taker order. In this case, order creation is currently subject to a speedbump of 25ms to ensure orders are matched against updated orderbook quotes.
reduce_only ro	boolean	False false	If True, Order must reduce the position size, or be cancelled
legs l	[OrderLeg]	True	The legs present in this order The legs must be sorted by Asset.Instrument/Underlying/Quote/Expiration/StrikePrice
signature s	Signature	True	The signature approving this order
metadata m	OrderMetadata	True	Order Metadata, ignored by the smart contract, and unsigned by the client
state s1	OrderState	False ''	[Filled by GRVT Backend] The current state of the order, ignored by the smart contract, and unsigned by the client
builder b	string	True	The main account ID of the builder
builder_fee bf	string	True	Builder fee charged for this order, expressed as a percentage (e.g., 0.001 means 0.001%).

TimeInForce

	Must Fill All	Can Fill Partial
Must Fill Immediately	FOK	IOC
Can Fill Till Time	AON	GTC

Value	Description
GOOD_TILL_TIME = 1	GTT - Remains open until it is cancelled, or expired
ALL_OR_NONE = 2	AON - Either fill the whole order or none of it (Block Trades Only)
IMMEDIATE_OR_CANCEL = 3	IOC - Fill the order as much as possible, when hitting the orderbook. Then cancel it
FILL_OR_KILL = 4	FOK - Both AoN and IoC. Either fill the full order when hitting the orderbook, or cancel it
RETAIL_PRICE_IMPROVEMENT = 5	RPI - A GTT + PostOnly maker order, that can only be taken by non-algorithmic UI users.

OrderLeg

Name Lite	Type	Required Default	Description
instrument i	string	True	The instrument to trade in this leg
size s	string	True	The total number of assets to trade in this leg, expressed in base asset decimal units.
limit_price lp	string	False 0	The limit price of the order leg, expressed in 9 decimals. This is the number of quote currency units to pay/receive for this leg. This should be null/0 if the order is a market order Exception: on STABLE_PERP market orders this carries the mandatory signed slippage bound (reference price ± the chosen slippage) rather than being left empty.
is_buying_asset ib	boolean	True	Specifies if the order leg is a buy or sell

Signature

Name Lite	Type	Required Default	Description
signer s	string	True	The address (public key) of the wallet signing the payload
r r	string	True	Signature R
s s1	string	True	Signature S
v v	integer	True	Signature V
expiration e	string	True	Timestamp after which this signature expires, expressed in unix nanoseconds. Must be capped at 30 days
nonce n	integer	True	Users can randomly generate this value, used as a signature deconflicting key. ie. You can send the same exact instruction twice with different nonces. When the same nonce is used, the same payload will generate the same signature. Our system will consider the payload a duplicate, and ignore it. Range: 0 to 4,294,967,295 (uint32)
chain_id ci	string	True	Chain ID used in EIP-712 domain. Zero value fallbacks to GRVT Chain ID.

OrderMetadata

Metadata fields are used to support Backend only operations. These operations are not trustless by nature.
Hence, fields in here are never signed, and is never transmitted to the smart contract.

Name Lite	Type	Required Default	Description
client_order_id co	string	True	A unique identifier for the active order within a subaccount, specified by the client This is used to identify the order in the client's system This field can be used for order amendment/cancellation, but has no bearing on the smart contract layer This field will not be propagated to the smart contract, and should not be signed by the client This value must be unique for all active orders in a subaccount, or amendment/cancellation will not work as expected Gravity UI will generate a random clientOrderID for each order in the range [0, 2^63 - 1] To prevent any conflicts, client machines should generate a random clientOrderID in the range [2^63, 2^64 - 1] When GRVT Backend receives an order with an overlapping clientOrderID, we will reject the order with rejectReason set to overlappingClientOrderId
create_time ct	string	False 0	[Filled by GRVT Backend] Time at which the order was received by GRVT in unix nanoseconds
trigger t	TriggerOrderMetadata	False ``	Trigger fields are used to support any type of trigger order such as TP/SL
broker b	BrokerTag	False ``	Specifies the broker who brokered the order
is_ecn ie	boolean	False false	Specifies this order is an ECN order eligible for Market Maker Last Look. Only applicable to STABLE_PERP (SFP) instruments with qualified market makers.
slippage_bps sb	integer	False 0	Maximum allowed slippage from mark price for an IOC limit order, expressed in basis points (800 = 8%). Only valid on IOC limit orders. 0 means no slippage protection (regular limit IOC order).
rfq_id ri	string	False None	Binds this order to an RFQ (see ApiCreateRfqRequest and the v1.rfq / v1.quote streams). Optional. As a taker acceptance: unlocks that RFQ's private quote pool, so the order matches across the private pool merged with the public book (firm resting liquidity + public quotes). The acceptance must be a single-leg order with time_in_force = IOC or FOK. Setting rfq_id on a non-ECN GTT order is rejected. If the referenced RFQ has expired, been cancelled, or is unknown, the order is rejected. As a maker quote (is_ecn = true): identifies which RFQ the quote is responding to. Omit rfq_id to match the public book only — private RFQ liquidity requires an RFQ.
is_private ip1	boolean	False false	Maker quotes only. true = a private quote delivered to a single RFQ's taker (appears only on that taker's v1.quote book); false = a public quote resting on the order book, visible to all. When true, rfq_id is required.

TriggerOrderMetadata

Contains metadata related to trigger orders, such as Take Profit (TP) or Stop Loss (SL).

Trigger orders are used to automatically execute an order when a predefined price condition is met, allowing traders to implement risk management strategies.

Name Lite	Type	Required Default	Description
trigger_type tt	TriggerType	True	Type of the trigger order. eg: Take Profit, Stop Loss, etc
tpsl t	TPSLOrderMetadata	True	Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.

TriggerType

Defines the type of trigger order used in trading, such as Take Profit or Stop Loss.

Trigger orders allow execution based on pre-defined price conditions rather than immediate market conditions.

Value	Description
UNSPECIFIED = 0	Not a trigger order. The order executes normally without any trigger conditions.
TAKE_PROFIT = 1	Take Profit Order - Executes when the price reaches a specified level to secure profits.
STOP_LOSS = 2	Stop Loss Order - Executes when the price reaches a specified level to limit losses.

TPSLOrderMetadata

Contains metadata for Take Profit (TP) and Stop Loss (SL) trigger orders.

Name Lite	Type	Required Default	Description
trigger_by tb	TriggerBy	True	Defines the price type (e.g., index price) that activates a Take Profit (TP) or Stop Loss (SL) order
trigger_price tp	string	True	The Trigger Price of the order, expressed in 9 decimals.
close_position cp	boolean	True	If True, the order will close the position when the trigger price is reached
is_split_position is	boolean	True	If True, the order will be treated as part of a position's split-TP/SL set, subject to aggregate size/count limits.

TriggerBy

Defines the price type that activates a Take Profit (TP) or Stop Loss (SL) order.

Trigger orders are executed when the selected price type reaches the specified trigger price.Different price types ensure flexibility in executing strategies based on market conditions.

Value	Description
UNSPECIFIED = 0	no trigger condition
INDEX = 1	INDEX - Order is activated when the index price reaches the trigger price
LAST = 2	LAST - Order is activated when the last trade price reaches the trigger price
MID = 3	MID - Order is activated when the mid price reaches the trigger price
MARK = 4	MARK - Order is activated when the mark price reaches the trigger price

BrokerTag

BrokerTag is a tag for the broker that the order is sent from.

Value	Description
UNSPECIFIED = 0
COIN_ROUTES = 1	CoinRoutes
ALERTATRON = 2	Alertatron
ORIGAMI = 3	Origami

OrderState

Name Lite	Type	Required Default	Description
status s	OrderStatus	True	The status of the order
reject_reason rr	OrderRejectReason	True	The reason for rejection or cancellation
book_size bs	[string]	True	The number of assets available for orderbook/RFQ matching. Sorted in same order as Order.Legs
traded_size ts	[string]	True	The total number of assets traded. Sorted in same order as Order.Legs
update_time ut	string	True	Time at which the order was updated by GRVT, expressed in unix nanoseconds
avg_fill_price af	[string]	True	The average fill price of the order. Sorted in same order as Order.Legs

OrderStatus

Value	Description
PENDING = 1	Order has been sent to the matching engine and is pending a transition to open/filled/rejected.
OPEN = 2	Order is actively matching on the matching engine, could be unfilled or partially filled.
FILLED = 3	Order is fully filled and hence closed. Taker Orders can transition directly from pending to filled, without going through open.
REJECTED = 4	Order is rejected by matching engine since if fails a particular check (See OrderRejectReason). Once an order is open, it cannot be rejected.
CANCELLED = 5	Order is cancelled by the user using one of the supported APIs (See OrderRejectReason). Before an order is open, it cannot be cancelled.

OrderRejectReason

Value	Description
UNSPECIFIED = 0	order is not cancelled or rejected
CLIENT_CANCEL = 1	client called a Cancel API
CLIENT_BULK_CANCEL = 2	client called a Bulk Cancel API
CLIENT_SESSION_END = 3	client called a Session Cancel API, or set the WebSocket connection to 'cancelOrdersOnTerminate'
MARKET_CANCEL = 4	the market order was cancelled after no/partial fill. Lower precedence than other TimeInForce cancel reasons
IOC_CANCEL = 5	the IOC order was cancelled after no/partial fill
AON_CANCEL = 6	the AON order was cancelled as it could not be fully matched
FOK_CANCEL = 7	the FOK order was cancelled as it could not be fully matched
EXPIRED = 8	the order was cancelled as it has expired
FAIL_POST_ONLY = 9	the post-only order could not be posted into the orderbook
FAIL_REDUCE_ONLY = 10	the reduce-only order would have caused position size to increase
MM_PROTECTION = 11	the order was cancelled due to market maker protection trigger
SELF_TRADE_PROTECTION = 12	the order was cancelled due to self-trade protection trigger
SELF_MATCHED_SUBACCOUNT = 13	the order matched with another order from the same sub account
OVERLAPPING_CLIENT_ORDER_ID = 14	an active order on your sub account shares the same clientOrderId
BELOW_MARGIN = 15	the order will bring the sub account below initial margin requirement
LIQUIDATION = 16	the sub account is liquidated (and all open orders are cancelled by Gravity)
INSTRUMENT_INVALID = 17	instrument is invalid or not found on Gravity
INSTRUMENT_DEACTIVATED = 18	instrument is no longer tradable on Gravity. (typically due to a market halt, or instrument expiry)
SYSTEM_FAILOVER = 19	system failover resulting in loss of order state
UNAUTHORISED = 20	the credentials used (userSession/apiKeySession/walletSignature) is not authorised to perform the action
SESSION_KEY_EXPIRED = 21	the session key used to sign the order expired
SUB_ACCOUNT_NOT_FOUND = 22	the subaccount does not exist
NO_TRADE_PERMISSION = 23	the signature used to sign the order has no trade permission
UNSUPPORTED_TIME_IN_FORCE = 24	the order payload does not contain a supported TimeInForce value
MULTI_LEGGED_ORDER = 25	the order has multiple legs, but multiple legs are not supported by this venue
EXCEED_MAX_POSITION_SIZE = 26	the order would have caused the subaccount to exceed the max position size
EXCEED_MAX_SIGNATURE_EXPIRATION = 27	the signature supplied is more than 30 days in the future
MARKET_ORDER_WITH_LIMIT_PRICE = 28	the market order has a limit price set
CLIENT_CANCEL_ON_DISCONNECT_TRIGGERED = 29	client cancel on disconnect triggered
OCO_COUNTER_PART_TRIGGERED = 30	the OCO counter part order was triggered
REDUCE_ONLY_LIMIT = 31	the remaining order size was cancelled because it exceeded current position size
CLIENT_REPLACE = 32	the order was replaced by a client replace request
DERISK_MUST_BE_IOC = 33	the derisk order must be an IOC order
DERISK_MUST_BE_REDUCE_ONLY = 34	the derisk order must be a reduce-only order
DERISK_NOT_SUPPORTED = 35	derisk is not supported
INVALID_ORDER_TYPE = 36	the order type is invalid
CURRENCY_NOT_DEFINED = 37	the currency is not defined
INVALID_CHAIN_ID = 38	the chain ID is invalid
BUILDER_ORDER_FEE_EXCEED = 39	Builder fee exceed the limit
BUILDER_ORDER_FEE_NEGATIVE = 40	Builder fee is below 0
BUILDER_ORDER_BUILDER_NOT_AUTHORIZED = 41	Builder is not an authorized builder for client
BUILDER_ORDER_BUILDER_NOT_EXIST = 42	Builder does not exist
TRADE_PRICE_WORSE_THAN_BANKRUPTCY_PRICE = 44	the trade price is worse than the bankruptcy price
TOO_MANY_MAKER_ORDERS = 45	the order was cancelled due to matching with too many maker orders
REDUCE_ONLY_NOT_SUPPORTED_FOR_SPOT_ORDER = 46	reduce-only order is not supported for spot order
TPSL_NOT_SUPPORTED_FOR_SPOT_ORDER = 47	tpsl is not supported for spot order
SPOT_ORDER_NOT_SUPPORTED = 48	spot order is not supported
INSUFFICIENT_BALANCE = 49	the subaccount has insufficient balance
SPOT_TRADING_BLOCKED_DURING_SOCIALIZED_LOSS = 50	spot trading is blocked during socialized loss (SLOW)
BELOW_MARGIN_WITH_PENALTY_DEVIATION = 51	the order will bring the sub account below initial margin requirement considering wide price deviation
CORPORATE_ACTION = 56	Cancelled by the system due to Corporate Action
NOT_QUALIFIED_MAKER = 57	the order was rejected because the sub account is not a qualified maker
PRIVATE_QUOTE_REQUIRES_RFQ = 58	rfq_id is required when is_private = true
STABLE_PERP_REQUIRES_PRICE_BOUND = 59	a signed slippage bound filled in limit_price is required
UNSUPPORTED_TRIGGER_BY = 60	SFP order only supports trigger_by = index
RFQ_NOT_FOUND = 61	the order was rejected because the referenced RFQ could not be found
RESTING_ORDER_WOULD_CROSS = 62	post-only resting placement crosses opposite best resting or index mid
SESSION_CLOSED = 63	the order was submitted when the trading session was either closed or under maintenance