Help

Overview

This document provides a resource to use Tokenomy API v2 that is available at the API documentation page. The Tokenomy API v2 provides HTTP REST and WebSocket API.

Most of the API requires authentication, except for the market’s related REST API and public WebSocket.

In each APIs, we will provide an example using curl. The "…​" in the JSON response example indicates the response has been truncated.

General response

API v2 uses the HTTP status codes as an indication of success or error. A success response is represented by HTTP status code 200-226. An error response caused by the client (for example, invalid parameters) is represented by HTTP status codes 400-451, and an error caused by the server is represented by HTTP status code 500-511.

In API v2, all responses have a single format, encoded in JSON as,

{
    "code": <integer>,
    "message": <string>,
    "data": <JSON object | JSON array>
}

The code field contains an optional response status code, its value is equal to the HTTP status code. The message field contains additional information, it’s usually used for an error response. The data field contains a dynamic value, either as a JSON object or JSON array, as a response to a successful request.

Pair name

Pair name, or sometimes we write it as pair, is a combination of two assets separated by underscore character ("_"). The asset before underscore is called a coin asset and the asset after underscore is called a base asset. For example, a pair between Tokenomy (the coin asset) and Bitcoin (the base asset) is written as "ten_btc".

The information about valid pair names in Tokenomy platform can be viewed from the Market information public API.

Response schemas

This section contains a list of common objects that are returned by REST API or WebSocket.

Depth

Depth contains the total base and coin assets in open orders in the market, grouped by price.

Depth format,

{
    "amount": <string>,
    "price": <string>,
    "total_base": <string>,
    "total_coin": <string>,
}

amount: for buy order this is equal to total_base and for sell order this is equal to total_coin. This field is deprecated.

price: the current price that is open in the market.

total_base: total amount of base asset open in the market.

total_coin: total amount of coin asset open in the market.

Ticker

Ticker contains the prices and volume information about a specific pair.

{
    "pair": <string>,
    "ask": <string>,
    "bid": <string>,
    "high": <string>,
    "low": <string>,
    "last_price": <string>,
    "volume_base": <string>,
    "volume_coin": <string>
}

pair: The pair name.

ask: Contains the lowest sell price of the pair in the market.

bid: Contains the highest buy price of the pair in the market.

high: The highest price for 24 hours of rolling time.

low: The lowest price for 24 hours of rolling time.

last_price: The latest trade price for the pair.

volume_base: the amount of base asset has been traded since the last 24 hours rolling time.

volume_coin: the amount of coin asset has been traded since the last 24 hours rolling time.

Trade

Trade contains the information about single open order or closed order. Trade object format,

{
    "id": <numeric>,
    "pair": <string>,
    "type": <string>,
    "method": <string>,
    "status": <string>,
    "price": <string>,

    "base_asset": <string>,
    "base_amount": <string>,
    "base_filled": <string>,
    "base_remain": <string>,

    "coin_asset": <string>,
    "coin_amount": <string>,
    "coin_filled": <string>,
    "coin_remain": <string>,

    "submit_time": <numeric>,
    "finish_time": <numeric>,
}

id: Unique identifier for the trade object.

pair: The name of the pair being traded.

type: Type of trade, its either "sell" or "buy".

method: Method of trade, its either "limit" or "market".

status: Status of trade, its either empty "" (open), "filled" or "cancelled".

price: The price of base asset being traded.

base_asset: The name of base asset being traded.

base_amount: The total amount of base asset being traded.

base_filled: The amount of base asset that has been taken. If the status is filled the value is equal to base_amount. If the status is cancelled the value may be zero or less than base_amount.

base_remain: Remaining amount of base asset.

coin_asset: The name of coin being traded.

coin_amount: The total amount of coin being traded.

coin_filled: The total amount of coin that has been taken.

coin_remain: The remaining amount of coin.

submit_time: The Unix timestamp value when the order being placed on the market.

finish_time: The Unix timestamp value when the order has been completed or cancelled.

REST API public

The APIs for all market information is available publicly, without authentication.

Market depths

List the market depths for each pair.

Request

GET /v2/market/depths

Query parameters,

  • pair: Required, string. The pair’s name.

Response

Response format,

{
    "data": {
      "asks": [ Depth ],
      "bids": [ Depth ]
    }
}

See Depth schema for the format of Depth record.

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/market/depths?pair=ten_btc'
{
  "data": {
    "asks": [
      {
        "amount": "291.27303651",
        "price": "0.00000298"
        "total_base": "0.00086799",
        "total_coin": "291.27303651"
      },
      {
        "amount": "582.60758818",
        "price": "0.00000311"
        "total_base": "0.00181190",
        "total_coin": "582.60758818",
      },
      ...
    ],
    "bids": [
      {
        "amount": "653.12027491",
        "price": "0.00000291"
        "total_base": "653.12027491",
        "total_coin": "2.24439957",
      },
      {
        "amount": "1965.71034482",
        "price": "0.0000029"
        "total_base": "1965.71034482",
        "total_coin": "6.77831153",
      },
      ...
    ]
  }
}

Market information

Information about all the pairs in the platform.

Request

GET /v2/market/info

Response

Response format,

{
    "data": [ MarketInfo ]
}

MarketInfo format,

{
    "id": <string>,
    "symbol": <string>,
    "coin_asset": <string>,
    "base_asset": <string>,
    "is_active": <bool>,
    "amount_precision": <integer>,
    "amount_minimum": <string>,
    "price_precision": <integer>,
    "price_minimum": <string>
}

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/market/info'
{
  "data": [
    {
      "id": "bchabcbtc",
      "symbol": "bchabc_btc",
      "coin_asset": "bchabc",
      "base_asset": "btc",
      "is_active": true,
      "amount_precision": 6,
      "amount_minimum": "0.001",
      "price_precision": 6,
      "price_minimum": "0.0001"
    },
    {
      "id": "btcidk",
      "symbol": "btc_idk",
      "coin_asset": "btc",
      "base_asset": "idk",
      "is_active": true,
      "amount_precision": 8,
      "amount_minimum": "0.0000001",
      "price_precision": 8,
      "price_minimum": "1"
    },
    ...
  ]
}

