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

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

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"
}
PreviousPlace OrderNextCancel Orders

Last updated