Authentication

To use any of the authenticated calls you must sign the call with a one time hash signature. You will need to

API Key

These can be created here on your accounts page The secret associated with the Key will only be displayed once after you have verified the Key creation by E-Mail You must create a new key if the secret is lost.

Nonce

A Nonce is a regular integer number. It must be increased with every request you make associated with the given Key For example you may set the first nonce to 1 in your first request, it must be at least 2 in your second request and so on. You may start at any number you like. It is often convenient to use a integer timestamp.

Signature

The signature used is a HMAC-SHA256 encoded hash of the ( NONCE + Your UserID + API Key ). The HMAC-SHA256 code must be generated using the secret issued with your API key. This signature needs to be sent as a hexadecimal string 64 characters long

Your User ID is the same 7 to 12 digit number used to sign in at logon.
Various examples of signature generation code can be found here in the coding example section

The signature Key and nonce must be included as parameters on all requests.
The Key secret is NEVER sent on a request.

Note The API will only respond to well formed POST requests over https. You must include all required parameters and set the Content Type header correctly to "Content-Type", "application/x-www-form-urlencoded" Invalid requests may be dropped silently.

Account Balance

POST https://nzbcx.com/api/account/balance

Required Parameters
  • nonce -- > An incremental number
  • key -- > Your API Key
  • signature -- > The HMAC-SHA256 digest generated with your key secret
Example Output
  {
      "BTC_available": "0.00000000",
      "BTC_reserved": "0.00000000",
      "BTC_pending": "0.00000000",
      "BTC_balance": "0.00000000",
      "NZD_available": "542.29400000",
      "NZD_reserved": "507.70600000",
      "NZD_pending": "0.00000000",
      "NZD_balance": "1050.00000000"
  }
        

Transactions

POST https://nzbcx.com/api/account/transactions

Required Parameters
  • nonce -- > An incremental number
  • key -- > Your API Key
  • signature -- > The HMAC-SHA256 digest generated with your key secret
  • Optional Parameters
  • since - System transaction sequence id to query from, Default 0, returned as id in result set
  • limit - Maximum rows returned max, Default 100
  • sort - desc or asc Default asc
Example Output
  [{
    "txn_id": "23490255571124263-D",
    "currency_code": "NZD",
    "amount": "50.00000000",
    "description": "deposited funds",
    "state": "Completed",
    "timestamp": "2014-05-23 16:45:12",
    "id": 12
}, {
    "txn_id": "23504011999051776-D",
    "currency_code": "NZD",
    "amount": "1000.00000000",
    "description": "deposited funds",
    "state": "Completed",
    "timestamp": "2014-05-27 12:14:01",
    "id": 16
}]
        

Note Timestamp values "timestamp": "2014-05-27 12:14:01" when expressed in human readable fromat are in UTC/GMT time and are not converted to yoru local time zone.

Executions

POST https://nzbcx.com/api/account/executions

Required Parameters
  • nonce -- > An incremental number
  • key -- > Your API Key
  • signature -- > The HMAC-SHA256 digest generated with your key secret
  • Optional Parameters
  • minutes - Filters results to executions in the last X minutes
  • hours - Filters results to executions in the last X hours
  • days - Filters results to executions in the last X days
  • order_id - Client order id Default empty limits results to single order

  • The time period is defulted to 1 hour if none is specified
Example Output
[ { "comp_rate" : "0.0005",
    "exchange_order_id" : "f4c86153-ca86-44fd-9452-0b9fdbeceeb2",
    "exec_id" : "c3e9338a-4699-4aed-8d42-64f3f56a79a7",
    "exec_price" : "500.01000000",
    "ord_price" : "0.00000000",
    "order_id" : "NZ-WEB-B-537f802003f60-5520aa1074b76",
    "quantity" : "0.01000000",
    "side" : "SELL",
    "ticker" : "BTCNZD",
    "timestamp" : "2015-04-05 03:20:51",
    "trade_seq_num" : "1988",
    "txn_id" : "Sc3e9338a-4699-4aed-8d42-64f3f56a79a7",
    "txn_seq_num" : "8260",
    "type" : "MKT",
    "utc_timestamp" : "1428204051.396000"
  },
  { "comp_rate" : "0.0005",
    "exchange_order_id" : "2879c43d-169b-41e2-b237-8fb6e77dc38a",
    "exec_id" : "43d9ec61-3d9d-4330-80cf-40d77b63f8bc",
    "exec_price" : "466.64000000",
    "ord_price" : "400.00000000",
    "order_id" : "NZ-WEB-B-537f802003f60-5520aa721cebd",
    "quantity" : "0.83760000",
    "side" : "SELL",
    "ticker" : "BTCNZD",
    "timestamp" : "2015-04-05 03:22:28",
    "trade_seq_num" : "1996",
    "txn_id" : "43d9ec61-3d9d-4330-80cf-40d77b63f8bc-W",
    "txn_seq_num" : "8294",
    "type" : "LMT",
    "utc_timestamp" : "1428204148.893000"
  }
]          
        

Orders

POST https://nzbcx.com/api/account/orders