Market trades open

List all open trades in the market specific to the pair’s name grouped by ask and bid.

Request

GET /v2/market/trades/open

Query parameters,

  • pair: Required, string. The name of the pair.

Response

Response format,

{
    "data": {
        "asks": [ Trade ],
        "bids": [ Trade ]
    }
}

The fields "asks" contain a list of open sell orders. The fields "bids" contain a list of open buy orders.

Example

$ curl --silent --location --request GET \
'https://api.tokenomy.com/v2/market/trades/open?pair=ten_btc'
{
  "data": {
    "asks": [
      {
        "id": 7374801,
        "pair": "ten_btc",
        "type": "sell",
        "method": "limit",
        "price": "0.00000298",
        "base_asset": "btc",
        "base_amount": "0.00086799",
        "base_filled": "0",
        "base_remain": "0.00086799",
        "coin_asset": "ten",
        "coin_amount": "291.27303651",
        "coin_filled": "0",
        "coin_remain": "291.27303651",
        "submit_time": 1593914091
      },
      ...
    ]
    "bids": [
      {
        "id": 7369886,
        "pair": "ten_btc",
        "type": "buy",
        "method": "limit",
        "price": "0.00000291",
        "base_asset": "btc",
        "base_amount": "0.00190058",
        "base_filled": "0",
        "base_remain": "0.00190058",
        "coin_asset": "ten",
        "coin_amount": "653.12027491",
        "coin_filled": "0",
        "coin_remain": "653.12027491",
        "submit_time": 1593885276
      },
      ...
    ]
  }
}

Market prices

List the latest traded pair’s prices in the market.

Request

GET /v2/market/prices

Response

Data format,

{
    "data": {
        "<PairName>": <string>,
        ...
    }
}

The PairName is using the "<coin>_<base>" format.

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/market/prices'
{
  "data": {
    "bchabc_btc": "0.025163",
    "btc_idk": "133800",
    "btc_usdt": "9252.35",
    "comp_idk": "2765.63072",
    "dai_idk": "14.9",
    "eos_btc": "0.0002756",
    "etc_btc": "0.000632",
    "eth_btc": "0.025584",
    "eth_usdt": "236.71",
    "idk_usdt": "0.06896076",
    "lrc_btc": "0.001",
    "ltc_btc": "0.004661",
    "mkr_idk": "6814.363",
    "ont_btc": "0.000066",
    "scc_idk": "0.0001",
    "six_btc": "1",
    "swipe_btc": "0.0000005",
    "ten_btc": "0.00000296",
    "ten_idk": "0.388",
    "ten_usdt": "0.02962306",
    "trx_btc": "0.00000193",
    "usdt_idk": "14.501",
    "vex_btc": "0.001",
    "xlm_btc": "0.00000766",
    "xmr_btc": "0.006943",
    "zec_btc": "0.005829"
  }
}

Market summaries

Fetch ticker information for all pairs, prices since the 24 hours ago, and prices since 7 days ago.

Request

GET /v2/market/summaries

Response

Response format,

{
    "data": {
        "prices": PairPrice,
        "prices_changes": PairChanges,
        "prices_24h": PairPriceSince24h,
        "prices_7d": PairPriceSince7d,
        "tickers": PairTicker
    }
}

The PairTicker is mapping between pair’s name and its Ticker information in the following format,

{
    "<PairName>": <Ticker>
}

The PairPrice contains mapping of pair name and its latest traded price.

The PairChanges contains mapping of pair name and percentage of price changes between latest price and past price 24 hours ago.

The PairPriceSince24h contains mapping of pair name and its last traded price since 24 hours ago, using the following format,

{
    "<PairName>": <string>
}

The PairPriceSince7d contains mapping of pair name and its last traded price since 7 days ago, in the following format,

{
    "<PairName>": <string>
}

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/market/summaries'
{
  "data": {
    "prices": {
      "bchabc_btc": "0.024657",
      "btc_idk": "132889",
      "btc_usdt": "9131",
      ...
    },
    "prices_24h": {
      "bchabc_btc": "0.024657",
      "btc_idk": "132889",
      "btc_usdt": "9131",
      ...
    },
    "prices_7d": {
      "bchabc_btc": "0.024387",
      "btc_idk": "132650",
      "btc_usdt": "9133",
      ...
    },
    "prices_changes": {
      "bchabc_btc": "0.1",
      "btc_idk": "-0.1",
      "btc_usdt": "0",
    },
    "tickers": {
      "bchabc_btc": {
        "pair": "bchabc_btc",
        "bid": "0.025001",
        "ask": "0.025318",
        "high": "0.025258",
        "low": "0.024593",
        "last_price": "0.025163",
        "volume_base": "68.08951",
        "volume_coin": "2741"
      },
      "btc_idk": {
        "pair": "btc_idk",
        "bid": "130651.730649",
        "ask": "137924.59",
        "high": "133989",
        "low": "132233",
        "last_price": "133800",
        "volume_base": "3328338.08150079",
        "volume_coin": "25.00036757"
      },
      ...
    }
  }
}

Market ticker

Fetch the pair information related to prices including sell, buy, highest, lowest, last price, and the volume of base and coin assets.

Request

GET /v2/market/ticker

Query parameters,

  • pair: Required, string. The name of the pair in "<coin>_<base>" format.

Response

The response in the data field returned as Ticker.

{
    "data": <Ticker>
}

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/market/ticker?pair=ten_btc'
{
  "data": {
    "pair": "ten_btc",
    "bid": "0.00000291",
    "ask": "0.00000298",
    "high": "0.00000296",
    "low": "0.00000296",
    "last_price": "0.00000296",
    "volume_base": "7.94120474",
    "volume_coin": "2682839.43918805"
  }
}

Market trades closed

List all completed trades in the market by specific pair.

Request

GET /v2/market/trades

Query parameters,

  • pair: Required, string. The name of the pair in the format "<coin>_<base>".

  • offset: Optional, number. The number of records to be skipped, default to 0.

  • limit: Optional, number. The limit of records to be fetched, default to 100.

Response

Data format,

