API FOR DEVELOPERS.

BitX provides an HTTP REST/JSON API for developers.

If you use it to build something, please let us know!

Security Considerations

Make sure to always use HTTPS when calling the API. Non-TLS HTTP requests cause error 403 to be returned. Using non-TLS requests can leak your authentication credentials.

Make sure that your client validates the server's SSL certificate. Many libraries (e.g. urllib2 in Python2) don't validate server certificates by default. Failing to verify the server certificate makes your application vulnerable to man-in-the-middle attack.

Conventions

Timestamps are always represented as an integer number of milliseconds since the UTC Epoch (a Unix timestamp).

Prices and volumes are always represented as a decimal strings e.g. "123.3432". We use strings instead of floats to preserve the precision.

Parameters for POST calls are sent as form values.

Rate Limiting

API calls are rate limited to roughly one request per minute per IP. Exceeding the limit causes error 503 to be returned.

Libraries

It is recommended to use a library to access the API if one is available for your language.

Public API

The Public API can be accessed by anyone without authentication.

Ticker

GET https://bitx.co.za/api/1/ticker?pair=XBTZAR

Returns the latest ticker indicators.

Result:
{
    "timestamp": 1366224386716,
    "bid": "924.00",
    "ask": "1050.00",
    "last_trade": "950.00",
    "rolling_24_hour_volume": "12.52"
  }

Order Book

GET https://bitx.co.za/api/1/orderbook?pair=XBTZAR

Returns a list of bids and asks in the order book.

Asks are sorted by price ascending. Bids are sorted by price descending. Note that multiple orders at the same price are not necessarily conflated.

Result:
{
    "timestamp": 1366305398592,
    "asks": [
      {"price": "1180.00", "volume": "0.10"},
      {"price": "2000.00", "volume": "0.10"}
    ],
    "bids": [
      {"price": "1100.00", "volume": "0.10"},
      {"price": "1000.00", "volume": "0.10"},
      {"price": "900.00", "volume": "0.10"}
    ]
  }

Trades

GET https://bitx.co.za/api/1/trades?pair=XBTZAR

Returns a list of the most recent trades.

Result:
{
    "trades": [
      {"timestamp": 1366052621774, "price": "1000.00", "volume": "0.10"}
      {"timestamp": 1366052621770, "price": "1020.50", "volume": "1.20"}
      ...
    ]
  }
  

Example

curl
$ curl https://bitx.co.za/api/1/ticker?pair=XBTZAR
Python 3.2+

First download our CA's certificate:

$ curl -O https://bitx.co.za/static/docs/UTN_USERFirst_Hardware_Root_CA.pem
#!/usr/bin/python3
  import urllib.request
  import json
  f = urllib.request.urlopen(
    'https://bitx.co.za/api/1/ticker?pair=XBTZAR', cafile='UTN_USERFirst_Hardware_Root_CA.pem')
  print(json.loads(f.read().decode('utf-8')))

If you are working on Linux, you can use the system root certificates file instead of UTN_USERFirst_Hardware_Root_CA.pem:
cafile='/etc/ssl/certs/ca-certificates.crt'

Private API

Authentication

In order to access the private API, you must first generate an API key for your account. This can be done at the API Access tab on the account page.

The key consists of an id and a secret. For example:
cnz2yjswbv3jd (key id) and 0hydMZDb9HRR3Qq-iqALwZtXLkbLR4fWxtDZvkB9h4I (key secret).

Private API calls are authenticated using HTTP basic authentication with the key id as the username and the key secret as the password. A missing or incorrect key causes error 401 to be returned.

ListOrders

GET https://bitx.co.za/api/1/listorders?pair=XBTZAR [auth required]

Returns a list of the most recently placed orders. The list is truncated after 100 items.

Result:
{
    "orders": [
      {"order_id": "BXMC2CJ7HNB88U4",
       "creation_timestamp": 1367849297609,
       "expiration_timestamp": 1367935697609,
       "type": "ASK",
       "state": "PENDING",
       "limit_price": "1000.00",
       "limit_volume": "0.80",
       "base":"0.00",
       "counter":"0.00",
       "fee_base":"0.00",
       "fee_counter":"0.00"},
       ...
    ]
  }
The possible order types are:
BID
bid (buy) limit order
ASK
ask (sell) limit order
The possible order states are:
PENDING
The order has been placed. Some trades may have taken place but the order is not filled yet.
COMPLETE
The order is no longer active and has been settled.

The base and counter amounts include fees. For example, the actual amount credited for a buy order would be base - fee_base.


PostOrder

POST https://bitx.co.za/api/1/postorder [auth required]

Create a new trade order.

Warning! Be very careful with this call. You are liable to pay for executed orders and they can't be reversed. A bug in your program could be costly.

Note that orders placed using PostOrder are subject to both the user-configurable API limits and your account limits. The API limits can be adjusted on the API Access tab on the account page.

Arguments to be passed as a form:

pair
"XBTZAR"
type
"BID" for a bid (buy) limit order or "ASK" for an ask (sell) limit order.
volume
Amount of Bitcoin to buy or sell as a decimal string in units of BTC e.g. "1.423".
price
Limit price as a decimal string in units of ZAR/BTC e.g. "1200.13".
Result in case of success:
{"order_id": "BXMC2CJ7HNB88U4"}
Result in case of error:
{"error": "Order would exceed your order limits."}

StopOrder

POST https://bitx.co.za/api/1/stoporder [auth required]

Request to stop an order.

Arguments to be passed as a form:

order_id
The order reference as a string e.g. BXMC2CJ7HNB88U4
Result in case of success:
{"success": true}
Result in case of error:
{"error": "Cannot stop unknown or non-pending order"}

Balance

GET https://bitx.co.za/api/1/balance?asset=XBT [auth required]

Returns the trading account balance and reserved funds.

Result:
{
    "balance": [
      {
        "asset": "XBT",
        "balance": "1.12434",
        "reserved": "0.92"
      }
    ]
  }

Bitcoin Funding Address

GET https://bitx.co.za/api/1/funding_address?asset=XBT [auth required]

Returns the asset address you need to use to fund your trade account balance.

Result:
{
    "asset": "XBT",
    "address": "B1tC0InExAMPL3fundIN6AdDreS5t0Use"
  }


Changelog