Trading API

Trade API covers all order placement and trade management.

Order Status

Below is the list of possible order status values:

New
Placed
Failed
Error
Cancelled
Partially Cancelled
Fully Matched
Partially Matched

Number Conversion

All numbers, specifically for price and volume, must be converted to an integer for use in Trading API requests. The conversion is 100000000, or 1E8. For strongly typed programming languages, use of integer or long integer variable types is strongly recommended, as decimals will not be accepted by the API.

Create an order

places a new order if the parameters are correct and the account has sufficient funds.

sample request:

{
  "currency": "AUD",
  "instrument": "BTC",
  "price": 13000000000,
  "volume": 10000000,
  "orderSide": "Bid",
  "ordertype": "Limit"
}

sample success response:

{
  "success": true,
  "errorCode": null,
  "errorMessage": null,
  "id": 100,
  "clientRequestId": null
}

sample error response

{
  "success": false,
  "errorCode": 3,
  "errorMessage": "Invalid argument.",
  "errorDetail": "Invalid order type",
  "id": 0,
  "clientRequestId": "null",
}

General notes

The clientRequestId is not currently used but must be specified. Any string is valid.
Price of $130 = 13000000000 (i.e x 100000000)
Volume of 1 BTC = 100000000 (i.e x 100000000)
When passing AUD as currency, maximum 2 decimal points are allowed. In above example, $130 and $130.12 are allowed but $130.123 will return "invalid amount".
In case of placing Market orders, price price is ultimately set by matching engine depending on existing orders in the orderbook at the time of trade execution.

Order types

The following types of orders are supported:

Limit
Market
Stop Limit
Take Profit
Stop

Stop orders

In the case of placing a Stop Limit order, the ordertype will be "Stop Limit", and an additional field triggerPrice must be supplied with the same number conversion as price.
In the case of placing a Stop order, the ordertype will be "Stop", and an additional field triggerPrice must be supplied with the same number conversion as price. When triggerPrice is reached, a market order will be executed.
In the case of placing a Take Profit order, the ordertype will be "Take Profit", and an additional field triggerPrice must be supplied with the same number conversion as price. When triggerPrice is reached, a market order will be executed.
For both Stop orders and Take Profit orders price is ultimately set by matching engine depending on existing orders in the orderbook at the time of trade execution (same as for market orders).

Post-Only orders (08/30)

postOnly is an optional boolean flag with true/false value. The default is false for all new orders. When this option is set to true then it means the order should only be posted to the orderbook if it does not result in any trades at the time of placement. If any part of the order results in trade execution, the order will be cancelled. Please note: once the order is accepted as part of the initial placement then it may execute at any later time depending on the market price movements. The option is only applied for the time of placement.

postOnly option is only applicable to Limit orders.

This option is mainly useful for market makers and liquidity providers.

Time In Force (08/30)

timeInForce option allows traders to control order life time with the following possible values.

GTC: good to cancel (the default value if not specified)
IOC: immediate or cancel. The order should be cancelled immediately after being placed in the orderbook. The order may be matched against existing orders as part of the initial placement in the orderbook but any volume that is is left from trade matching will be cancelled immediately after placement. Therefore possible results of an order with IOC option will be either Fully Matched, Partially Matched, Cancelled or Partially Cancelled.
FOK: fill or kill. The order is cancelled if it's not executed fully at the time of placement. Possible results of an order with FOK option will be either Fully Matched or Cancelled immediately.

Note: When postOnly option is set to true then the only possible value for timeInForce is IOC or leave it as empty.

Target Amount (08/30)

This is an optional parameter allowing traders to instruct the system to sell (or buy) as many number of instrument as possible so that the targetAmount is reached. For example, as a trader, I'd like to receive $100 (the target amount) by selling as many of my XRPs (the actual volume is determined by the system at the time of placing the order). The system then makes best effort to determine the total volume of XRP that is needed to sell in order to generate $100 considering all trading fees, partial order match, etc.

This feature eliminates the need for traders to calculate how many XRP's are needed before placing an order and particularly when marker is moving quickly, this might be a difficult task.

This option also works for Bid orders with the use case being: I'd like to spend maximum $100 on buying LTC and the system determines the total volume that I can purchase considering all fees.

targetAmount option is only applicable to Market orders.

below is a sample request when specifying target amount:

{
  "currency": "AUD",
  "instrument": "XRP",
  "targetAmount": 10000000000,
  "orderSide": "Ask",
  "ordertype": "Market"
}

Please note that price and volume are not required when using targetAmount.

Self Trade Prevention (08/30)