{
    "data": {
        "asks": [ <Trade> ],
        "bids": [ <Trade> ]
    }
}

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/market/trades?pair=ten_btc&limit=4'
{
  "data": {
    "asks": [
      {
        "id": 1044337,
        "pair": "ten_btc",
        "type": "sell",
        "price": "0.00000296",
        "base_asset": "btc",
        "base_amount": "0.05433306",
        "coin_asset": "ten",
        "coin_amount": "18355.76351351",
        "finish_time": 1594041529
      },
      ...
    ],
    "bids": [
      {
         "id": 1044372,
         "pair": "ten_btc",
         "type": "buy",
         "price": "0.00000296",
         "base_asset": "btc",
         "base_amount": "0.03145598",
         "coin_asset": "ten",
         "coin_amount": "10627.02027027",
         "finish_time": 1594042102
      },
      ...
    ]
  }
}

REST API private

Authentication

REST API private requires authentication using API and Secret keys. Both of those keys can be obtained through Trade API. The API key must be sent along with the request inside the custom HTTP header Key value. The Secret key is used to compute HMAC-SHA512 of the request’s query (when using the HTTP GET or DELETE method) or request’s body (when using the POST or PUT method), which then encoded using hexadecimal. The result then sent inside the custom HTTP header Sign value.

For request using HTTP POST and parameters in the body, the request header must set the Content-Type value to application/x-www-form-urlencoded.

All requests must include a timestamp field that contains the value of the current Unix timestamp in seconds. The request will be rejected if the timestamp value is different 8 seconds with the server time. So, make sure your client operating system sync their time with the nearest time server.

For example, let’s say that we have API key XYZ and Secret key secr3t, and we want to get our trade history for pair ten_btc. The query string would be: timestamp=1574423788&pair=ten_btc. First, we compute the HMAC-SHA512 of query string using the Secret key,

hash := HMAC_SHA512("timestamp=1574423788&pair=ten_btc", "secr3t")

Then we encode the resulting hash in hexadecimal,

sign := HEX(hash)
// sign is equal to
// "db068236b2cbc0084946de7be9dce15f2ac271ddae83e6d9181f25b397d09f10d128f4e710dbf1aa7b15c13bb2032b9673d549829e7455fe3ef0ddb95a0dc1a5"

Finally we can send the GET request to API trade history using the Key and Sign header,

GET /v2/user/trades?timestamp=1574423788&pair=ten_btc HTTP/1.1
Accept: application/json
Key: XYZ
Sign: db068236b2cbc0084946de7be9dce15f2ac271ddae83e6d9181f25b397d09f10d128f4e710dbf1aa7b15c13bb2032b9673d549829e7455fe3ef0ddb95a0dc1a5

Another example of request using HTTP POST,

POST /v2/trade/cancel/ask HTTP/1.1
Accept: application/json
Content-type: application/x-www-form-urlencoded
Key: XYZ
Sign: 0788a57e33fb2d683e2df9051653794adb132cf88b70482c46d9ae9598b589742babcecdd9ce367375a84862286cbf77d839c8b3ba4d9676f7713673e51016a1

timestamp=1574423788&pair=ten_btc&trade_id=1

User information

Information about a user on the platform.

Request

GET /v2/user/info
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Query parameter,

  • timestamp: Required, integer. Unix timestamp when the request is made.

Response

Response format,

{
    "data": {
        "id": <integer>,
        "email": <string>,
        "full_name": <string>,
        "notifications": <Notifications>,
        "wallets": <UserWallets>,
        "balances": <UserBalances>,
        "frozen_balances": <UserFrozenBalances>
    }
}

Notifications format,

{
    "deposit": <boolean>,
    "login": <boolean>,
    "trade": <boolean>,
    "withdraw": <boolean>
}

UserWallets format,

{
    "<asset_name>": "<Address> (<Memo>)",
    ...
}

UserBalances format,

{
    "<AssetName>": <string>,
    ...
}

UserFrozenBalances format,

{
    "<FrozenAssetName>": <string>,
    ...
}

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/user/info?timestamp=1593593507187' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header "Key: ${TOKENOMY_API_KEY}" \
    --header "Sign: ${TOKENOMY_SIGN}"
{
  "data": {
    "id": 1,
    "email": "[email protected]",
    "full_name": "Your Name",
    "notifications": {
      "deposit": true,
      "login": false,
      "trade": true,
      "withdraw": true
    },
    "wallets": {
      "bnb": "bnb1u8tv2fpcd3fz7yn9jcpqr2vd5suhpx6gyx54n7 (Memo 114)",
      "eos": "tokexaccount (Memo 114)",
      "eth": "0xb1b26bf16dc831208dbc703206579f81b6262767",
      "hnst": "bnb1u8tv2fpcd3fz7yn9jcpqr2vd5suhpx6gyx54n7 (Memo 114)",
      "lyfebep": "bnb1u8tv2fpcd3fz7yn9jcpqr2vd5suhpx6gyx54n7 (Memo 114)",
      "six": "GC3UVRVE54GJ45YTOPPYI4TTH2ZN4CZLVIHZNJ5PR5GP54IF6B5KEY5B (Memo 114)",
      "swipe": "bnb1u8tv2fpcd3fz7yn9jcpqr2vd5suhpx6gyx54n7 (Memo 114)",
      "vex": "tokenomyvexa (Memo 114)",
      "xlm": "GC3UVRVE54GJ45YTOPPYI4TTH2ZN4CZLVIHZNJ5PR5GP54IF6B5KEY5B (Memo 114)"
    },
    "balances": {
      "btc": "9.99334615",
      "ten": "8862.94108891"
    },
    "frozen_balances": {
      "btc": "0.00032856",
      "ten": "16.50000001"
    }
  }
}

User trades history

This API return list of user’s trades either as taker or maker, sorted by trade ID in descending order.

Request

