REST API v2
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 explainedtonce
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. KingDragon 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 categorymessage
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 Epochbuy
/sell
: Current buy/sell pricelow
/high
: Lowest/highest price in last 24 hourslast_desc
: Last pricevol_desc
: Trade volume in last 24 hours
Member
Example:
{ "sn": "PEA5TFFOGQHTIO", "name": "foo", "email": "[email protected]", "activated": true, "accounts": [ { "currency": "aud", "balance": "100243840.0", "locked": "0.0" }, { "currency": "btc", "balance": "99999708.26", "locked": "210.8" } ] }
sn
: Unique identifier of username
: User nameemail
: User emailactivated
: Whether user is activatedaccounts
: User’s accounts info, see Account
Account
Example:
{"currency":"aud","balance":"100243840.0","locked":"0.0"}
balance
: Account balance, exclude locked fundslocked
: 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 IDside
: Buy/Sellprice
: Order priceavg_price
: Average execution pricestate
: 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 tocreated_at
: Order created timevolume
: volume to buy/sellremaining_volume
: remaining_volume is always less or equal than volumeexecuted_volume
: volume = remaining_volume + executed_volumetrades
: 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 IDprice
: trade pricevolume
: trade volumemarket
: the market trade belongs to, like ‘btcaud’created_at
: trade time
OrderBook
{"asks": [...],"bids": [...]}
- OrderBook shows
order
s 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.
Comments
0 comments
Article is closed for comments.