Tokens.net API documentation

Introduction

Tokens.net allows users to interact with trading platform programmatically via HTTP API, located at https://api.tokens.net/. API allows users to view, add and cancel orders as well as view account balance and perform various other tasks.

Performing a call

Some API calls can be performed without authentication while others require you to be registered with Tokens.net platform and have generated an API key. Each authenticated API request needs to contain the following HTTP headers:

  1. key: API key associated with users trading account
  2. nonce: sequential number associated with current request
  3. signature: hmac of concatenated nonce and API key using SHA-256 hashing algorithm

We provide the following examples for Bash and Python programming languages:

Bash example
#!/bin/bash

apiurl="https://api.tokens.net/private/balance/btc/"
apikey="0123456789abcdef0123456789abcdef"
secret="0123456789abcdef0123456789abcdef"
nonce="0"
message="${nonce}${apikey}"
signature=`echo -n "$message" | openssl dgst -sha256 -hmac $secret | cut -d" " -f2`

curl $apiurl -H "key:$apikey" -H "nonce:$nonce" -H "signature:${signature^^}"
Python example
#!/usr/bin/env python3

import hashlib, hmac, requests

apiurl = "https://api.tokens.net/private/balance/btc/"
apikey = "0123456789abcdef0123456789abcdef"
secret = "0123456789abcdef0123456789abcdef"
nonce = "0"
message = "{}{}".format(nonce, apikey).encode("utf8")
signature = hmac.new(secret.encode("utf8"), message, hashlib.sha256).hexdigest().upper()

r = requests.get(apiurl, headers = {"key": apikey, "nonce": nonce, "signature": signature})
print(r.text)

Variables apikey and secret should be replaced with your API key and secret respectively, while nonce should be increased for each subsequent request.

Libraries

To make interaction with API easier we recommend using one of the following libraries depending on your programming language of choice:

  1. Python: tokens-client-python
  2. C#: Tokens.Net (unofficial)
  3. Node.js / TypeScript: tokens-net (unofficial)

Return values

API returns results in JSON format. Results of most methods include status property and timestamp property containing the current UNIX time.

The status property can have the following values:

  • ok
  • error

Errors

Errors can occur for multiple reasons. Each error returns errorCode and reason properties, which include information about the nature of the error.

Error code Reason
100 API Key is missing
101 Nonce is missing
102 Signature is missing
110 Nonce has to be integer
111 Provided nonce is less or equal to the last nonce
120 Invalid API key
121 Signature is invalid
130 Invalid trading pair
131 Invalid order id
140 Only opened orders can be canceled
150 Parameter {parameter} is invalid with error: {error}
160 Invalid currency code
429 API rate limit exceeded
Error example
{
"timestamp": 1234567890,
"status": error,
"errorCode": 100,
"reason": API Key is missing
}

API reference

API calls are performed by sending a HTTP request to URL starting with https://api.tokens.net, followed by endpoint URL listed in the table below.

Replace values in curly braces with appropriate variables:

  • {id}: entry ID, for example 01234567-89ab-cdef-0123-456789abcdef
  • {trading_pair}: trading pair ID, for example btcusdt
Method Endpoint URL Function Authentication
GET /public/ticker/{trading_pair}/ Ticker for last day No
GET /public/ticker/hour/{trading_pair}/ Ticker for last hour No
GET /public/trades/minute/{trading_pair}/ List trades in last minute No
GET /public/trades/hour/{trading_pair}/ List trades in last hour No
GET /public/trades/day/{trading_pair}/ List trades in last day No
GET /public/trading-pairs/get/all/ List all existing trading pairs No
GET /public/order-book/{trading_pair}/ List open buy and sell orders No
GET /private/balance/{currency}/ Account balance for selected currency Yes
GET /private/orders/get/all/ List open orders for your account Yes
GET /private/orders/get/{id}/ List a single order for your account Yes
GET /private/orders/get/{trading_pair}/ List orders for your account for a trading pair Yes
POST /private/orders/add/limit/ Place an order Yes
POST /private/orders/cancel/{id}/ Cancel an order Yes
GET /public/voting/get/all/ List all currencies participating in voting No

Ticker

Get ticker for last day or hour.

Method Endpoint URL Function Authentication
GET /public/ticker/{trading_pair}/ Ticker for last day No
GET /public/ticker/hour/{trading_pair}/ Ticker for last hour No
Request
curl https://api.tokens.net/public/ticker/btcusdt/
Response
{
"status": ok,
"timestamp": 1234567890,
"bid": "1234.56",
"open": "1234.56",
"low": "1234.56",
"high": "1234.56",
"last": "1234.56",
"ask": "1234.56",
"vwap": "0.00000000",
"volume": "0.00000000",
"volume_usdt": "0.00000000"
}

Trades

List trades, which occured in last minute, hour or day.

Method Endpoint URL Function Authentication
GET /public/trades/minute/{trading_pair}/ List trades in last minute No
GET /public/trades/hour/{trading_pair}/ List trades in last hour No
GET /public/trades/day/{trading_pair}/ List trades in last day No
Request
curl https://api.tokens.net/public/trades/minute/btcusdt/
Response
{
"status": "ok",
"trades": [{
"id": 1234567,
"datetime": 1234567890",
"price": "1234.56",
"type": "buy",
"amount": "0.12345678"
}],
"timestamp": 1234567890"
}

Trading pairs

List all existing pairs.