GET /v2/user/trades
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Query parameters,

  • timestamp: Required, integer. The time when the request is made.

  • pair: Required, string. The name of the pair in the format "<coin>_<base>".

  • offset: Optional, integer. The number of records to be skipped.

  • limit: Optional, integer. The maximum number of records to be fetched.

  • id_after: Optional, integer. Filter records with ID are greater or equal than its value.

  • id_before: Optional, integer. Filter records with ID are equal or less than its value.

  • time_after: Optional, integer. Filter records with trade’s time are after its value.

  • time_before: Optional, integer. Filter records with trade’s time are before its value.

Response

The API will return array of Trade,

{
    "data": [ Trade ]
}

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/user/trades?pair=ten_btc&timestamp=1594011524823' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header "Key: ${TOKENOMY_API_KEY}" \
    --header "Sign: ${TOKENOMY_SIGN}"
{
  "data": [
    {
      "id": 7298795,
      "type": "buy",
      "method": "bid",
      "price": "0.00000297",
      "base_asset": "btc",
      "base_amount": "0.00002451",
      "coin_asset": "ten",
      "coin_amount": "8.25252525",
      "finish_time": 1593503606
    },
    ...
  ]
}

User orders history

List of user trades that have been completed or canceled.

Request

GET /v2/user/orders/closed HTTP/1.1
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Query parameters,

  • timestamp: Required, integer. Unix timestamp when requests being made.

  • pair: Required, string. The name of the pair in the format "<coin>_<base>".

  • time_after: Unix timestamp to filter only orders that have been submitted after the time. Optional, default to current timestamp if not set.

  • time_before: Unix timestamp to filter only orders that have been submitted before the time. Optional, default to timeAfter minus 1 hour.

Response

It will return array of Trade,

{
    "data": [ *Trade ]
}

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/user/orders/closed?pair=ten_btc&timestamp=1594011524823' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header "Key: ${TOKENOMY_API_KEY}" \
    --header "Sign: ${TOKENOMY_SIGN}"
{
  "data": [
    {
       "id": 7392253,
       "pair": "ten_btc",
       "type": "buy",
       "method": "limit",
       "status": "cancelled",
       "price": "0.00000253",
       "base_asset": "btc",
       "base_amount": "0.0000253",
       "base_filled": "0",
       "base_remain": "0.0000253",
       "coin_asset": "ten",
       "coin_amount": "10",
       "coin_filled": "0",
       "coin_remain": "10",
       "submit_time": 1594012679,
       "finish_time": 1594012850
    },
    ...
  ]
}
//{{{ user orders open

User open orders

List of user orders that still open in the market.

Request

GET /v2/user/orders/open
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Query parameters,

  • timestamp: Required, integer. Unix timestamp when requests being made.

  • pair: Optional, string. The name of the pair in the format "<coin>_<base>".

Response

Response format,

{
    "data": {
        "<pairName>": {
            "asks": [ *Trade ],
            "bids": [ *Trade ]
        }
    }
}

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/user/orders/open?pair=ten_btc&limit=2&timestamp=1594011877171' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header "Key: ${TOKENOMY_API_KEY}" \
    --header "Sign: ${TOKENOMY_SIGN}"
{
  "data": {
    "ten_btc": {
      "asks": [],
      "bids": [
        {
           "id": 7301082,
           "pair": "ten_btc",
           "type": "buy",
           "method": "limit",
           "price": "0.00000238",
           "base_asset": "btc",
           "base_amount": "0.00002856",
           "base_filled": "0",
           "base_remain": "0.00002856",
           "coin_asset": "ten",
           "coin_amount": "12",
           "coin_filled": "0",
           "coin_remain": "12",
           "submit_time": 1593517391
        }
      ]
    }
  }
}
//{{{ user order information

User order information

Get a single order (open) or trade (closed) information based on the pair name and trade ID.

Request

GET /v2/user/order
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Query parameters,

  • timestamp: Required, integer. Unix timestamp when requests being made.

  • pair: Required, string. The name of the pair in the format "<coin>_<base>".

  • trade_id: Required, integer. The ID of trade to be fetched.

Response

It will return a single Trade record,

{
    "data": <Trade>
}

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/user/order?pair=ten_btc&trade_id=7301082&timestamp=1594012140860' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header "Key: ${TOKENOMY_API_KEY}" \
    --header "Sign: ${TOKENOMY_SIGN}"
{
  "data": {
    "id": 7301082,
    "pair": "ten_btc",
    "type": "buy",
    "method": "limit",
    "price": "0.00000238",
    "base_asset": "btc",
    "base_amount": "0.00002856",
    "base_filled": "0",
    "base_remain": "0.00002856",
    "coin_asset": "ten",
    "coin_amount": "12",
    "coin_filled": "0",
    "coin_remain": "12",
    "submit_time": 1593517391
  }
}

User transaction history

List the user’s deposit and withdrawal transactions.

Request

GET /v2/user/transactions
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Query parameters,

  • timestamp: Required, integer. Unix timestamp when requests being made.

  • asset: Optional, string. The name of the asset, if it is empty all asset’s history will be returned.

  • offset: Optional, number. The number of records to be skipped, default to 0.

  • limit: Optional, number. Maximum of records returned by the server.

Response

Response format,

{
    "data": {
        "deposit": {
            "<AssetName>": <Deposit>
        },
        "withdraw": {
            "<AssetName>": <Withdraw>
        }
    }
}

Format of Deposit,

{
    "id": <number>,
    "status": <string>,
    "amount": <string>,
    "final_amount": <string>,
    "success_time": <timestamp>
}

Format of Withdraw,

{
    "id": <number>,
    "status": <string>,
    "amount": <string>,
    "fee": <string>,
    "final_amount": <string>,
    "submit_time": <timestamp>,
    "success_time": <timestamp>
}

Example

$ curl --silent --location --request GET \
    'https://api.tokenomy.com/v2/user/transactions?timestamp=1594012296443' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header "Key: ${TOKENOMY_API_KEY}" \
    --header "Sign: ${TOKENOMY_SIGN}"
{
    "data": {
        "deposit": {
            "btc": [{
                "id": 1,
                "status": "success",
                "amount": "1.3",
                "final_amount": "1.3",
                "success_time": 1570423386
            }]
        },
        "withdraw": {
            "btc": [{
                "id": 1,
                "status": "success",
                "amount": "0.1",
                "fee": "0.0003",
                "final_amount": "0.0997",
                "submit_time": 1570423386,
                "success_time": 1570423806
            }]
        }
    }
}

