REST APIv2

Endpoint: /api/v2
Response: JSON

There are two sets of APIs: Public and Private.

The Public API requires no authentication, no threshold, while the Private one does and has a threshold of 1000 request/keypair/5 minutes.

note: API abuse is still subject to throttle or temporary IP ban even if there is no threshold.

Authentication

To use private API, you need to get your access/secret key first. Please visit API Tokens page to get your keys. All private API requires 3 parameters: access_key, tonce and signature.

• access_key is self explained
• tonce is a timestamp in integer, stands for milliseconds elapsed since Unix epoch. Tonce must be within 30 seconds of server’s current time. Each tonce can only be used once.
• signature is a hash of the API request, generated by you using your secret key.

# Signature is a hash of the request (in canonical string form):
signature = HMAC-SHA256(payload, secret_key).to_hex

# Payload is a combination of HTTP verb, uri, and query string:
# canonical_verb is HTTP verb like GET/POST in upcase.
# canonical_uri is request path like /api/v2/markets.
# canonical_query is the request query sorted in alphabetica order, 
#     including access_key and tonce, e.g. access_key=xxx&foo=bar&tonce=123456789
# The combined string looks like:
# GET|/api/v2/markets|access_key=xxx&foo=bar&tonce=123456789
def payload
  "\#{canonical_verb}|\#{canonical_uri}|\#{canonical_query}"
end

Query parameters are sorted in payload, so it must be "access_key=xxx&foo=bar" not "foo=bar&&access_key=xxx".

# For example, Suppose my secret key is 'yyy', then the result of HMAC-SHA256 of above payload is:
hash = HMAC-SHA256('GET|/api/v2/markets|access_key=xxx&foo=bar&tonce=123456789', 'yyy').to_hex
 = 'e324059be4491ed8e528aa7b8735af1e96547fbec96db962d51feb7bf1b64dee'

Now we hav a signed request which can be used like this:

curl -X GET 'https://ccx.io/api/v2/markets?access_key=xxx&foo=bar&tonce=123456789&signature=e324059be4491ed8e528aa7b8735af1e96547fbec96db962d51feb7bf1b64dee'

Response Format

Corresponding HTTP status code will be used in API response. CCX will also return a JSON structure including error details on failed request, for example:

{"error":{"code":1001,"message":"market does not have a valid value"}}

All errors follow the message format above, only differ in code and message.

• code is an application defined error code, indicating error’s category
• message is human-readable details.

Server returns HTTP 200 response on successful request, with requested data in JSON format. A few data structures are defined as below:

Market

Example：

{
  "at":1398410899, 
  "ticker":{
      "buy":"3000.0",
      "sell":"3100.0"
      "low":"3000.0"
      "high":"3000.0"
      "last":"3000.0"
      "vol":"0.11"
    }
}

• at: A timestamp in seconds since Epoch
• buy/sell: Current buy/sell price
• low/high: Lowest/highest price in last 24 hours
• last_desc: Last price
• vol_desc: Trade volume in last 24 hours

Member

Example：

{                                                                                                                             
  "sn": "PEA5TFFOGQHTIO",
  "name": "foo",
  "email": "foo@CCX.dev",
  "activated": true,
  "accounts": [
    {
      "currency": "aud",
      "balance": "100243840.0",
      "locked": "0.0"
    },
    {
      "currency": "btc",
      "balance": "99999708.26",
      "locked": "210.8"
    }
  ]
}

• sn: Unique identifier of user
• name: User name
• email: User email
• activated: Whether user is activated
• accounts: User’s accounts info, see Account

Account

Example：

{"currency":"aud","balance":"100243840.0","locked":"0.0"}

• balance: Account balance, exclude locked funds
• locked: locked funds

Order

{
  "id": 7,
  "side": "sell",
  "price": "3100.0",
  "avg_price": "3101.2",
  "state": "wait",
  "market": "btcaud",
  "created_at": "2014-04-18T02:02:33Z",
  "volume": "100.0",
  "remaining_volume": "89.8",
  "executed_volume": "10.2",
  "trades": [
    {
      "id": 2,
      "price": "3100.0",
      "volume": "10.2",
      "market": "btcaud",
      "created_at": "2014-04-18T02:04:49Z",
      "side": "sell"
    }
  ]
}

• id: Unique order ID
• side: Buy/Sell
• price: Order price
• avg_price: Average execution price
• state: wait, done or cancel. ‘wait’ represents the order is active, it may be a new order or partial complete order; ‘done’ means the order has been fulfilled completely; ‘cancel’ means the order has been cancelled.
• market: Which market the order belongs to
• created_at: Order created time
• volume: volume to buy/sell
• remaining_volume: remaining_volume is always less or equal than volume
• executed_volume: volume = remaining_volume + executed_volume
• trades: the order’s trade history, see Trade. Note: not all order include trades, only detailed order data returned by certain API will.

Trade

{
  "id": 2,
  "price": "3100.0",
  "volume": "10.2",
  "market": "btcaud",
  "created_at": "2014-04-18T02:04:49Z",
  "side": "sell"
}

• id: Unique ID
• price: trade price
• volume: trade volume
• market: the market trade belongs to, like ‘btcaud’
• created_at: trade time

OrderBook

{"asks": [...],"bids": [...]}

• OrderBook shows orders on market.

Asynchronous calls

POST /api/v2/order/delete: Cancel order is an asynchronous operation. A success response only means your cancel request has been accepted, it doesn’t mean the order has been cancelled. You should always use GET /api/v2/order or websocket api to get order’s latest state.

POST /api/v2/orders/clear: Cancel all orders is an asynchronous operation. A success response only means your request has been accepted. The orders in response may or may not have been cancelled yet.

API list

Here is the full list.