Method Endpoint URL Function Authentication
GET /public/trading-pairs/get/all/ List all existing trading pairs No
Request
curl https://api.tokens.net/public/trading-pairs/get/all/
Response
{
"btcusdt": {
"title": "BTC/USDT",
"amountDecimals": 8,
"priceDecimals": 2,
"minAmount": 0.0005,
"baseCurrency": "btc",
"counterCurrency": "usdt"
}
}

Order book

List open buy and sell orders for a trading pair.

Method Endpoint URL Function Authentication
GET /public/order-book/{trading_pair}/ List open buy and sell orders No
Request
curl https://api.tokens.net/public/order-book/btcusdt/
Response
{
"status": "ok",
"timestamp": 1234567890,
"bids": [[
"0.01234",
"9500.12"
]],
"asks": [[
"0.01234",
"9501.12"
]]
}

Balance

Get trading account balance for all currencies with non-zero balance.

Method Endpoint URL Function Authentication
GET /private/balance/{currency}/ Account balance for selected currency Yes
Request
curl https://api.tokens.net/private/balance/btc/ \
-H "key:$key" -H "nonce:$nonce" -H "signature:$signature"
Response
{
"status": "ok",
"total": "0.12345678",
"currency": "BTC",
"available": "0.12345678"
"timestamp": 1234567890
}

Orders

List, add or cancel order in your trading account.

Method Endpoint URL Function Authentication
GET /private/orders/get/all/ List open orders for your account Yes
GET /private/orders/get/{id}/ List a single order for your account Yes
GET /private/orders/get/{trading_pair}/ List orders for your account for a trading pair Yes
POST /private/orders/add/limit/ Place an order Yes
POST /private/orders/cancel/{id}/ Cancel an order Yes

Place an order

This method takes the following POST parameters:

  1. tradingPair: name of trading pair, for example btcusdt
  2. side: buy or sell currency
  3. amount: amount of currency to trade, for example 1
  4. price: price of currency per unit, for example 2
  5. takeProfit (optional): automatically take profit when this price is reached, for example 3
  6. expireDate (optional): UNIX timestamp, at which the order should expire, for example 2147483647
Request
curl https://api.tokens.net/private/orders/add/limit/ \
-H "key:$key" -H "nonce:$nonce" -H "signature:$signature" -X POST --data \
"tradingPair=btcusdt&side=buy&amount=1&price=2&takeProfit=3&expireDate=2147483647"
Response
{
"status": "ok",
"orderId": "01234567-89ab-cdef-0123-456789abcdef",
"timestamp": 1234567890
}

Cancel an order

Request
curl https://api.tokens.net/private/orders/cancel/01234567-89ab-cdef-0123-456789abcdef/ \
-X POST -H "key:$key" -H "nonce:$nonce" -H "signature:$signature"
Response
{
"status": "ok",
"timestamp": 1234567890
}

Order details

Order status is returned in orderStatus property and can have the following values:

  • Open
  • Filled
  • Canceled
  • Expired
Request
curl https://api.tokens.net/private/orders/get/01234567-89ab-cdef-0123-456789abcdef/ \
-H "key:$key" -H "nonce:$nonce" -H "signature:$signature"
Response
{
"status": "ok",
"timestamp": 1234567890,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created": 1234567890,
"type": "buy",
"orderStatus": "Open",
"price": "1234.56",
"amount": "1234.56",
"remainingAmount": "1234.56",
"currencyPair": "btcusdt",
"takeProfit": "1234.56",
"trades": [{
"datetime": 1234567890,
"id": 1234567,
"type": "buy",
"price": "1234.56",
"amount": "1.00",
"value": "1234.56"
}]
}

List all orders

Request
curl https://api.tokens.net/private/orders/get/all/ \
-H "key:$key" -H "nonce:$nonce" -H "signature:$signature"
Response
{
"status": "ok",
"timestamp": 1234567890,
"openOrders": [{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created": 1234567890,
"type": "buy",
"price": "1234.56",
"amount": "1234.56",
"remainingAmount": "1234.56",
"currencyPair": "btcusdt",
"takeProfit": "1234.56"
}]
}

List orders by trading pair

Request
curl https://api.tokens.net/private/orders/get/btcusdt/ \
-H "key:$key" -H "nonce:$nonce" -H "signature:$signature"
Response
{
"status": "ok",
"timestamp": 1234567890,
"openOrders": [{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created": 1234567890,
"type": "buy",
"price": "1234.56",
"amount": "1234.56",
"remainingAmount": "1234.56",
"currencyPair": "btcusdt",
"takeProfit": "1234.56"
}]
}

Voting

List all currencies participating in voting and number of votes for each currency.

Method Endpoint URL Function Authentication
GET /public/voting/get/all/ List all currencies participating in voting No

List currencies

Winning currency status is returned in publishStatus property and can have the following values:

  • 0: currency will be added to exchange at unkown date
  • 1: currency will be added to exchange at known date, included in response
  • 2: currency has been added and trading is enabled
Request
curl https://api.tokens.net/public/voting/get/all/
Response
{
"status": ok,
"timestamp": 1234567890,
"votingEndDate": 1234567890,
"winnerList": [{
"currency": "XLM",
"currencyName": "Stellar",
"totalVotes": 10000,
"publishStatus": 2,
"winDate": 1234567890,
"addToMarketDate": 1234567890
}],
"activeList": [{
"currency": "ADA",
"currencyName": "Cardano",
"votes": 5000
}]
}