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&param1=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.