Required Parameters
  • nonce -- > An incremental number
  • key -- > Your API Key
  • signature -- > The HMAC-SHA256 digest generated with your key secret
  • Optional Parameters
  • status - Filters ordres on status Default: A (Active only ) [U,A,C,P,R,X,PC]
  • order_id - Client order id Default empty limits results to single order

Example Output
[{
    "order_id": "TEST-00001",
    "update_timestamp": "1401457905",
    "status": "A",
    "type": "LMT",
    "side": "BUY",
    "price": "400.00000000",
    "quantity": "0.01000000",
    "filled": "0.00000000",
    "remaining": "0.01",
    "exchange_order_id": "802f5adb-13cb-4089-9eed-a7468f3bf904",
    "timestamp": "1401854094"
}, {
    "order_id": "API_D_537f7ab521b14_53888f5d8104f",
    "update_timestamp": "1401458529",
    "status": "A",
    "type": "LMT",
    "side": "BUY",
    "price": "300.00000000",
    "quantity": "0.10000000",
    "filled": "0.00000000",
    "remaining": "0.1",
    "exchange_order_id": "2c159908-98d4-4243-a783-c4ef23a0ad49",
    "timestamp": "1401854094"
}]
        

Order Cancel

POST https://nzbcx.com/api/account/order/cancel

Required Parameters
  • nonce -- > An incremental number
  • key -- > Your API Key
  • signature -- > The HMAC-SHA256 digest generated with your key secret

  • order_id --Client order id

Example Output
{
    "order_id": "NZ-WEB-D-537f7ab521b14-53889058560d2",
    "update_timestamp": "1401501100",
    "status": "PC"
}
        

Order Archive

POST https://nzbcx.com/api/account/order/archive

Required Parameters
  • nonce -- > An incremental number
  • key -- > Your API Key
  • signature -- > The HMAC-SHA256 digest generated with your key secret

  • order_id --Client order id

Example Output
{
    "order_id": "NZ-WEB-D-537f7ab521b14-5388903d3sfs",
    "update_timestamp": "1401501100",
    "status": "AR"
}
        

New Order

POST https://nzbcx.com/api/account/new/order

Required Parameters
  • nonce -- > An incremental number
  • key -- > Your API Key
  • signature -- > The HMAC-SHA256 digest generated with your key secret

  • ticker --The order ticker example ( BTCNZD )
  • side --Buy or sell ( BUY , SELL )
  • type --Limit or Market order ( LMT , MKT )
  • price --Required only on LMT, limit orders
  • quantity --Order amount no defaults
  • Optional Parameters
  • order_id --Client order id Default empty your order is assigned a new unique id

Example Output
{
    "order_id": "NZ-API-D-537f7ab521b14-538d42921b708",
    "update_timestamp": "1401766546",
    "status": "P",
    "type": "LMT",
    "side": "BUY",
    "price": "543",
    "quantity": "0.01",
    "filled": "",
    "remaining": "0.01",
    "exchange_order_id": null,
    "timestamp": "1401766546"
}
        

End of Day ( ** Experimental *** )

POST https://nzbcx.com/api/account/orders/endofday

Required Parameters
  • nonce -- > An incremental number
  • key -- > Your API Key
  • signature -- > The HMAC-SHA256 digest generated with your key secret
Example Output
{
   "canceled": "5",
   "archived": "5",
   "errors": "0"
}
        


This call will attempt to cancel and then archive all orders. It is provided for an easy end of day clean up.

Developer Notes

Implementation

There are some inconsistencies in the API in the formatting of timestamps the use of the amount vs quantity field. Some of this is a deliberate attempt to provide cross compatibility with existing exchanges out there while some of it may well be corrected.
While we fully acknowledge there is some debate over the correctness of REST full APIs and the implementation of an exchange API over HTTPS it has become the industry standard and has been provided more for convince and ease of implementation than best practice. It would be our intention to eventually provide a full streaming API if and when there was demand for this.

Synchronization

The API calls are not synchronous . For both simplicity and to avoid the need to block a caller while waiting on the exchange they have been implemented to return immediately.
New order and cancel request return the order status as P or PC, meaning pending or pending cancel.
These opperations can still be fail, for example if an order was matched before a cancel request reached the exchange or the market was in a condition that did not permit a new order entry. Market orders are rejected when no matching quantity exists or when there execution would result in a large market movement.
In these cases the order would be rejected and have a status of R. This my not be immediately obvious until an order book query is done using the order id
Limited market side validations are in place to help protect clients from programming and fat finger errors.

Limitations

Withdrawal and deposit calls have been quite deliberately left out the the current API This is for several reasons firstly as a security measure to limit the possibility of unauthorised account withdraws. Secondly we have implemented but not yet deployed a key level access right system and we would not provide automated API withdrawals until this system was fully tested and deployed. Finally we would like to avoid or at least make it more difficult for 3rd parties to simply use our API as a mean of on selling with out putting up any capital or providing any significant services. We have seen a number of sites come an go quickly that simply add a large mark up and some paid for search terms. While some people view this as a legitimate business model we believe it to be predatory and neither good for the consumer or bit coin.

Talk to us first

What we would recommend is having a quick chat to us first before you put in those hard hours to code up that python script. If your idea sounds legit we might even give you a helping hand or even provide a custom api to better fit your needs.

Contribute As always we are happy to hear you feedback and suggestions for improvement. Send us your feedback