Withdraw asset

Transfer the asset from Tokenomy to an external account or other exchange.

This method requires "withdraw" permission to be enabled and a non-empty Callback URL when you generate the API key.

The callback URL is an endpoint that will be called by our system to verify the withdrawal request. Some parameters in the request will be forwarded to the Callback URL, so please check this information in your system. If all the request parameters are valid, the Callback URL should respond with HTTP status code 200 and print out a string “ok” (without quotes). We will continue the withdraw process only if we receive an HTTP status code 200 response, otherwise, the withdrawal request will be canceled.

Request

POST /v2/user/withdraw
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Parameters in the body,

  • timestamp: Required, integer. Unix timestamp when requests being made.

  • request_id: Required, string. Custom string to identify each withdrawal request. The request_id will be passed to the Callback URL to allow the receiver to identify the withdrawal request. The request_id must be less than 255 characters and only contains alphanumeric characters.

  • asset: Required, string. The name of the asset to be withdrawn.

  • address: Required, string. Receiver address.

  • amount: Required, float. Amount to be withdrawn.

  • memo: Optional (depends on the receiver), string. Memo to be sent to the receiver address. Some exchanges use a memo to accept deposits for certain assets. For example, on Ripple the memo value is custom Destination Tag, on NXT the memo value is custom Message, in BitShares the memo value is custom Memo.

Response

Data format,

{
    "data": {
        "id": <number>,
        "request_id": <string>,
        "requester_ip": <string>,
        "status": <string>,
        "asset": <string>,
        "address": <string>,
        "memo": <string>,
        "amount": <string>,
        "fee": <string>,
        "final_amount": <string>,
        "submit_time": <number>,
        "success_time": <number>
    }
}
  • id: the unique identifier of withdraw request in the system

  • request_id: the unique identifier from the request

  • requester_ip: the IP address of the client

  • status: status of withdrawing, its either "success" or "fail".

  • asset: the name of the asset, the same with the request.

  • address: receiver address, same with the request.

  • memo: memo in the request.

  • amount: the amount of withdrawing, same with the request.

  • fee: the withdrawal fee.

  • final_amount: the total withdrawal amount after subtracted with the fee.

  • submit_time: the time when withdraw requested.

  • success_time: the time when withdraw requested approved.

Trade ask

Open a sell order for a coin asset at a specific amount and price to market.

For example, given a pair "ten_btc" with amount "5" and price "0.0001" means user want to sell 5 TEN at the price 0.0001 BTC.

Request

POST /v2/trade/ask
Content-type: application/x-www-form-urlencoded
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Parameters in the body,

  • timestamp: Required, integer. Unix timestamp when requests being made.

  • pair: Required, string. The name of the pair to be traded.

  • trade_method: Optional, string, The method of trade, its either "limit" or "market", default to "limit" if it’s empty.

  • amount: Required, float. The amount of coin to sell.

  • price: Required, float. The price of the coin to sell.

  • post_only: Optional, boolean. This parameter only applicable when trade_method is "limit". If its value is true, the request will succeed only if no matches in the market; otherwise it will return an error.

  • time_in_force: Optional, string. This parameter only applicable if trade_method is "limit". This parameter may change the behaviour of order "limit" processed by broker. Currently, the valid values are empty "" (default) or "FOK" (fill-or-kill).

    If the value is empty, the order request processed normally as "limit" request.

    If the value is "FOK", the order will be success only if only all of requested amount is fulfilled, otherwise it will return as an error.

Response

Response format,

{
    "data": {
        "order": <Trade>,
        "trades": [ Trade ],
        "user": User
    }
}

Example

$ curl --silent --location --request POST \
    'https://api.tokenomy.com/v2/trade/ask' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header "Key: ${TOKENOMY_API_KEY}" \
    --header "Sign: ${TOKENOMY_SIGN}" \
    --data-raw 'pair=ten_btc&amount=10&price=0.00000364&trade_method=limit&timestamp=1594012404298'
{
    "code": 200,
    "data": {
        "order": {
            "id": 7392222,
            "pair": "ten_btc",
            "type": "sell",
            "method": "limit",
            "price": "0.00000364",
            "base_asset": "btc",
            "base_amount": "0.0000364",
            "base_filled": 0,
            "base_remain": "0.0000364",
            "coin_asset": "ten",
            "coin_amount": "10",
            "coin_filled": "0",
            "coin_remain": "10",
            "submit_time": 1594012404
        },
        "trades": [],
        "user": {
            "id": 114,
            "email": "[email protected]",
            "full_name": "Your Name",
            "balances": {
                "btc": "9.99334615",
                "ten": "8852.94108891"
            },
            "frozen_balances": {
                "btc": "0.00032856",
                "ten": "26.50000001"
            }
        }
    }
}

Trade bid

Request

POST /v2/trade/bid
Content-type: application/x-www-form-urlencoded
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Parameters in the body,

  • timestamp: Required, integer. Unix timestamp when requests being made.

  • pair: Required, string. The name of the pair to be traded.

  • trade_method: Optional, string, The method of trade, its either "limit" or "market", default to "limit" if it is empty.

  • amount: Required, float. The amount of coin to buy.

  • price: Required, float. The price of the coin to buy.

  • post_only: Optional, boolean. This parameter only applicable when trade_method is "limit". If its value is true, the request will succeed only if no matches in the market; otherwise it will return an error.

  • time_in_force: Optional, string. This parameter only applicable if Method is "limit". This option may change the behaviour of order "limit" processed by broker. Currently, the valid values are empty "" (default) or "FOK" (fill-or-kill).

    If the value is empty, the order request processed normally as "limit" request.

    If the value is "FOK", the order will be success only if only all of requested amount is fulfilled, otherwise it will return as an error.

Response

Response format,

{
    "data": {
        "order": <Trade>,
        "trades": [ Trade ],
        "user": User
    }
}

Example

