Place Isolated Order

Create an isolated position with isolated margin for a provided market / product.

An isolated position has its own dedicated margin for a given product. Opening an isolated position, creates a corresponding isolated subaccount that holds that margin. You can later view your isolated positions (and isolated subaccounts) via Isolated Positions. The cross-subaccount that creates the isolated position is known as the parent subaccount.

You can perform the following actions to manage your isolated positions:

• Place Order: Use PlaceOrder to reduce/close your isolated position. The specified sender needs to be the isolated subaccount for the provided productId.

• Transfer Quote: Use TransferQuote to increase/reduce your quote margin to/from the isolated subaccount. The specified sender needs to be isolated subaccount for the provided productId.

Notes:

• Isolated subaccounts can only transfer quote to/from the parent cross-subaccount.

• Isolated subaccounts can sign PlaceOrder/ TransferQuote requests using the parent's wallet or the parent's linked signer.

• See Isolated Margin to learn more.

Rate limits

• 120 orders/minute or 2 orders/sec per wallet. (weight=5)

• A max of 10 open isolated positions per address.

See more details in API Rate limits.

Request

Websocket

Connect

WEBSOCKET [GATEWAY_WEBSOCKET_ENDPOINT]

Message

{
  "place_isolated_order": {
    "product_id": 1,
    "isolated_order": {
      "sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
      "priceX18": "1000000000000000000",
      "amount": "1000000000000000000",
      "expiration": "4294967295",
      "nonce": "1757062078359666688",
      "margin": "100000000000000000000"
    },
    "signature": "0x",
    "borrow_margin": false,
    "id": 100
  }
}

REST

POST [GATEWAY_REST_ENDPOINT]/execute

Body

{
  "place_order": {
    "product_id": 1,
    "order": {
      "sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
      "priceX18": "1000000000000000000",
      "amount": "1000000000000000000",
      "expiration": "4294967295",
      "nonce": "1757062078359666688"
    },
    "signature": "0x",
    "id": 100
  }
}

Request Parameters

Parameter	Type	Required	Description
product_id	number	Yes	Id of perp product for which to open an isolated position. Use All products query to retrieve all valid product ids.
isolated_order	object	Yes	Isolated order object, see Signing section for details on each isolated order field.
isolated_order.sender	string	Yes	Hex string representing the cross subaccount's 32 bytes (address + subaccount name) of the tx sender.
isolated_order.priceX18	string	Yes	Price of the order multiplied by 1e18.
isolated_order.amount	string	Yes	Quantity of the order multiplied by 1e18.
isolated_order.expiration	string	Yes	A time after which the order should automatically be cancelled, as a timestamp in seconds after the unix epoch. See Signing section for more details
isolated_order.margin	bool	Yes	Amount of quote margin to transfer to the isolated position from the cross-subaccount.
isolated_order.nonce	string	Yes	Used to differentiate between the same order multiple times. See Signing section for more details.
signature	string	Yes	Hex string representing hash of the signed isolated order. See Signing section for more details.
digest	string	No	Hex string representing a hash of the order.
borrow_margin	boolean	No	Whether the cross subaccount can borrow quote for the margin transfer into the isolated subaccount. If not provided, it defaults to true.
id	number	No	An optional id that when provided is returned as part of Fill and OrderUpdate stream events. See subscriptions for more details. NOTE: The client id should not be used to differentiate orders, as it is not included in the order hash (i.e., the order digest). Instead, use the last 20 bits of the order nonce to distinguish between similar orders. For more details, refer to the Order Nonce documentation.

Signing

See more details and examples in our signing page.

The solidity typed data struct that needs to be signed is:

struct IsolatedOrder {
    bytes32 sender;
    int128 priceX18;
    int128 amount;
    uint64 expiration;
    uint64 nonce;
    int128 margin;
    
}

sender: a bytes32 sent as a hex string; includes the address and the subaccount identifier

priceX18: an int128 representing the price of the order multiplied by 1e18, sent as a string. For example, a price of 1 USDC would be sent as "1000000000000000000"

amount: an int128 representing the quantity of the order multiplied by 1e18, sent as a string. A positive amount means that this is a buy order, and a negative amount means this is a sell order.

margin: an int128representing the quote margin to transfer from the parent subaccount into the isolated subaccount multiplied by 1e18, sent as a string. Margin cannot be negative.

Order Expiration

expiration: a time after which the order should automatically be cancelled, as a timestamp in seconds after the unix epoch, sent as a string. The most significant two bits of expiration also encode the order type:

0 ⇒ Default order, where it will attempt to take from the book and then become a resting limit order if there is quantity remaining

1 ⇒ Immediate-or-cancel order, which is the same as a default order except it doesn’t become a resting limit order

2 ⇒ Fill-or-kill order, which is the same as an IOC order except either the entire order has to be filled or none of it.

3 ⇒ Post-only order, where the order is not allowed to take from the book. An error is returned if the order would cross the bid ask spread.

For example, to submit an IOC order with an expiration of 1000 seconds, we would set expiration as follows:

import time
unix_epoch = int(time.time())
post_only_expiration = str((unix_epoch + 1000) | (1 << 62))

Reserved Bits

The 4th to 6th most significant bits in the expiration field are reserved and must be unset. Orders using reserved bits will be rejected.

Order Nonce

nonce: used to differentiate between the same order multiple times, and a user trying to place an order with the same parameters twice. Sent as a string. Encodes two bit of information:

• Most significant 44 bits encoding the time in milliseconds (a recv_time) after which the order should be ignored by the matching engine

• Least significant 20 bits are a random integer used to avoid hash collisions

  For example, to place an order with a random integer of 1000, and a discard time 50 ms from now, we would send a nonce of ((timestamp_ms() + 50) << 20) + 1000)

import time
unix_epoch_ms = int(time.time()) * 1000
nonce = ((unix_epoch_ms + 50) << 20) + 1000

Note: for signing you should always use the data type specified in the solidity struct which might be different from the type sent in the request e.g: nonce should be an uint64 for Signing but should be sent as a string in the final payload.

Response

Success

{
  "status": "success",
  "signature": {signature},
  "data": { 
    "digest": {order digest} 
  },
  "request_type": "execute_place_isolated_order"
  "id": 100
}

Failure

{
  "status": "failure",
  "signature": {signature},
  "error": "{error_msg}",
  "error_code": {error_code},
  "request_type": "execute_place_isolated_order"
}