API v2 Documentation

Overview

This document provides a resource to use Tokenomy API v2 that is available at https://api.tokenomy.com. The Tokenomy API v2 provides HTTP and WebSocket APIs.

Most of the API requires authentication, except for the market’s related HTTP 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.

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": <number>,
    "message": <string>,
    "name": <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 name field contains the name of error message, for example ERR_INTERNAL for status code 500 internal server error. 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.

Schemas

This section contains a list of common objects that are returned by HTTP or WebSocket APIs.

All of the schemas uses the JSON format with standard JavaScript types: number, string, boolean, and null. In this document we have additional types:

address: The address in network as string.
assetName: The name of asset as string, for example "ten", "btc", "eth".
decimalString: A decimal number formatted as string, for example "0.001".
epoch: Number that represents Unix timestamp in seconds, for example 1638853254 is equal to UTC time "2021-12-07 05:00:54".
pairName: The name of pair as string, for example "ten_btc".

DepositItem

The DepositItem record the asset deposit transaction to Tokenomy. Format of DepositItem,

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

id: the unique ID for each deposit transaction.

status: status of deposit. Each deposit has three possible status:

pending: deposit transaction waiting for confirmation.
success: the deposit transaction has been successfully received and processed by Tokenomy.
failed: the deposit transaction failed to process.

amount: the amount of asset being deposited.

final_amount: the total amount of asset being deposited.

success_time: the time when deposit successfully processed.

Depth

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

Depth format,

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

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

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.

Market depths

The MarketDepths schema contains total volume of sell and buy orders related to single pair grouped by prices.

{
    "data": {
        "pair": <pairName>,
        "asks": <Depth[]>,
        "bids": <Depth[]>
    }
}

Market information

The MarketInfo schema contains information about pair that can be traded in the Tokenomy platform. The MarketInfo format,

{
    "id": <string>,
    "symbol": <string>, // Deprecated, in favor of "pair".
    "pair": <string>,
    "coin_asset": <string>,
    "base_asset": <string>,
    "amount_precision": <number>,
    "amount_minimum": <decimalString>,
    "price_precision": <number>,
    "price_minimum": <decimalString>,
    "is_active": <boolean>
}

id: the pair ID.

symbol: the pair symbol, for example "ten_btc". This field is deprecated, in favor of "pair".

pair: the pair name, for example "ten_btc".

coin_asset: the name of coin asset, for example for pair "ten_btc", the coin name is "ten".

base_asset: the name of base asset, for example for pair "ten_btc", the base name is "btc".

amount_precision: the maximum digits after comma that is acceptable for coin asset.

amount_minimum: the minimum amount of coin for sell.

price_precision: the maximum digits after comma that is acceptable for price on sell order or for base asset in buy order.

price_minimum: the minimum amount of price on sell order or minimum amount of base asset in buy order.

is_active: If false the pair cannot be traded on market.

Ticker

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

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

pair: The pair name.

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

bid: 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 schema format,

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

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

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

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

id: Unique identifier for the trade.

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.

User balances

The UserBalances schema contains list of current user’s balance per asset.

{
    "<assetName>": <decimalString>,
    ...
}

User frozen balances

The UserFrozenBalances schema contains list of current user’s balance being freeze for trading.

{
    "<assetName>": <decimalString>,
    ...
}

User information (UserInfo)

The UserInfo schema contains the user information including its unique ID, email, full name, notification settings, wallet addresses, balances and frozen balances.

{
    "id": <number>,
    "email": <string>,
    "full_name": <string>,
    "notifications": <UserNotifications>,
    "wallets": <UserWallets>,
    "balances": <UserBalances>,
    "frozen_balances": <UserFrozenBalances>
}

User notifications

The UserNotifications schema contains the current setting for notification.

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

deposit: if true, user will receive notification after doing deposit transaction.

login: if true, user will receive notification on login to Tokenomy.

trade: if true, user will receive notification for each trading operation, from opening the trade until its filled or cancelled.

withdraw: if true, user will receive notification after a successful withdraw transaction.

User wallets

The UserWallets schema contains list of user’s address per asset.

{
    "<assetName>": "<address> (<Memo>)",
    ...
}

WithdrawItem

Format of Withdraw,

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

id: unique identified for each withdraw record.

status: status of withdraw transaction.

amount: amount of asset requested for withdraw.

