Place Order

Places an order on Vertex's orderbook.

Rate limits

• With spot leverage: 600 orders/minute or 10 orders/sec per wallet. (weight=1)

• Without spot leverage: 30 orders/min or 5 orders every 10 seconds per wallet. (weight = 20)

See more details in API Rate limits.

Request

Websocket

Connect

WEBSOCKET [GATEWAY_WEBSOCKET_ENDPOINT]

Message

{
  "place_order": {
    "product_id": 1,
    "order": {
      "sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
      "priceX18": "1000000000000000000",
      "amount": "1000000000000000000",
      "expiration": "4294967295",
      "nonce": "1757062078359666688"
    },
    "signature": "0x",
    "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 spot / perp product for which to place order. Use All products query to retrieve all valid product ids.
order	object	Yes	Order object, see Signing section for details on each order field.
order.sender	string	Yes	Hex string representing the subaccount's 32 bytes (address + subaccount name) of the tx sender.
order.priceX18	string	Yes	Price of the order multiplied by 1e18.
order.amount	string	Yes	Quantity of the order multiplied by 1e18.
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
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 order. See Signing section for more details.
digest	string	No	Hex string representing a hash of the order.
spot_leverage	boolean	No	Indicates whether leverage should be used; when set to false , placing the order fails if the transaction causes a borrow on the subaccount. 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 Order {
    bytes32 sender;
    int128 priceX18;
    int128 amount;
    uint64 expiration;
    uint64 nonce;
}

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.

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 a post-only 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) | (3 << 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.

Reduce-only

A reduce-only is an order that will either close or reduce your position. The reduce-only flag can only be set on IOC or FOK order types. Send a reduce-only order by setting the 3rd most significant bit on the expiration field. See the following example:

import time
unix_epoch = int(time.time())
ioc_reduce_only_expiration = str((unix_epoch + 1000) | (1 << 62) | (1 << 61))
fok_reduce_only_expiration = str((unix_epoch + 1000) | (2 << 62) | (1 << 61))

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

  • First bit must be set for placing trigger orders.
• 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_order"
  "id": 100
}

Failure

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