$ curl --silent --location --request POST \
    'https://api.tokenomy.com/v2/trade/bid' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header "Key: ${TOKENOMY_API_KEY}" \
    --header "Sign: ${TOKENOMY_SIGN}" \
    --data-raw 'pair=ten_btc&amount=10&price=0.00000253&trade_method=limit&timestamp=1594012679192'
{
    "code": 200,
    "data": {
        "order": {
            "id": 7392253,
            "pair": "ten_btc",
            "type": "buy",
            "method": "limit",
            "price": "0.00000253",
            "base_asset": "btc",
            "base_amount": "0.0000253",
            "base_filled": "0",
            "base_remain": "0.0000253",
            "coin_asset": "ten",
            "coin_amount": "10",
            "coin_filled": "0",
            "coin_remain": "10",
            "submit_time": 1594012679
        },
        "trades": [],
        "user": {
            "id": 114,
            "email": "[email protected]",
            "full_name": "Your Name",
            "balances": {
                "btc": "9.99332085",
                "ten": "8862.94108891"
            },
            "frozen_balances": {
                "btc": "0.00035386",
                "ten": "16.50000001"
            }
        }
    }
}

Cancel all open orders

This API cancels all open asks and bids orders.

Request

DELETE /v2/trade/cancel/all?timestamp=<timestamp>
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Parameters in the query,

  • timestamp: Required, integer. Unix timestamp when requests being made.

Response

It will return all orders that has been canceled as an array,

{
    "message": <string>,
    "data": [ *<Trade> ]
}

Trade cancel ask

Request

DELETE /v2/trade/cancel/ask
Content-type: application/x-www-form-urlencoded
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Parameters in the query,

  • timestamp: Required, integer. Unix timestamp when requests being made.

  • pair: Required, string. The name of the pair to be canceled.

  • trade_id: Required, number. The ID of trade to be canceled.

Response

Data format,

{
    "message": <string>,
    "data": {
        "order": <Trade>,
        "trades": [ Trade ],
        "user": User
    }
}

Example

$ curl --silent --location --request DELETE \
    'https://api.tokenomy.com/v2/trade/cancel/ask?pair=ten_btc&trade_id=7392222&timestamp=1594012556407' \
    --header "Key: ${TOKENOMY_API_KEY}" \
    --header "Sign: ${TOKENOMY_SIGN}" \
    --header 'Content-Type: application/x-www-form-urlencoded'
{
    "code": 200,
    "message": "trade ask 7392222 cancelled",
    "name": "TRADE_ASK_CANCELLED",
    "data": {
        "order": {
            "id": 7392222,
            "pair": "ten_btc",
            "type": "sell",
            "method": "limit",
            "status": "cancelled",
            "price": "0.00000364",
            "base_asset": "btc",
            "base_amount": "0.0000364",
            "base_filled": "0",
            "base_remain": "0.0000364",
            "coin_asset": "ten",
            "coin_amount": "10",
            "coin_filled": "0",
            "coin_remain": "10",
            "submit_time": 1594012404,
            "finish_time": 1594012556
        },
        "trades": [],
        "user": {
            "id": 114,
            "email": "[email protected]",
            "full_name": "Your Name",
            "balances": {
                "btc": "9.99334615",
                "ten": "8862.94108891"
            },
            "frozen_balances": {
                "btc": "0.00032856",
                "ten": "16.50000001"
            }
        }
    }
}

Trade cancel bid

Request

DELETE /v2/trade/cancel/bid
Content-type: application/x-www-form-urlencoded
Sign: <Body signature using HMAC-SHA512>
Key: <API key>

Parameters in the query,

  • timestamp: Required, integer. Unix timestamp when requests being made.

  • pair: Required, string. The name of the pair to be canceled.

  • trade_id: Required, number. The ID of trade to be canceled.

Response

Data format,

{
    "message": <string>,
    "data": {
        "order": <Trade>,
        "trades": [ Trade ],
        "user": User
    }
}

Example

$ curl --silent --location --request DELETE \
    'https://api.tokenomy.com/v2/trade/cancel/bid?pair=ten_btc&trade_id=7392253&timestamp=1594012850806' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header "Key: ${TOKENOMY_API_KEY}" \
    --header "Sign: ${TOKENOMY_SIGN}"
{
    "code": 200,
    "message": "trade bid 7392253 cancelled",
    "name": "TRADE_BID_CANCELLED",
    "data": {
        "order": {
            "id": 7392253,
            "pair": "ten_btc",
            "type": "buy",
            "method": "limit",
            "status": "cancelled",
            "price": "0.00000253",
            "base_asset": "btc",
            "base_amount": "0.0000253",
            "base_filled": "0",
            "base_remain": "0.0000253",
            "coin_asset": "ten",
            "coin_amount": "10",
            "coin_filled": "0",
            "coin_remain": "10",
            "submit_time": 1594012679,
            "finish_time": 1594012850
        },
        "trades": [],
        "user": {
            "id": 114,
            "email": "[email protected]",
            "full_name": "Your Name",
            "balances": {
                "btc": "9.99334615",
                "ten": "8862.94108891"
            },
            "frozen_balances": {
                "btc": "0.00032856",
                "ten": "16.50000001"
            }
        }
    }
}

WebSocket

Tokenomy API v2 provides two WebSocket endpoints, one is for public consumption and another one is for private, registered account only.

Message Format

All messages between client and server must be sent using WebSocket TEXT operation code (0x02) and encoded using JSON.

Request schema

The WebSocket request mimic the HTTP request as JSON object,

{
    "id": <number>,
    "method": <string>,
    "target": <string>,
    "body": <JSON encoded with base64>
}

The id field must be unique between requests. The recommended value is using Unix timestamp in milliseconds. If a client sent two requests with the same ID, the server will still process it but the client may receive an unexpected response.

The method field is equal to one of the HTTP methods: GET, POST, PUT, or DELETE.

The target field contains the API to be called on the server, its equal to the path in REST API.

The body field may contain JSON encoded with base64 that as an argument to "target".

Response schema

The WebSocket response message is represented by the following JSON object,

{
    "id": <numeric>,
    "code": <numeric>,
    "message": <string>,
    "body": <base64 JSON encoded string>
}

