Api bulk orders request

ApiBulkOrdersRequest

Bulk create, cancel, or cancel-replace orders for a single subaccount.

A cancel-replace is a cancel of the old order plus a create of a new one. The new order is assigned a new order_id; the cancelled order_id is terminated. Clients must track the new order_id from the response.

Rules
- Up to 100 entries in each of orders, order_ids, and client_order_ids
- All create orders must target the same instrument
- client_order_ids within orders must be unique
- order_ids and client_order_ids are mutually exclusive; supplying both is rejected
- Rate limits: N creates consume N create_order tokens; any cancels consume 1 cancel_order token

BulkCreate

Populate orders only; leave order_ids and client_order_ids empty. A batch may not mix multiple normal orders with trigger orders.

To mark an order as TP or SL, populate its metadata.trigger field; see TriggerOrderMetadata for details.

A 'parent' order is a normal order whose linked TP/SL trigger orders become active once the parent is fully filled.

Supported combinations:
- Normal orders (non-TPSL): one or many orders
- Standalone TP: 1 TP order
- Standalone SL: 1 SL order
- OCO (2 orders: 1 TP + 1 SL): same asset, same size, same side
- OTO (2 orders: parent + 1 trigger): 1 parent + 1 TP or SL order. Same asset and size. Parent side is opposite of the trigger side.
- OTOCO (3 orders: parent + TP + SL): 1 parent + 1 TP order + 1 SL order. Same asset and size across all three. Parent side is opposite of TP and SL sides.

BulkCancel

Leave orders empty; populate either order_ids or client_order_ids (not both). Targets can be normal orders, standalone TP/SL, or members of an OCO/OTO/OTOCO group. Passing any member id of a grouped TPSL order cancels the whole group.

BulkCancelReplace

Populate orders together with order_ids or client_order_ids. Ids below refer to entries in whichever id list you chose.

Normal orders (non-TPSL): the batch is processed as all cancels first, then all creates.

TPSL: #creates must equal #cancels, and one request may modify only one group. For OTO and OTOCO, only the trigger part is replaceable — the parent order is not included in orders or in the cancel id list, and stays on the book unchanged.
- Standalone TP / Standalone SL: cancel 1 id (the existing trigger order) + create 1 new trigger order with matching triggerType.
- OCO: cancel both ids of the existing OCO group (the TP and SL) + create 2 new orders (1 TP + 1 SL); shape conditions same as BulkCreate OCO.
- OTO: cancel the id of the existing trigger order in the OTO group + create 1 new trigger order. The new trigger is linked to the same parent.
- OTOCO: cancel both ids of the existing OTOCO group (the TP and SL) + create 2 new orders (1 TP + 1 SL); shape conditions same as BulkCreate OCO. The new TP and SL are linked to the same parent.

Name Lite	Type	Required Default	Description
sub_account_id sa	string	True	The subaccount ID of the user creating the request
orders o	[Order]	True	Orders to create or replace, supply up to 100 orders
order_i_ds oi	[string]	True	The order IDs of the orders to cancel or replace, supply up to 100 orderIDs (if both orderIDs and clientOrderIDs are provided, we will reject the payload)
client_order_i_ds co	[string]	True	The client order IDs of the orders to cancel or replace, supply up to 100 clientOrderIDs (if both orderIDs and clientOrderIDs are provided, we will reject the payload)
time_to_live_ms tt	string	False 100	Specifies the time-to-live (in milliseconds) for this cancellation. During this period, any order creation with a matching client_order_id will be cancelled and not be added to the GRVT matching engine. This mechanism helps mitigate time-of-flight issues where cancellations might arrive before the corresponding orders. Hence, cancellation by order_id ignores this field as the exchange can only assign order_ids to already-processed order creations. The duration cannot be negative, is rounded down to the nearest 100ms (e.g., '670' -> '600', '30' -> '0') and capped at 5 seconds (i.e., '5000'). Value of '0' or omission results in the default time-to-live value being applied. If the caller requests multiple successive cancellations for a given order, such that the time-to-live windows overlap, only the first request will be considered.

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
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 (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
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

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