selfTrade option allows traders to control possibility of their own orders execute against each other. For instance if you already have an order already in the orderbook to buy 100 XRP for price of 0.50 and then place a new order to sell 100 XRP with the same price of 0.50 then the new sell order will be cancelled immediately and won't be submitted to the orderbook. The existing order (the the buy order for 100 XRP) will continue to stay in the orderbook and will work as normal.

The same is true also when the new order has the potential to partially match existing orders. So in above sample (your existing buy order of 100 XRP) and if you place a new sell order with selfTrade option to sell 200 XRP (given that 100 of those XRP will potentially match with an existing order that does not belong to you) then again the entire new sell order will be cancelled immediately due to self trade option.

Please also note that this option is only checked at the time of order arrival and only once. If the order stays in the orderbook then this option is not applicable anymore.

Possible values for selfTrade option are A (self trade is allowed that is the default behavior) and P to prevent self trade.

sample request with all of the options:

{
  "currency": "AUD",
  "instrument": "BTC",
  "price": 13000000000,
  "volume": 10000000,
  "orderSide": "Bid",
  "ordertype": "Limit",
  "postOnly": false,
  "timeInForce": "FOK",
  "selfTrade": "A"
}

Cancel an order

path: /order/cancel

http post

sample request:

{"orderIds":[6840125478]}

The array of order ids can contain maximum 30 items.

sample response:

{"success":true,"errorCode":null,"errorMessage":null,"responses":[{"success":false,"errorCode":3,"errorMessage":"order does not exist.","id":6840125478}]}

Order history

path: /order/history

http post

since parameter for this api method is the order id.

sample request:

{"currency":"AUD","instrument":"BTC","limit":10,"since":33434568724}

sample response:

{"success":true,"errorCode":null,"errorMessage":null,"orders":[{"id":1003245675,"currency":"AUD","instrument":"BTC","orderSide":"Bid","ordertype":"Limit","creationTime":1378862733366,"status":"Placed","errorMessage":null,"price":13000000000,"volume":10000000,"openVolume":10000000,"clientRequestId":null,"trades":[]},{"id":4345675,"currency":"AUD","instrument":"BTC","orderSide":"Ask","ordertype":"Limit","creationTime":1378636912705,"status":"Fully Matched","errorMessage":null,"price":13000000000,"volume":10000000,"openVolume":0,"clientRequestId":null,"trades":[{"id":5345677,"creationTime":1378636913151,"description":null,"price":13000000000,"volume":10000000,"fee":100000}]}]}

Open Orders

path: /order/open

http post

This is similar to the order history request and response. The only difference is that this method only returns open orders.

Trade History

path: /order/trade/history

http post

since parameter for this api method is the trade id.

sample request:

{"currency":"AUD","instrument":"BTC","limit":10,"since":33434568724}

sample response:

{"success":true,"errorCode":null,"errorMessage":null,"trades":[{"id":374367855,"creationTime":1492232900701,"price":159672000000,"volume":100000,"side":"Ask","fee":1357210,"orderId":374367838},{"id":229485482,"creationTime":1478837751322,"price":94299000000,"volume":100000,"side":"Bid","fee":801540,"orderId":229485469}]}

Order detail

path: /order/detail

http post

sample request:

{"orderIds":[698068, 698771, 698825]}

The value(s) for orderIds must always be in the format of an array, even if only one ID is included.

sample response:

{
  "success": true,
  "errorCode": null,
  "errorMessage": null,
  "orders": [
    {
      "id": 698068,
      "currency": "AUD",
      "instrument": "ETH",
      "orderSide": "Ask",
      "ordertype": "Market",
      "creationTime": 1516140997056,
      "status": "Fully Matched",
      "errorMessage": null,
      "price": 1200000000,
      "volume": 5000000,
      "openVolume": 0,
      "clientRequestId": null,
      "trades": [
        {
          "id": 698080,
          "creationTime": 1516140997301,
          "description": null,
          "price": 1200000000,
          "volume": 5000000,
          "side": "Ask",
          "fee": 509999,
          "orderId": 698068
        }
      ]
    },
    {
      "id": 698771,
      "currency": "AUD",
      "instrument": "BTC",
      "orderSide": "Bid",
      "ordertype": "Limit",
      "creationTime": 1516919450949,
      "status": "Partially Matched",
      "errorMessage": null,
      "price": 2700000000,
      "volume": 100000000,
      "openVolume": 4400000,
      "clientRequestId": null,
      "trades": [
        {
          "id": 698935,
          "creationTime": 1517808598156,
          "description": null,
          "price": 2700000000,
          "volume": 95600000,
          "side": "Bid",
          "fee": 21940174,
          "orderId": 698771
        }
      ]
    },
    {
      "id": 698825,
      "currency": "AUD",
      "instrument": "BTC",
      "orderSide": "Bid",
      "ordertype": "Limit",
      "creationTime": 1516923611252,
      "status": "Placed",
      "errorMessage": null,
      "price": 2700000000,
      "volume": 100000000,
      "openVolume": 100000000,
      "clientRequestId": null,
      "trades": []
    }
  ]
}