There are two modes of response that the client will receive: normal mode and broadcast mode. In the normal mode, the response is a reply from the request. In broadcast mode, the response is a message from the server after the client successfully connected to the server.

In normal mode, the id field will be set to the id in the client request. In broadcast mode, the id is zero.

In normal mode, the code field is equal to the HTTP response, 200 for successful request, 4xx client error, or 5xx for server error. In broadcast mode, its value is zero.

In normal mode, the message field will be set to success or error message in a single line. In broadcast mode, its value is equal to the topic that sends the message.

In normal mode, the body field will contain any data requested by the client. In broadcast mode, its value is equal to data sent by the topic’s publisher.

WebSocket public

This WebSocket API does not require authentication.

The client can open a new public WebSocket connection through /v2/ws endpoint.

Market depths

List the market depths for each pair.

  • Method: GET

  • Target: /v2/market/depths

  • Parameters:

    • pair: Required, string; the name of pair

Example,

{
    "id": 1,
    "method": "GET",
    "target": "/v2/market/depths",
    "body": "eyJwYWlyIjoidGVuX2J0YyJ9" // Equal to {"pair":"ten_btc"}"
}

Market prices

Get the latest market price for all pairs.

  • Method: GET

  • Target: /v2/market/prices

Example,

{
    "id": 1,
    "method": "GET",
    "target": "/v2/market/prices",
}

Market trades

List all completed trades in the market by specific pair.

  • Method: GET

  • Target: /v2/market/trades

  • Parameters:

    • pair: Required, string. The name of the pair using "<coin>_<base>" format.

    • offset: Optional, number. The number of records to be skipped, default to 0.

    • limit: Optional, number. The number of records to be fetched, default to 100.

Example

{
    "id": 1,
    "method": "GET",
    "target": "/v2/market/trades",
    "body": "eyJwYWlyIjoidGVuX2J0YyJ9" // Equal to {"pair":"ten_btc"}"
}

Market ticker

Fetch the pair information related to prices including sell, buy, highest, lowest, and the last price, also and volume of base and coin.

  • Method: GET

  • Target: /v2/market/ticker

  • Parameters:

    • pair: Required, string. The name of the pair in the format "<coin>_<base>".

Example,

{
    "id": 1,
    "method": "GET",
    "target": "/v2/market/ticker",
    "body": "eyJwYWlyIjoidGVuX2J0YyJ9" // Equal to {"pair":"ten_btc"}"
}

Subscription

Subscription is an API that allows clients to be notified when servers have new value on a specific topic. For example, instead of calling "/v2/market/depths" with parameter pair "ten_btc" every 10 seconds, clients can subscribe to the topic "depths" and when servers have a new depths value for "ten_btc" they will send it to the client connection immediately.

Available topics and its value for subscription APIs,

trades

The subscription value is list of pair, for example ["ten_btc", "eth_btc"]. This topic will broadcast latest open order and closed orders for the subscribed pairs.

summaries

The subscription value is boolean true or false. This topic will broadcast the market information on all active pairs, including latest prices, price past 24 hours ago, and tickers.

List subscription

An API to get a list of client subscriptions on the server.

Request

{
    "id": <timestamp>,
    "method": "GET",
    "target": "/v2/ws/subscription"
}

Response

On success, it will return a list of key-value of the topic and its pair.

{
    "<topic>": [ *<PairName> ]
}

Example

Assume that client has subscribe to topic "depth" and "trades" on pair "ten_btc"; given the following request,

{
    "id": 1,
    "method": "GET",
    "target": "/v2/ws/subscription"
}

It will return the following response,

{
    "id": 1,
    "code": 200,
    "body":
    "ewogICAgICAgICJkZXB0aCI6IFsidGVuX2J0YyIsICJldGhfYnRjIl0sCiAgICAgICAgInRyYWRlcyI6IFsidGVuX2J0YyJdLAogICAgICAgICJ0aWNrZXIiOiBbXQp9"
}

The body when decoded using base64 will result in

{
    "trades": ["ten_btc"],
}

Subscribe

Subscribe to a specific topic by pair names.

Multiple calls on this endpoint will not clear previously subscribed pairs. For example, if the first call subscribed to the topic "trades" with pair "X" and the second call subscribed to the topic "trades" but different pair "Y", the client has two subscriptions: "X" and "Y", NOT "Y".

Request

The subscribe parameter is a JSON object with key as topic and list of pairs in values.

