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)
  4. Go: TokensApi (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/all/ All tickers for last day No
GET /public/ticker/hour/{trading_pair}/ Ticker for last hour No
GET /public/ticker/hour/all/ All tickers for last hour 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/balance/all/ Account balance for all currencies Yes
GET /private/transactions/{page}/ List transactions 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/all/ All tickers for last day No
GET /public/ticker/hour/{trading_pair}/ Ticker for last hour No
GET /public/ticker/hour/all/ All tickers for last day 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"
}

You can also request all tickers at the same time to avoid multiple calls. Please note that this data might be a few seconds behind individual tickers.

Request
curl https://api.tokens.net/public/ticker/all/
Response
{
"status": ok,
"timestamp": 1234567890,
"btcusdt": {
"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 hour or day.

Method Endpoint URL Function Authentication
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/hour/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 available and total balance for a specific currency.

Method Endpoint URL Function Authentication
GET /private/balance/{currency}/ Account balance for selected currency Yes
GET /private/balance/all/ Account balance for all currencies 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
}

You can also request all balances at the same time to avoid multiple calls.

Request
curl https://api.tokens.net/private/balance/all/ \
-H "key:$key" -H "nonce:$nonce" -H "signature:$signature"
Response
{
"status": "ok",
"timestamp": 1234567890
"balances": {
"BTC": {
"total": "0.12345678",
"available": "0.12345678"
}
}
}

Transactions

Get information about trades, fees, account transfers, votes, withdrawals and deposits.

Method Endpoint URL Function Authentication
GET /private/transactions/{page}/ List transactions Yes

List transactions

Transaction list requires page number. Page number starts at 1 and each page contains 100 transactions. Transactions are listed in descending ID order (newest transactions are listed first).

Transaction type is returned in type property and can have the following values:

  • Deposit
  • Withdrawal
  • Withdrawal fee
  • Trade
  • Trading fee
  • Account transfer
  • Vote
Request
curl https://api.tokens.net/private/transactions/1/
Response
{
"status": ok,
"timestamp": 1234567890,
"page": 1,
"pages": 10,
"transactions": [{
"id": 123456789,
"datetime": 1234567890,
"type": "Trade",
"currency": "BTC",
"amount": "1.23456789"
}, {
"id": 123456788,
"datetime": 1234567890,
"type": "Trade",
"currency": "ETH",
"amount": "-12.34567890"
}]
}

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
}]
}