Tokenomy API v1 Documentation
Guides, tutorials, and detailed reference docs to help you build your application.
Welcome to the Tokenomy API exchange documentation. You can build your application or trading bot by following this document.
Public API
The following data is available to the public. These methods do not require an API key for retrieval of data. You can call simple GET requests or use a browser to enter the URL directly. Since most of the API methods require a 'pair' parameter you can first retrieve the existing set from the 'Summary API' below.
API Name | Url | Example | Description |
---|---|---|---|
Summaries | https://spot.tokenomy.com/api/summaries | https://spot.tokenomy.com/api/summaries | Retrieve the summary of all traded pairs, highest price, lowest price, volume, last price, token/coin name. This API method can also be used to discover all current traded pairs. |
Ticker | https://spot.tokenomy.com/api/[pair]/ticker | https://spot.tokenomy.com/api/ten_btc/ticker | Show the price summary of an individual pair. |
Trades | https://spot.tokenomy.com/api/[pair]/trades | https://spot.tokenomy.com/api/ten_btc/trades | Show the latest trades for a particular pair. |
Public Order Book | https://spot.tokenomy.com/api/[pair]/depth | https://spot.tokenomy.com/api/ten_btc/depth | Display the public order book and market depth. |
Market Info | https://spot.tokenomy.com/api/market_info | https://spot.tokenomy.com/api/market_info | Display the list of all available pairs including limit information and market status. |
Private API
Before using the Private API, you will first need to obtain your API credentials by logging into your Tokenomy Exchange account (https://spot.tokenomy.com) and open the Trade API section (https://spot.tokenomy.com/trade_api). These credentials contain "API Key" and "Secret Key". Please keep these credentials safe and do not reveal to any external party.
Permission | Allowed Methods |
---|---|
view | getInfo, transHistory, tradeHistory, openOrders, orderHistory, getOrder |
trade | trade, cancelOrder |
withdraw | withdrawCoin |
Now, you are ready to connect your application to our private API.
Authentication
Each Private API request must be authenticated. You will need to put your API key in the request header and use the Secret Key to encrypt the POST data. Both keys are obtained from the previous step.
Authorization is completed by sending data via the HTTP header with the following parameter:
Key | API key. Example: 14B0C9D6-UG71XOID-SH4IB5VQ-A9LK3YVZ-4HFR8X2T |
Sign | POST data (?param=val¶m1=val1) encrypted with method HMAC-SHA512 using secret key |
Send request to this URL: https://spot.tokenomy.com/tapi
All requests must be sent with POST.
Content type must be “application/x-www-form-urlencoded”.
For each request you need to include the following parameters:
nonce:
An increment integer. For example if the last request's nonce is 1000, the next request should be 1001 or a larger number.
To learn more about nonce please see: https://en.wikipedia.org/wiki/Cryptographic_nonce
method:
Specify the method you want to call. You can find the list of available methods you can call in the latter part of this document.
Responses
All responses are returned in JSON format. See examples below.
Response format if the request successfully executed:
{
"success":1,
"return":{
/*here is some returned data*/
}
}
Response format if request resulting an error:
{
"success":0,
"error":"some error message"
}
getInfo
This method gives the user balance and server timestamp.
Parameter: none
Response example:
{
"success":1,
"return":{
"balance":{
"ten":2000,
"btc":1.52,
"ltc":33.14,
... #other coins balances
},
"server_time":1392225342
}
}
transHistory
This method returns the history of deposits and withdrawals of all assets.
Parameter: none
Response example:
{
"success":1,
"return":{
"withdraw":{
"ten":[
{
"status":"wait",
"type":"coupon",
"ten":"100",
"fee":"0",
"amount":"100",
"submit_time":"1392135074",
"success_time":"0"
}
],
"btc":[
{
"status":"success",
"btc":"150000000",
"fee":"20000",
"amount":"149980000",
"submit_time":"1392135074",
"success_time":"0"
}
],
"ltc":[
],
... #other coins
},
"deposit":{
"ten":[
{
"status":"success",
"type":"bank",
"ten":"10000",
"fee":"0",
"amount":"10000",
"submit_time":"1392193569",
"success_time":"1392193569"
}
],
"btc":[
{
"status":"success",
"btc":"200000000",
"amount":"200000000",
"success_time":"1391979201"
}
],
... #other coins
}
}
}
trade
This method is for creating a new order.
Parameter:
Parameter | Required? | Description | Value | Default |
---|---|---|---|---|
pair | Yes | Pair to get the information from | ten_btc, ltc_btc, etc | - |
type | Yes | transaction type (buy or sell) | buy / sell | - |
price | Yes | order price | numerical | - |
ten | required if selling ten using limit method | Amount of ten used to buy / sell from limit | numerical | - |
btc | required if sell using market method | Amount of btc used to buy from market | numerical | - |
order_method | No | order method (limit or market) | limit / market | limit |
Response example:
{
"success":1,
"return":{
"receive_btc":0,
"remain_ten":1000000,
"order_id":11560,
"balance":{
"ten":"8000",
"btc":1.52,
"ltc":900.092,
... #other coins
}
}
}
tradeHistory
This method returns trade history.
Parameter:
Parameter | Required? | Description | Value | Default |
---|---|---|---|---|
count | No | number of transaction which will be displayed | numerical | 1000 |
from_id | No | first ID | numerical | 0 |
end_id | No | end ID | numerical | ∞ |
order | No | sort by | asc / desc | desc |
since | No | start time | UNIX time | |
end | No | end time | UNIX time | |
pair | Yes | Pair to get the information from | ten_btc, ltc_btc, etc | ten_btc |
Response example:
{
"success":1,
"return":{
"trades":[
{
"trade_id":"2929",
"order_id":"8123",
"type":"buy",
"btc":0.013,
"price":"8068585",
"fee":"1049",
"trade_time":"1392226454"
},
{
"trade_id":"2920",
"order_id":"8111",
"type":"sell",
"btc":0.01499999,
"price":"8086935",
"fee":"1214",
"trade_time":"1392225916"
}
]
}
}
openOrders
This method returns the current open orders (buy and sell).
Parameter:
Parameter | Required? | Description | Value | Default |
---|---|---|---|---|
pair | No | Pair to get the information from | ten_btc, ltc_btc, etc | - |
Response example (if pair is set):
{
"success":1,
"return":{
"orders":[
{
"order_id":"11567",
"submit_time":"1392227908",
"price":"10000000",
"type":"buy",
"order_ten":"1000000",
"remain_ten":"1000000"
}
]
}
}
Response example (if pair is not set):
{
"success": 1,
"return": {
"orders": {
"ten_btc": [
{
"order_id": "11567",
"submit_time": "1392227908",
"price": "10000000",
"type": "buy",
"order_ten": "1000000",
"remain_ten": "1000000"
}
],
"ltc_btc": [
{
"order_id": "12345",
"submit_time": "1392228122",
"price": "8000000",
"type": "sell",
"order_ltc": "100000000",
"remain_ltc": "100000000"
}
]
}
}
}
orderHistory
This method returns the order history (buy and sell).
Parameter:
Parameter | Required? | Description | Value | Default |
---|---|---|---|---|
pair | Yes | Pair to get the information from | ten_btc, ltc_btc, etc | ten_btc |
count | No | integer | 100 | |
from | No | integer | 0 |
Response example:
{
"success": 1,
"return": {
"orders": [
{
"order_id": "11512",
"type": "sell",
"price": "5000000",
"submit_time": "1392227908",
"finish_time": "1392227978",
"status": "filled",
"order_btc": "0.00100000",
"remain_btc": "0.00000000"
},
{
"order_id": "11513",
"type": "buy",
"price": "5000000",
"submit_time": "1392227908",
"finish_time": "1392227978",
"status": "cancelled",
"order_ten": "1000",
"remain_ten": "1000"
}
]
}
}
getOrder
This method can be used to return details of a specific order.
Parameter:
Parameter | Required? | Description | Value | Default |
---|---|---|---|---|
pair | Yes | Pair to get the information from | ten_btc, ltc_btc, etc | - |
order_id | Yes | Order ID | integer | - |
Response example:
{
"success": 1,
"return": {
"order": {
"order_id": "94425",
"price": "0.00810000",
"type": "sell",
"order_ltc": "1.00000000",
"remain_ltc": "0.53000000",
"submit_time": "1497657065",
"finish_time": "0",
"status": "open"
}
}
}
{
"success": 1,
"return": {
"order": {
"order_id": "664257",
"price": "1000000",
"type": "buy",
"order_ten": "10000",
"remain_ten": "0",
"submit_time": "1497330670",
"finish_time": "1497330670",
"status": "filled"
}
}
}
cancelOrder
This method is for canceling an existing open order.
Parameter:
Parameter | Required? | Description | Value | Default |
---|---|---|---|---|
pair | Yes | Pair to get the information from | ten_btc, ltc_btc, etc | - |
order_id | Yes | Order ID | numerical | - |
type | Yes | transaction type (buy or sell) | buy / sell | - |
Response example:
{
"success":1,
"return":{
"order_id":11574,
"type":"buy",
"balance":{
"ten":"5000",
"btc":2.5,
"ltc":900.092,
... #other coins
}
}
}
withdrawCoin
This method is for withdrawing assets (except TEN).
To be able to use this method you need to enable the 'withdraw' permission when you generate the API Key. Otherwise you will receive a “No permission” error.
You also need to prepare a Callback URL. Callback URL is a URL that our system will call to verify your withdrawal requests. Various parameters will be sent to Callback URL so please make check this information in your application. If all the data is correct, print out a string “ok” (without quotes). We will continue the request only if we receive an “ok” (without quotes) response, otherwise the request will fail.
Callback call will be sent through a POST request, with 5 seconds connection timeout.
Request Parameter:
Parameter | Required? | Description | Value | Default |
---|---|---|---|---|
currency | Yes | Currency to withdraw | btc, ltc, eth, etc | - |
withdraw_address | Yes | Receiver address | a valid address | - |
withdraw_amount | Yes | Amount to send | numerical | - |
withdraw_memo | No | Memo to be sent to the receiver, if supported by the asset platform. Exchanges use this memo for accepting deposits for certain assets. Example: Destination Tag (for Ripple) Message (for NXT) Memo (for BitShares) |
a valid memo/message/destination tag | - |
request_id | Yes | Custom string you need to provide to identify each withdrawal request. request_id will be passed to callback call so your system can identify the request. | alphanumeric, max length 255 | - |
Response example:
{
"success": 1,
"status": "approved",
"withdraw_currency": "xrp",
"withdraw_address": "rwWr7KUZ3ZFwzgaDGjKBysADByzxvohQ3C",
"withdraw_amount": "10000.00000000",
"fee": "2.00000000",
"amount_after_fee": "9998.00000000",
"submit_time": "1509469200",
"withdraw_id": "xrp-12345",
"txid": "",
"withdraw_memo": "123123"
}
Callback parameter:
Parameter | Description |
---|---|
request_id | request_id from your request |
withdraw_currency | currency from your request |
withdraw_address | withdraw_address from your request |
withdraw_amount | withdraw_amount from your request |
withdraw_memo | withdraw memo from your request (if any) |
requester_ip | ip address of the request |
request_date | time the request submitted |
PHP Function
<?php
function btcid_query($method, array $req = array()) {
// API settings
$key = ''; // your API-key
$secret = ''; // your Secret-key
$req['method'] = $method;
$req['nonce'] = time();
// generate the POST data string
$post_data = http_build_query($req, '', '&');
$sign = hash_hmac('sha512', $post_data, $secret);
// generate the extra headers
$headers = array(
'Sign: '.$sign,
'Key: '.$key,
);
// our curl handle (initialize if required)
static $ch = null;
if (is_null($ch)) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; TOKENOMY PHP client;
'.php_uname('s').'; PHP/'.phpversion().')');
}
curl_setopt($ch, CURLOPT_URL, 'https://spot.tokenomy.com/tapi/');
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
// run the query
$res = curl_exec($ch);
if ($res === false) throw new Exception('Could not get reply: '.curl_error($ch));
$dec = json_decode($res, true);
if (!$dec) throw new Exception('Invalid data received, please make sure connection is working and
requested API exists: '.$res);
curl_close($ch);
$ch = null;
return $dec;
}
$result = btcid_query('getInfo');
print_r($result);
Reference
The Websocket API is an advanced technology that makes it possible to open a two-way interactive communication session between the user's browser and a server. With this API, you can send messages to a server and receive event-driven responses without having to poll the server for a reply. Use JSON-RPC 2.0 over WebSocket connection as transport.
Ping/Pong
The Server Websocket API will do ping every 30 second for checking network session still alive. If in 3 ping user failed ping by server. The user will be kick on the list of our server. Note: User don't need to send ping to our server.
Request Object
To connect to ws server you need to call ws request connect at ws://ws.tokenomy.com/v1. Web Socket call is represented by sending a Request object to a Server. The Request object has the following members:
method | a String containing the name of the method be invoked |
event | an String containing the name of the event be invoked example : subscribe, unsubscribe. |
params | a Structured value that holds the parameter values to be used during the invocation of the method. |
Example to connect & sending request object:
wscat -c wss://ws.tokenomy.com/v1
{
"method": "tradeHistory",
"event": "subscribe",
"params": {
"pair": "TEN-BTC"
}
}
Subscribe to Order Book (Depth)
Request event subscribe or unsubscribe with the method depth example:
Parameter:
{
"method": "depth", # Required
"event": "subscribe", # Required | subscribe/unsubscribe
"params": {
"pair": "TEN-BTC" # Required | ETH-BTC/ etc
}
}
Notification Snapshoot:
{
"status":1,
"method":"depth",
"pair":"TEN-BTC",
"return":{
"asks":[
[
"0.00010000",
"30.00000000"
]
],
"bids":[
[
"0.00000009",
"2980.00000000"
]
]
},
"server_time":1561090205
}
Subscribe to Trade History
Request event subscribe or unsubscribe with the method tradeHistory example:
Parameter:
{
"method": "tradeHistory", # Required
"event": "subscribe", # Required | subscribe/unsubscribe
"params": {
"pair": "TEN-BTC" # Required | ETH-BTC/ etc
}
}
Notification Snapshoot:
{
"status":1,
"method":"tradeHistory",
"pair":"TEN-BTC",
"return":[
{
"date":1561090205,
"price":"0.00000009",
"amount":"100.00000000",
"tid":794,
"type":"ask"
}
],
"server_time":1561090206
}
Troubleshooting
I'm getting a 403 Unauthorized or 403 Forbidden error.
Our firewall has strict controls and occasionally this can create a false positive for genuine requests. Please send your IP addresses to our customer service so we can manually unblock your IPs.
I'm getting “Too Many Requests” error.
To prevent abusive requests, we limit API call to 180 requests per minute.
I'm getting "Invalid nonce" error after migration to production server.
If you use a timestamp for your nonce, your production server time might not match with your development server. To prevent this you can add 86400 to the nonce. To reset nonce, disable and create a new API Key.