{
    "id": <timestamp>,
    "method": "PUT",
    "target": "/v2/ws/subscription",
    "body": <base64>{
        "<topic>": [ <boolean> | *<PairName> ]
    }

For example, if we want to be notified when there is a new open order on pair TEN_BTC,

{
    "id": ,
    "method": "PUT",
    "target": "/v2/ws/subscription",
    "body": "eyJ0cmFkZXMiOlsidGVuX2J0YyJdfQ=="
}

The body base64 is equal to,

{"trades":["ten_btc"]}

Response

On success it will return list of subscription.

Unsubscribe

The API to unsubscribe from specific topics by pair name or boolean value.

Request

The unsubscribe parameters is JSON object with key as topic and list of pairs in values.

{
    "id": <timestamp>,
    "method": "DELETE",
    "target": "/v2/ws/subscription",
    "body": base64{
        "<topic>": [ <boolean> | *<PairName> ]
    }
}

Response

On success, it will return a list of subscriptions.

Broadcast notifications

Once the client has subscribed to specific topics and pairs, they will receive a broadcast message related to those topics.

For the topic "trades" client will receive two message types

  • open order with message field value "/v2/market/trades/open", and

{
    "id": 0,
    "message": "/v2/market/trades/open",
    "body": base64<Trade>
}
  • closed or canceled order with message field value "/v2/market/trades"

{
    "id": 0,
    "message": "/v2/market/trades",
    "body": base64<Trade>
}

WebSocket private

This WebSocket API requires authentication.

Authentication

The client opens a new private WebSocket connection on /v2/user/ws bypassing the API key and signature of the timestamp.

Example of WebSocket handshake request,

GET /v2/user/ws?timestamp=1574423788 HTTP/1.1
Host: tokenomy.com
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Key: (24 chars of generated keys)
Sec-WebSocket-Version: 13
Key: XYZ
Sign: db068236b2cbc0084946de7be9dce15f2ac271ddae83e6d9181f25b397d09f10d128f4e710dbf1aa7b15c13bb2032b9673d549829e7455fe3ef0ddb95a0dc1a5

Once the connection has been established and the Key and Sign key is validated, user can send the request as described below.

User Information

Get information about the user on the platform.

  • Method: GET

  • Target: /v2/user/info

  • Parameters: -

The response format is equal to UserInfo schema in REST API User Information.

Example of request in JSON format,

{
    "id": 1587701148,
    "method": "GET",
    "target": "/v2/user/info",
    "body": ""
}

User order information

Get single order information based on pair name and trade ID.

  • Method: GET

  • Target: /v2/user/order

  • Parameters,

    • pair: Required, string. The name of the pair in the format "<coin>_<base>".

    • trade_id: Required, integer. The ID of order to be fetched.

The response format is equal to Trade in REST API Trade data.

Example of request in JSON format,

{
    "id": 1587701148,
    "method": "GET",
    "target": "/v2/user/order",
    "body": "eyJwYWlyIjoidGVuX2J0YyIsInRyYWRlX2lkIjoxMH0=" // Equal to {"pair":"ten_btc","trade_id":10}
}

User open trades

List the current user’s trades that still open on the market.

  • Method: GET

  • Target: /v2/user/orders/open

  • Parameters:

    • pair: string, required; the name of pair

Example of request in JSON format,

{
    "id": 1587701148,
    "method": "GET",
    "target": "/v2/user/orders/open",
    "body": "eyJwYWlyIjoidGVuX2J0YyJ9" // Equal to {"pair":"ten_btc"}"
}

Withdraw

Transfer the asset from Tokenomy to an external account or other exchange.

  • Method: POST

  • Target: /v2/user/withdraw

  • Parameters in the body:

    • timestamp: Required, integer. Unix timestamp when requests being made.

    • request_id: Required, string. Custom string to identify each withdrawal request. The request_id will be passed to the callback URL to allow the receiver to identify the withdrawal request. The request_id must be less than 255 characters and only contains alphanumeric characters.

    • asset: Required, string. The name of the asset to be withdrawn.

    • address: Required, string. Receiver address.

    • amount: Required, float. Amount to be withdrawn.

    • memo: Optional (depends on the receiver), string. Memo to be sent to the receiver address. Some exchanges use a memo to accept deposits for certain assets. For example, on Ripple the memo value is custom Destination Tag, on NXT the memo value is custom Message, in BitShares the memo value is custom Memo.

Trade ask

Open a sell for an asset at a specific amount and price.

  • Method: POST

  • Target: /v2/trade/ask

  • Parameters in the body:

    • trade_method: Required, string, The method of trade, its either "limit" or "market", default to "limit" if it is empty.

    • pair: Required, string. The name of the pair in the format "<coin>_<base>".

    • amount: Required, float. The amount of coin to sell

    • price: Required, float. The price of the coin to sell

    • time_in_force: Optional, string. This parameter only applicable if trade_method is "limit". This parameter may change the behaviour of order "limit" processed by broker. Currently, the valid values are empty "" (default) or "FOK" (fill-or-kill).

      If the value is empty, the order request processed normally as "limit" request.

      If the value is "FOK", the order will be success only if only all of requested amount is fulfilled, otherwise it will return as an error.

Trade bid

Open a buy for an asset at a specific amount and price on the market.

  • Method: POST

  • Target: /v2/trade/bid

  • Parameters in the body:

    • trade_method: Required, string, The method of trade, its either "limit" or "market", default to "limit" if it is empty.

    • pair: Required, string. The name of the pair in the format "<coin>_<base>".

    • amount: Required, float. The amount of coin to sell

    • price: Required, float. The price of the coin to sell

    • time_in_force: Optional, string. This parameter only applicable if trade_method is "limit". This parameter may change the behaviour of order "limit" processed by broker. Currently, the valid values are empty "" (default) or "FOK" (fill-or-kill).

      If the value is empty, the order request processed normally as "limit" request.

      If the value is "FOK", the order will be success only if only all of requested amount is fulfilled, otherwise it will return as an error.

Trade cancel all orders

Cancel all open ask and bid orders.

  • Method: DELETE

  • Target: /v2/trade/cancel/all

Trade cancel ask

Cancel a specific sell order by ID.

  • Method: DELETE

  • Target: /v2/trade/cancel/ask

  • Parameters in the body:

    • pair: Required, string. The name of the pair in the format "<coin>_<base>".

    • trade_id: Required, number. The ID of trade to be canceled.

Trade cancel bid

Cancel specific trade buy by ID.

  • Method: DELETE

  • Target: /v2/trade/cancel/bid

  • Parameters in the body:

    • pair: Required, string. The name of the pair in the format "<coin>_<base>".

    • trade_id: Required, number. The ID of trade to be canceled.

Broadcast notifications

As mentioned earlier in WebSocket WebSocket schema, at some point the WebSocket connection will receive broadcast notifications.

The private WebSocket will receive the following notifications,

Order partially taken notification

This notification will received when part of your open order amount taken by other users, which means your open order is still marked as open in the market. Format of notification,

{
    "id": 0,
    "code": 0,
    "message": "/v2/user/orders/taken",
    "body": <Trade>
}

See Trade schema for the format of Trade value.

Order closed notification

This notification will received when all of your open order amount taken by other users, which means your order has been marked as closed by market. Format of notification,

{
    "id": 0,
    "code": 0,
    "message": "/v2/user/orders/closed",
    "body": <Trade>
}

See Trade schema for the format of Trade.

Client library

List of a client library for Tokenomy API,

History

v0.9.0 (2021-05-20)

New features

Add parameter time_in_force with "FOK" to trade APIs.

Enhancements

Make all section to have valid anchors.

v0.8.1 (2021-01-22)

Remove the list of pair names, since its may subject to changes while the documentation is not up to date. User can get the latest information from the Market information from public API.