Documentation

New Order

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
  [
    1575287438.515, // MTS (omitted for 'on' event)
    "on-req", // TYPE (omitted for 'on' event)
    null, // MESSAGE_ID (omitted for 'on' event)
    null, // null (omitted for 'on' event)
    [
      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 (omitted for 'on' event)
    "SUCCESS", // STATUS (omitted for 'on' event)
    "Submitting limit sell order for -2.5 ETH." // TEXT (omitted for 'on' event)
  ]
]

[
  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

NameTypeDescription
gidint32(optional) Group id for the order
cidint45Should be unique in the day (UTC) (not enforced)
typestringThe 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.
symbolstringsymbol (tBTCUSD, tETHUSD, ...)
amountdecimal stringPositive for buy, Negative for sell
pricedecimal stringPrice (Not required for market orders)
levintSet 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_trailingdecimal stringThe trailing price
price_aux_limitdecimal stringAuxiliary Limit price (for STOP LIMIT)
price_oco_stopdecimal stringOCO stop price
flagsint16See https://docs.bitfinex.com/v2/docs/flag-values.
tifdatetime stringTime-In-Force: datetime for automatic order cancellation (e.g. 2020-01-15 10:45:23).
metaobjectObject 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.

Response Fields

TermTypeDescription
CHANNEL_IDintID of the channel. (0 for account info messages)
EVENTstringType of event ('n' for notification)
MTSintMillisecond Time Stamp of the update
TYPEstringPurpose of notification ('on-req', 'oc-req', 'uca', 'fon-req', 'foc-req')
MESSAGE_IDintunique ID of the message
IDintOrder ID
GIDintGroup ID
CIDintClient Order ID
SYMBOLstringPair (tBTCUSD, …)
MTS_CREATEintMillisecond timestamp of creation
MTS_UPDATEintMillisecond timestamp of update
AMOUNTfloatPositive means buy, negative means sell.
AMOUNT_ORIGfloatOriginal amount
TYPEstringThe 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_PREVstringPrevious order type
MTS_TIFintMillisecond timestamp of Time-In-Force: automatic order cancellation
ORDER_STATUSstringOrder Status: ACTIVE
PRICEfloatPrice
PRICE_AVGfloatAverage price
PRICE_TRAILINGfloatThe trailing price
PRICE_AUX_LIMITfloatAuxiliary Limit price (for STOP LIMIT)
HIDDENint0 if false, 1 if true
PLACED_IDintIf another order caused this order to be placed (OCO) this will be that other order's ID
ROUTINGstringindicates origin of action: BFX, ETHFX, API>BFX, API>ETHFX
FLAGSintSee https://docs.bitfinex.com/v2/docs/flag-values.
METAjson stringAdditional meta information about the order ( $F7 = IS_POST_ONLY (0 if false, 1 if true), $F33 = Leverage (int))
CODEnull or integerWork in progress
STATUSstringStatus of the notification; it may vary over time (SUCCESS, ERROR, FAILURE, ...)
TEXTstringText of the notification