Place an Order

The method POST /orders enables you to place a buy or sell order. Both Limit and Market orders are available.

HTTP Request

POST https://stage.bitso.com/api/v3/orders

Header Parameters

You must specify the following authorization parameters in your request:

Parameter	Description	Required
`key`	See the section, Authentication	Yes
`signature`	See the section, Authentication	Yes
`nonce`	See the section, Authentication	Yes

Body Parameters

Body parameters must be JSON encoded and precisely the same as the JSON payload used to construct the signature:

Parameter	Description	Required
`book`	The book to use.	Yes
`major`	The amount in the major currency for the order. Limit Orders: Required. You must always specify the amount using `major`. Market Orders:Optional. You may specify the amount using either `major` or `minor`, but not both. If both are provided, the request will be rejected.	No
`minor`	The amount in the minor currency for the order. Limit Orders: Not supported. Do not use `minor` when placing Limit Orders. Market Orders: Optional. You may specify the amount using either `major` or `minor`, but not both.	No
`origin_id`	The order's client-supplied, unique ID (if any). Valid character set: `a` to `z` (lower and uppercase), `0` to `9`, underscore, `_`, and dash, `-`. Maximum length = 40 characters.	No
`price`	The price per unit of major. Use this parameter only with Limit Orders. The rounding algorithm considers only eight decimal places, rounding up to the nearest price when selling and down when buying.	No
`side`	The order's side. Valid values: `buy` and `sell`.	Yes
`stop`	The price per unit of major at which to stop and place the order. Use this parameter only with Stop Orders.	No
`time_in_force`	The period a Limit Order remains active before it is executed or expires. Valid values: `goodtillcancelled`, `fillorkill`, `immediateorcancel`, and `postonly`.	No
`type`	The order's type. Valid values: `market` and `limit`.	Yes
`slippage_tolerance`	The maximum acceptable slippage for Market or Stop-Loss Orders, expressed as a percentage in decimal form (e.g., `0.5` = `0.5%`, `0` = no slippage allowed). Must be `>= 0` and `<= 100` (100%). Only applicable to Market and Stop-Loss Orders; ignored for other order types. If omitted or negative slippage protection is disabled. If not a number, request fails with`incorrect_slippage` (code `0418`)	No
`margin_order_type`	The margin order type. Margin trading is enabled only upon request. Contact [email protected] for more information. Only valid for users with a margin account. Omit this parameter or send it as null for regular spot orders. Valid values: `CROSS_MARGIN`.	No
`settle_major`	The major currency to use for settlement, instead of the book's major currency. When used with a sell order, this currency will be locked instead of the book's major currency; when used with a buy order, your balance will be increased in this currency instead of the book's major currency, and your fee will be charged in this currency as well.	No
`settle_minor`	The minor currency to use for settlement, instead of the book's minor currency. When used with a buy order, this currency will be locked instead of the book's minor currency; when used with a sell order, your balance will be increased in this currency instead of the book's minor currency, and your fee will be charged in this currency as well.	No

📘
Order Rejected if origin_id Is Not Unique
The origin_id parameter must uniquely identify each active order. If a new order placement request uses an origin_id already associated with an active order, the system rejects the request.

JSON Response Payload

The endpoint returns a JSON object representing the order. This object includes the following field:

Field Name	Description	Type
`oid`	The order's unique ID.	String

The following response object exemplifies the JSON object returned:

{
    "success": true,
    "payload": {
        "oid": "qlbga6b600n3xta7"
    }
}

A note about settlement currencies

Certain books allow the use of settlement currencies. A settlement currency is one which can be used instead of the book's major or minor currency.
An example of this is MXNB, which can be used instead of MXN. If MXN is the book's minor currency, then you can specify mxnb in the settle_minor field. On a buy order, your MXNB balance will be locked instead of MXN; on a sell order, your MXNB balance will be increased when the order trades, and the fee will be charged in MXNB.

HTTP Request

Header Parameters

Body Parameters

Order Rejected if origin_id Is Not Unique

JSON Response Payload

A note about settlement currencies

Order Rejected if `origin_id` Is Not Unique