fee: amount of fee.

final_amount: amount minus fee.

submit_time: the time when withdraw transaction requested.

success_time: the time when withdraw successfully confirmed by user.

HTTP 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?pair=

Query parameters,

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

Response

The response contains list of Depth grouped by ask’s and buy’s prices wrapped inside Market depths.

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

On success, it will return list of MarketInfo.

{
    "data": <MarketInfo[]>
}

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?pair=

Query parameters,

pair: Required. 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>": <decimalString>,
        ...
    }
}

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",
    "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",
    "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?pair=

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?pair=&offset=&limit=

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

Response 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
      },
      ...
    ]
  }
}

HTTP API private

Authentication

HTTP 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. Make sure the client operating system sync their time with the nearest time server, otherwise the request will be rejected if the timestamp value has 8 seconds differences with the server time.

For example, given an API key XYZ and Secret key secr3t, if we want to get trade history for pair ten_btc the query string would be,

timestamp=1574423788&pair=ten_btc

Note: 1574423788 is the example of epoch time that represent UTC time "2021-12-07 05:56:28".

First, compute the HMAC-SHA512 of query string using the Secret key,

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

Then encode the resulting hash into hexadecimal,

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

Finally, 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 with body,

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?timestamp=
Key: <API key>
Sign: <Signature of query using HMAC-SHA512>

Query parameter,

timestamp: Required. The Unix timestamp when the request is made.

Response

On success, it will return the User information.

{
    "data": <UserInfo>
}

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)",
      "eth": "0xb1b26bf16dc831208dbc703206579f81b6262767",
      "hnst": "bnb1u8tv2fpcd3fz7yn9jcpqr2vd5suhpx6gyx54n7 (Memo 114)",
      "lyfebep": "bnb1u8tv2fpcd3fz7yn9jcpqr2vd5suhpx6gyx54n7 (Memo 114)",
      "six": "GC3UVRVE54GJ45YTOPPYI4TTH2ZN4CZLVIHZNJ5PR5GP54IF6B5KEY5B (Memo 114)",
      "swipe": "bnb1u8tv2fpcd3fz7yn9jcpqr2vd5suhpx6gyx54n7 (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?timestamp=&pair=&offset=&limit=&id_after=&id_before=&time_after=&time_before=
Key: <API key>
Sign: <Signature of query using HMAC-SHA512>

Query parameters,

timestamp: Required, number. The time when the request is made.
pair: Required, string. The name of the pair in the format "<coin>_<base>".
offset: Optional, number. The number of records to be skipped.
limit: Optional, number. The maximum number of records to be fetched.
id_after: Optional, number. Filter records with ID are greater or equal than its value.
id_before: Optional, number. Filter records with ID are equal or less than its value.
time_after: Optional, epoch. Filter records with trade’s time are after its value.
time_before: Optional, epoch. Filter records with trade’s time are before its value.

Response

The API will return list of user’s 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 closed orders

List of user trades that have been completed or canceled.

Request

GET /v2/user/orders/closed?timestamp=&pair=&offset=&limit=&time_after=&time_before=
Key: <API key>
Sign: <Signature of query using HMAC-SHA512>

Query parameters,

timestamp: Required, epoch. Unix timestamp when requests being made.
pair: Required, string. The name of the pair in the format "<coin>_<base>".
offset: Optional, number. The number of records to be skipped.
limit: Optional, number. The maximum number of records to be fetched. Default to 100 if not set.
sort: Optional, string. Define the sorting order of returned records by ID. Valid value is "asc" for ascending or "desc" (default) for descending order.
time_after: Optional. Unix timestamp to filter only orders that have been submitted after the time.
time_before: Optional, Unix timestamp to filter only orders that have been submitted before the time.

Response

The response data contains list of user closed 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 open orders

List of user orders that still open in the market.

Request

GET /v2/user/orders/open?timestamp=&pair=
Key: <API key>
Sign: <Signature of query using HMAC-SHA512>

Query parameters,

timestamp: Required, epoch. 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

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

Request

GET /v2/user/order?timestamp=&pair=&trade_id=
Key: <API key>
Sign: <Signature of query using HMAC-SHA512>

Query parameters,

timestamp: Required, epoch. Unix timestamp when requests being made.
pair: Required, string. The name of the pair in the format "<coin>_<base>".
trade_id: Required, number. The ID of trade to be fetched.