v2

Open Orders

http GET

path: /v2/order/open[/{instrument}/{currency}]

optional: To get all open orders, regardless of instrument and currency, simply leave them out of the path. See second example.

pagination: no

sample request: /v2/order/open/BTC/AUD

sample response:

{
    "success": true,
    "errorCode": null,
    "errorMessage": null,
    "orders": [
        {
            "id": 702587,
            "currency": "AUD",
            "instrument": "BTC",
            "orderSide": "Ask",
            "ordertype": "Limit",
            "creationTime": 1531518888090,
            "status": "Placed",
            "errorMessage": null,
            "price": 998700000000,
            "volume": 3000000,
            "openVolume": 3000000,
            "clientRequestId": null,
            "trades": []
        },
        {
            "id": 702590,
            "currency": "AUD",
            "instrument": "BTC",
            "orderSide": "Ask",
            "ordertype": "Limit",
            "creationTime": 1531518897518,
            "status": "Placed",
            "errorMessage": null,
            "price": 889800000000,
            "volume": 4000000,
            "openVolume": 4000000,
            "clientRequestId": null,
            "trades": []
        }
    ]
}

Open all orders

sample request: /v2/order/open

sample response:

{
    "success": true,
    "errorCode": null,
    "errorMessage": null,
    "orders": [
        {
            "id": 743363,
            "currency": "AUD",
            "instrument": "BTC",
            "orderSide": "Ask",
            "ordertype": "Limit",
            "creationTime": 1535659048351,
            "status": "Placed",
            "errorMessage": null,
            "price": 930706000000,
            "volume": 8404360,
            "openVolume": 8404360,
            "clientRequestId": null,
            "trades": []
        },
        {
            "id": 743565,
            "currency": "AUD",
            "instrument": "ETH",
            "orderSide": "Bid",
            "ordertype": "Limit",
            "creationTime": 1535660328066,
            "status": "Placed",
            "errorMessage": null,
            "price": 34791000000,
            "volume": 363507743,
            "openVolume": 363507743,
            "clientRequestId": null,
            "trades": []
        }
    ]
}

Cancel all orders

This method cancels all open orders for all markets or a specific markets (if marketIds parameter is provided as request body)

http POST

path: /v2/order/cancelall

If you want to cancel open orders for specific markets only, then please pass the following as the request body:

{
  "marketIds": ["BTC-AUD", "XRP-AUD"] 	
}

sample response:

{"success":true,"errorCode":null,"errorMessage":null,"orderIds":[3929899238,3929899017,3929705536]}

The response includes orderIds for which cancellation has been requested.

API authentication note: When calling this POST method and if no marketIds is provided then string to sign parameter would look like below (there should be an extra \n after the timestamp as per below)

/v2/order/cancelall
1565207864688

If marketIds is provided then string to sign parameter would look like below:

/v2/order/cancelall
1565207864688
{"marketIds":["BTC-AUD"]}

Order History

http GET

path: /v2/order/history/{instrument}/{currency}

url parameters:

indexForward: Set to true to see orders more recent than the orderId in the since parameter, if a since parameter is used. Default is false.
limit: Number of results to return per "page". If not provided, default is 200.
since: an orderId. If provided, and indexForward is false, returned results will be trades earlier than the trade id provided, non-inclusive. If indexForward is true, returned results will be trades after the orderId provided, non-inclusive.

pagination: yes

sample request: /v2/order/history/BTC/AUD?limit=3&since=701336

sample response:

{
    "success": true,
    "errorCode": null,
    "errorMessage": null,
    "orders": [
        {
            "id": 701335,
            "currency": "AUD",
            "instrument": "BTC",
            "orderSide": "Ask",
            "ordertype": "Limit",
            "creationTime": 1525903561732,
            "status": "Fully Matched",
            "errorMessage": null,
            "price": 1000000000,
            "volume": 100000000,
            "openVolume": 0,
            "clientRequestId": null,
            "trades": [
                {
                    "id": 701347,
                    "creationTime": 1525903561932,
                    "description": null,
                    "price": 2600000000,
                    "volume": 100000000,
                    "side": "Ask",
                    "fee": 22099974,
                    "orderId": 701335
                }
            ]
        },
        {
            "id": 701308,
            "currency": "AUD",
            "instrument": "BTC",
            "orderSide": "Ask",
            "ordertype": "Limit",
            "creationTime": 1525903341150,
            "status": "Fully Matched",
            "errorMessage": null,
            "price": 1000000000,
            "volume": 100000000,
            "openVolume": 0,
            "clientRequestId": null,
            "trades": [
                {
                    "id": 701332,
                    "creationTime": 1525903341371,
                    "description": null,
                    "price": 2600000000,
                    "volume": 90000000,
                    "side": "Ask",
                    "fee": 19889976,
                    "orderId": 701308
                },
                {
                    "id": 701321,
                    "creationTime": 1525903341349,
                    "description": null,
                    "price": 2700000000,
                    "volume": 10000000,
                    "side": "Ask",
                    "fee": 2294997,
                    "orderId": 701308
                }
            ]
        },
        {
            "id": 701208,
            "currency": "AUD",
            "instrument": "BTC",
            "orderSide": "Bid",
            "ordertype": "Limit",
            "creationTime": 1525899345980,
            "status": "Fully Matched",
            "errorMessage": null,
            "price": 2700000000,
            "volume": 100000000,
            "openVolume": 0,
            "clientRequestId": null,
            "trades": [
                {
                    "id": 701316,
                    "creationTime": 1525903341332,
                    "description": null,
                    "price": 2700000000,
                    "volume": 10000000,
                    "side": "Bid",
                    "fee": 2294997,
                    "orderId": 701208
                },
                {
                    "id": 701298,
                    "creationTime": 1525899507793,
                    "description": null,
                    "price": 2700000000,
                    "volume": 90000000,
                    "side": "Bid",
                    "fee": 20654975,
                    "orderId": 701208
                }
            ]
        }
    ],
    "paging": {
        "newer": "/v2/order/history/BTC/AUD?limit=3&since=701335&indexForward=true",
        "older": "/v2/order/history/BTC/AUD?limit=3&since=701208&indexForward=false"
    }
}

Trade History

http GET

path: /v2/order/trade/history/{instrument}/{currency}

url parameters:

indexForward: Set to true to see orders more recent than the tradeId in the since parameter, if a since parameter is used. Default is false.
limit: Number of results to return per "page". If not provided, default is 200.
since: an tradeId. If provided, and indexForward is false, returned results will be trades earlier than the trade id provided, non-inclusive. If indexForward is true, returned results will be trades after the tradeId provided, non-inclusive.

pagination: yes

sample request: /v2/order/trade/history/BTC/AUD?limit=4&since=701333

sample response:

{
    "success": true,
    "errorCode": null,
    "errorMessage": null,
    "trades": [
        {
            "id": 701332,
            "creationTime": 1525903341371,
            "description": null,
            "price": 2600000000,
            "volume": 90000000,
            "side": "Ask",
            "fee": 19889976,
            "orderId": 701308
        },
        {
            "id": 701321,
            "creationTime": 1525903341349,
            "description": null,
            "price": 2700000000,
            "volume": 10000000,
            "side": "Ask",
            "fee": 2294997,
            "orderId": 701308
        },
        {
            "id": 701316,
            "creationTime": 1525903341332,
            "description": null,
            "price": 2700000000,
            "volume": 10000000,
            "side": "Bid",
            "fee": 2294997,
            "orderId": 701208
        },
        {
            "id": 701298,
            "creationTime": 1525899507793,
            "description": null,
            "price": 2700000000,
            "volume": 90000000,
            "side": "Bid",
            "fee": 20654975,
            "orderId": 701208
        }
    ],
    "paging": {
        "newer": "/v2/order/trade/history/BTC/AUD?limit=4&since=701332&indexForward=true",
        "older": "/v2/order/trade/history/BTC/AUD?limit=4&since=701298&indexForward=false"
    }
}

Introduction _{updated 9/28/18}

Authentication

Pagination

WebSocket v2

WebSocket v1 _deprecated

Market Data API _{updated 7/24/19}

Trading API _{updated 08/19/19}

Transaction API

Account API _{updated 3/14/19}

Fund Transfer API _{updated 08/06/19}

FAQ

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Trading API

Order Status

Number Conversion

Create an order

General notes

Order types

Stop orders

Post-Only orders (08/30)

Time In Force (08/30)

Target Amount (08/30)

Self Trade Prevention (08/30)

Cancel an order

Order history

Open Orders

Trade History

Order detail

v2

Open Orders

Open all orders

Cancel all orders

Order History

Trade History

Clone this wiki locally