Creates a new order, can be used to create margin, exchange, and derivative orders.
To submit an order, construct a payload using the "on" (order new) abbreviation and include the desired order details. Please look to the sidebar for a model and an example.
Upon submitting the order, you will receive a message of the appropriated type on the "account info" channel. Example responses are included in the sidebar. Please look to the Orders and Notifications pages for further information, such as the response fields.
Order inputs require you to run the authentication code along with additional code for the input. The authentication code can be found on our Authenticated Channels and the additional code for inputs can be found on the Websocket Inputs page.
// Model
[
0,
"on",
null,
{
"gid": GID,
"cid": CID,
"type": TYPE,
"symbol": SYMBOL,
"amount": AMOUNT,
"price": PRICE,
"meta": {aff_code: "AFF_CODE_HERE"} // optional param to pass an affiliate code
...
}
]
// Example
[
0,
"on",
null,
{
"gid": 1,
"cid": 12345,
"type": "LIMIT",
"symbol": "tBTCUSD",
"amount": "1.0",
"price": "500"
}
]
// When the order is submitted you will receive an 'n' (notification) event as confirmation. If the order request is successful, you will also receive an 'on' (order new) event. Both events are sent through CHANNEL_ID = 0.
[
0, // CHANNEL_ID
"n", // EVENT
[
1575287438515, // MTS
"on-req", // TYPE
null, // MESSAGE_ID
null, // _PLACEHOLDER
[
1185815098, // ID
null, // GID
1575287436979, // CID
"tETHUSD", // SYMBOL
1575287438515, // MTS_CREATE
1575287438515, // MTS_UPDATE
-2.5, // AMOUNT
-2.5, // AMOUNT_ORIG
"LIMIT", // ORDER_TYPE
null, // TYPE_PREV
null, // MTS_TIF
null, // _PLACEHOLDER
0, // FLAGS
"ACTIVE", // STATUS
null, // _PLACEHOLDER
null, // _PLACEHOLDER
230, // PRICE
0, // PRICE_AVG
0, // PRICE_TRAILING
0, // PRICE_AUX_LIMIT
null, // _PLACEHOLDER
null, // _PLACEHOLDER
null, // _PLACEHOLDER
0, // NOTIFY
null, // HIDDEN
null, // PLACED_ID
null, // _PLACEHOLDER
null, // _PLACEHOLDER
"API>BFX", // ROUTING
null, // _PLACEHOLDER
null, // _PLACEHOLDER
null // META
],
null, // CODE
"SUCCESS", // STATUS
"Submitting limit sell order for -2.5 ETH." // TEXT
]
]
[
0, // CHANNEL_ID
"on", // EVENT
[
1185815098, // ID
null, // GID
1575287436979, // CID
"tETHUSD", // SYMBOL
1575287438515, // MTS_CREATE
1575287438519, // MTS_UPDATE
-2.5, // AMOUNT
-2.5, // AMOUNT_ORIG
"LIMIT", // ORDER_TYPE
null, // TYPE_PREV
null, // MTS_TIF
null, // _PLACEHOLDER
0, // FLAGS
"ACTIVE", // STATUS
null, // _PLACEHOLDER
null, // _PLACEHOLDER
230, // PRICE
0, // PRICE_AVG
0, // PRICE_TRAILING
0, // PRICE_AUX_LIMIT
null, // _PLACEHOLDER
null, // _PLACEHOLDER
null, // _PLACEHOLDER
0, // NOTIFY
0, // HIDDEN
null, // PLACED_ID
null, // _PLACEHOLDER
null, // _PLACEHOLDER
"API>BFX", // ROUTING
null, // _PLACEHOLDER
null, // _PLACEHOLDER
null // META
]
]
Request fields
| Name | Type | Description |
|---|---|---|
| gid | int32 | (optional) Group id for the order |
| cid | int45 | Should be unique in the day (UTC) (not enforced) |
| type | string | The type of the order: LIMIT, EXCHANGE LIMIT, MARKET, EXCHANGE MARKET, STOP, EXCHANGE STOP, STOP LIMIT, EXCHANGE STOP LIMIT, TRAILING STOP, EXCHANGE TRAILING STOP, FOK, EXCHANGE FOK, IOC, EXCHANGE IOC. |
| symbol | string | symbol (tBTCUSD, tETHUSD, ...) |
| amount | decimal string | Positive for buy, Negative for sell |
| price | decimal string | Price (Not required for market orders) |
| lev | int | Set the leverage for a derivative order, supported by derivative symbol orders only. The value should be between 1 and 100 inclusive. The field is optional, if omitted the default leverage value of 10 will be used. |
| price_trailing | decimal string | The trailing price |
| price_aux_limit | decimal string | Auxiliary Limit price (for STOP LIMIT) |
| price_oco_stop | decimal string | OCO stop price |
| flags | int16 | See https://docs.bitfinex.com/v2/docs/flag-values. |
| tif | datetime string | Time-In-Force: datetime for automatic order cancellation (e.g. 2020-01-15 10:45:23). |
| meta | object | Object to pass order meta data. Options: 'aff_code' (to pass affiliate codes), 'make_visible' (to toggle visible on hit for hidden orders), 'protect_selfmatch' (to cancel submitted order if it would match with one of your own orders). Example: meta: {aff_code: "AFF_CODE_HERE", make_visible: 1} |
meta: {aff_code: ...}
API orders can now pass an affiliate code through which you can earn rebates. To learn more about these rebates and our affiliate program, please look at the relevant announcement and knowledge base article.
meta: {protect_selfmatch: 1}
The 'protect_selfmatch' flag can be used to avoid matching orders with standing orders on the same account. This flag is passed in the meta object in the order body when submitting or updating your orders.
Note that this flag is only intended to assist users in avoiding unintentional wash trading. As per our trading rulebook, wash trading is forbidden on the platform.
Order types
Additional information about the types of orders can be found here:
https://support.bitfinex.com/hc/en-us/articles/115003506105-Limit-Order
Multiple Flags
You may sum flag values to pass multiple flags. For example, passing 4160 (64 + 4096) means hidden and post only.
The default value is 0 and indicates that no flags will be used.
New order notification data
| Index | Field | Type | Description |
|---|---|---|---|
| [0] | CHANNEL_ID | Int | ID of the channel. (0 for account info messages) |
| [1] | EVENT | String | Type of event ('n' for notification) |
| [2] | PLACEHOLDER | ||
| [3] | NOTIFICATION_ARRAY | Array |
Notification array data
| Index | Field | Type | Description |
|---|---|---|---|
| [0] | MTS | Int | Millisecond Time Stamp of the update |
| [1] | TYPE | String | Purpose of notification ('on-req', 'oc-req', 'uca', 'fon-req', 'foc-req') |
| [2] | MESSAGE_ID | Int | nique ID of the message |
| [3] | ORDER_ARRAY | Array | |
| [4] | CODE | Null or Integer | Work in progress |
| [5] | STATUS | String | Status of the notification; it may vary over time (SUCCESS, ERROR, FAILURE, ...) |
| [6] | TEXT | String | Text of the notification |
"on" event data
| Index | Field | Type | Description |
|---|---|---|---|
| [0] | CHANNEL_ID | Int | ID of the channel. (0 for account info messages) |
| [1] | TYPE | String | Purpose of notification ('on-req', 'oc-req', 'uca', 'fon-req', 'foc-req') |
| [2] | ORDER_ARRAY | Array |
Order Array data (
| Term | Type | Description |
|---|---|---|
| CHANNEL_ID | int | ID of the channel. (0 for account info messages) |
| EVENT | string | Type of event ('n' for notification) |
| MTS | int | Millisecond Time Stamp of the update |
| TYPE | string | Purpose of notification ('on-req', 'oc-req', 'uca', 'fon-req', 'foc-req') |
| MESSAGE_ID | int | unique ID of the message |
| ID | int | Order ID |
| GID | int | Group ID |
| CID | int | Client Order ID |
| SYMBOL | string | Pair (tBTCUSD, …) |
| MTS_CREATE | int | Millisecond timestamp of creation |
| MTS_UPDATE | int | Millisecond timestamp of update |
| AMOUNT | float | Positive means buy, negative means sell. |
| AMOUNT_ORIG | float | Original amount |
| TYPE | string | The type of the order: LIMIT, EXCHANGE LIMIT, MARKET, EXCHANGE MARKET, STOP, EXCHANGE STOP, STOP LIMIT, EXCHANGE STOP LIMIT, TRAILING STOP, EXCHANGE TRAILING STOP, FOK, EXCHANGE FOK, IOC, EXCHANGE IOC. |
| TYPE_PREV | string | Previous order type |
| MTS_TIF | int | Millisecond timestamp of Time-In-Force: automatic order cancellation |
| ORDER_STATUS | string | Order Status: ACTIVE |
| PRICE | float | Price |
| PRICE_AVG | float | Average price |
| PRICE_TRAILING | float | The trailing price |
| PRICE_AUX_LIMIT | float | Auxiliary Limit price (for STOP LIMIT) |
| HIDDEN | int | 0 if false, 1 if true |
| PLACED_ID | int | If another order caused this order to be placed (OCO) this will be that other order's ID |
| ROUTING | string | indicates origin of action: BFX, ETHFX, API>BFX, API>ETHFX |
| FLAGS | int | See https://docs.bitfinex.com/v2/docs/flag-values. |
| META | json string | Additional meta information about the order ( $F7 = IS_POST_ONLY (0 if false, 1 if true), $F33 = Leverage (int)) |
| CODE | null or integer | Work in progress |
| STATUS | string | Status of the notification; it may vary over time (SUCCESS, ERROR, FAILURE, ...) |
| TEXT | string | Text of the notification |