Response

Response format,

{
    "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?timestamp=&asset=&offset=&limit=
Key: <API key>
Sign: <Signature of query using HMAC-SHA512>

Query parameters,

timestamp: Required, epoch. 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>": <DepositItem>,
            ...
        },
        "withdraw": {
            "<assetName>": <WithdrawItem>,
            ...
        }
    }
}

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 generating the API key.

The callback URL is an endpoint that will be called by our system to verify the withdrawal request. The withdraw parameters in the request will be forwarded to the Callback URL for confirmation. 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
Key: <API key>
Sign: <Signature of body using HMAC-SHA512>

timestamp=&request_id=&asset=&address=&amount=&memo=

Parameters in the body,

timestamp: Required, epoch. 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
Key: <API key>
Sign: <Signature of body using HMAC-SHA512>

timestamp=&pair=&trade_method=&amount=&price=&post_only=&time_in_force=

Parameters in the body,

timestamp: Required, epoch. 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": <UserInfo>
    }
}

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
Key: <API key>
Sign: <Signature of body using HMAC-SHA512>

timestamp=&pair=&trade_method=&amount=&price=&post_only=&time_in_force=

Parameters in the body,

timestamp: Required, epoch. 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": <UserInfo>
    }
}

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, optionally by specific pair.

Request

DELETE /v2/trade/cancel/all?timestamp=&pair=
Key: <API key>
Sign: <Signature of query using HMAC-SHA512>

Parameters in the query,

timestamp: Required, epoch. Unix timestamp when requests being made.
pair: Optional, string. The name of pair orders to be cancelled. If it’s not set, all user orders will be cancelled.
type: Optional, type of order; its either empty string "" (default), "sell", or "buy". If its empty, all sell and buy orders will be cancelled. If its "sell" only open sell orders will be cancelled. If its "buy" only open buy orders will be cancelled.

Response

On success, it will list of cancelled orders,

{
    "data": <Trade[]>
}

Trade cancel ask

Request

DELETE /v2/trade/cancel/ask?timestamp=&pair=&trade_id=
Key: <API key>
Sign: <Signature of query using HMAC-SHA512>

Parameters in the query,

timestamp: Required, epoch. 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": <UserInfo>
    }
}

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?timestamp=&pair=&trade_id=
Key: <API key>
Sign: <Signature of query using HMAC-SHA512>

Parameters in the query,

timestamp: Required, epoch. 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": <UserInfo>
    }
}

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 HTTP 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": <number>,
    "code": <number>,
    "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

Get the market depths for single 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 summaries

Get the market summaries for all pairs.

Method: GET
Target: /v2/market/summaries

Example,

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

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 data 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 data for pair "ten_btc" they will send it to the client connection immediately.

Available topics and its value for subscription APIs,

depths: The subscription value is list of pair, for example ["ten_btc", "eth_btc"]. This topic will broadcast latest volume of open orders (asks and bids) based on pair.
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 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": <epoch>,
    "method": "POST",
    "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": 1639973898,
    "method": "POST",
    "target": "/v2/ws/subscription",
    "body": "eyJ0cmFkZXMiOlsidGVuX2J0YyJdfQ=="
}

The body field is base64 of the following JSON string,

{"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 HTTP 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, number. The ID of order to be fetched.

The response format is equal to Trade in HTTP 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, epoch. 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 open order amount taken by other users, which means the 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 open order amount taken by other users, which means the 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,

tokenomy-go: Go module for API v2.

History

v0.11.0 (2022-01-10)

Rename the word REST/rest to HTTP/http.
Add WebSocket market summaries

v0.10.0 (2021-12-22)

Add WebSocket subscription for market depths.

v0.9.3 (2021-12-21)

Add field "pair" to MarketDepths schema
Add parameters "offset", "limit", and "sort" to user orders history.

v0.9.2 (2021-12-07)

Add field "name" to General Response
Add new types "epoch" and "decimalString" to represent values in JSON format.
Move DepositItem, MarketInfo, UserBalances, UserFrozenBalances, UserInfo, UserNotifications, UserWallets, and WithdrawItem to Schema section.
Add query or body parameters to request format

v0.9.1 (2021-06-21)

Fixes

Fix the WebSocket method for subscribe. The correct method should be POST instead of PUT.

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.