NAV Navbar
Samples

Introduction

Coinscious Data Service - Market Data API: Our comprehensive raw market data API services include crypto exchange trade history data, order book data, blockchain transaction data, media updates data and millisecond level live stream data.

Version: 1.0.0

Requests

Exchange

Please refer to the value of name field in the response returned by Exchange List Exchange List API.

Fiat Currency

We support AUD, CAD, CNY, EUR, GBP, JPY, KRW, RUB and USD. USD is used as the default for any pricing.

Token Pair

Please refer to the response returned by Exchange Token Pair List API.

Token

Please refer to the response returned by Token List API. Only lower case is accepted.

Interval, Limit and Date Range

We support the following intervals: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 12h, 1d, 1W. The default interval is 30m if it is not specified.

"Limit" is the number of data returned in JSON response.
* Limit is set to the default value of 500 if it is not specified.
* We only accept limits less than and equal to 2000. Multiple calls are required with different time ranges to pull more data.

You can also specify your query date range by defining the start and end in query parameters.
* "End" is set to the current timestamp by default.
* "Start" is calculated based on end, limit, and interval.

Response

Coinscious uses standard HTTP response codes to indicate the success or failure of an API request. For example,
* Code 200 indicates success.
* Code 400 indicates an error that resulted from the provided information (e.g., a required parameter was missing).

JSON structure of an unexpected error response is the following:

{
  "code": "1001",
  "message": "Exchange not specified."
}

We support the following list of standard HTTP response codes:

Status Code Description
200 It's All Good.
400 Unexpected Error
Refer to the list of Error Codes we provide.
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
429 Too Many Requests
500 Internal Server Error

Dump (.csv) downloads

Trade History Download

Download a .csv dump file that contains the trade history of a specific token pair found on a supported exchange.

HTTP Request

GET /download/trade-history/{exchange}/{pair}

Parameters

Name Required Type Description
exchange Yes string Exchanges supported
pair Yes string Token Pair supported
start No timestamp
end No timestamp
limit No integer Interval and limit

Responses

Code Description
200 Successful response

Examples

/download/trade-history/poloniex/eth_btc?start=1532554784000&end=1532562073000&limit=500

Order Book Download

Download a .csv dump file that contains a 10% order book. This consists of orders placed at 10% lower or higher than the mid-price, for a specific token pair found on a supported exchange.

HTTP Request

GET /download/orderbook/{exchange}/{pair}

Parameters

Name Required Type Description
exchange Yes string Exchanges supported
pair Yes string Token Pair supported
start No timestamp
end No timestamp
limit No integer Interval and limit

Responses

Code Description
200 Successful response

Examples

/download/orderbook/bittres/eth_btc?start=1532554784000&end=1532555700000&limit=200

Exchange API

Exchange List

Obtain a list of supported exchanges, including their fee structures.

HTTP Request

GET /exchanges

The request returns JSON structured like the following:

[  
  {
    "name": "binance",
    "fee": {
        "orderExecutionFees": [
          {
            "tokenOrPair": "all",
            "isFutureTrading": false,
            "makerFee": "0.100%",
            "takerFee": "0.200%",
            "settlementFee": "",
            "leverage": "",
            "condition": "$0.00 or more traded"
          },
          {
            "tokenOrPair": "all",
            "isFutureTrading": false,
            "makerFee": "0.080%",
            "takerFee": "0.200%",
            "settlementFee": "",
            "leverage": "",
            "condition": "$500,000.00 or more traded"
          }
        ],
        "withdrawFees": [
          {
            "token": "btc",
            "feeRange": 
              {
                "all" : "0.0004 BTC"
              },
            "minumum": "0.002",
            "maximum": "",
            "limits": 
              {
                "Withdraw Daily Limit" : "100000"
              }
          }
        ],
        "depositFees": [
          {
            "token": "btc",
            "feeRange": 
              {
                ">=1000USD": "FREE",
                "<1000USD": "0.0004 BTC"
              },
            "minumum": "",
            "maximum": "",
            "limits": {}
          }
        ],
        "contracts": [
          {
            "contractType": "Perpetual Contracts",
            "tokenOrPair": "xbt",
            "makerFee": "-0.0250%",
            "takerFee": "0.0750%",
            "settlementFee": "",
            "leverage": "100x",
            "longFunding": "0.0100%",
            "shortfunding": "-0.0100%",
            "fundingInterval": "every 8 hours"
          }, 
          {
            "contractType": "Traditional Futures",
            "tokenOrPair": "xbt",
            "makerFee": "-0.0250%",
            "takerFee": "0.0750%",
            "settlementFee": "0.0500%",
            "leverage": "100x",
            "longFunding": "",
            "shortfunding": "",
            "fundingInterval": ""
          },
        ],
        "marginFunding": [
          {
            "Charge on fees collected by Margin Funding Providers":"15.0% (of the fees generated by active margin funding contracts)",
            "Charge on fees collected by Margin Funding Providers, when opened by a hidden offer": "18.0% (of the fees generated by active margin funding contracts)",
            "Charge on funding that is borrowed and subsequently returned without being used in a margin position":"Up to one full day’s interest"
          }
        ]
      }
  },
  {
    "name": "polonix",
    "fee": {
      "orderExecutionFees": [
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.10%",
          "takerFee": "0.20%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) < 500K USD",
          "futureTrading": false
        },
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.08%",
          "takerFee": "0.20%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) ≥ 500K USD",
          "futureTrading": false
        },
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.06%",
          "takerFee": "0.20%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) ≥ 1M USD",
          "futureTrading": false
        },
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.04%",
          "takerFee": "0.20%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) ≥ 2.5M USD",
          "futureTrading": false
        },
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.02%",
          "takerFee": "0.20%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) ≥ 5M USD",
          "futureTrading": false
        },
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.00%",
          "takerFee": "0.20%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) ≥ 7.5M USD",
          "futureTrading": false
        },
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.00%",
          "takerFee": "0.18%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) ≥ 10M USD",
          "futureTrading": false
        },
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.00%",
          "takerFee": "0.16%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) ≥ 15M USD",
          "futureTrading": false
        },
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.00%",
          "takerFee": "0.14%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) ≥ 20M USD",
          "futureTrading": false
        },
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.00%",
          "takerFee": "0.12%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) ≥ 25M USD",
          "futureTrading": false
        },
        {
          "tokenOrPair": "all",
          "isFutureTrading": false,
          "makerFee": "0.00%",
          "takerFee": "0.10%",
          "settlementFee": null,
          "leverage": null,
          "condition": "Trade Volume (trailing 30 day avg) ≥ 30M USD",
          "futureTrading": false
        }
      ],
      "withdrawalFees": [
        {
          "token": "all",
          "feeRange": {
            "all": "0"
          },
          "minimum": null,
          "maximum": null,
          "limits": null
        }
      ],
      "depositFees": [
        {
          "token": "all",
          "feeRange": {
            "all": "0"
          },
          "minimum": null,
          "maximum": null,
          "limits": null
        }
      ],
      "contracts": null,
      "marginFunding": null
    }
  }
]

Responses

Code Description
200 Successful response

Exchange Token Pair List

Obtain a list of all the token pairs available on a supported exchange.

HTTP Request

GET /exchanges/{exchange}/pairs

Parameters

Name Required Type Description
exchange Yes string Exchanges supported

The request returns JSON structured like the following:

[
  "eth_btc",
  "btc_usdt"
]

Responses

Code Description
200 Successful response

Token List

Obtain a list of general information on all the available tokens.

HTTP Request

GET /tokens

The request returns JSON structured like the following:

[
  {
    "symbol": "BTC",
    "fullName": "Bitcoin (BTC)",
    "chineseName": "比特币"
  }
]

Responses

Code Description
200 Successful response

OHLCV Data

Obtain open, high, low, close prices and volume indicators (OHLCV) data for a specific token pair found on a supported exchange.

HTTP Request

GET /ohlcv/{exchange}/{pair}

Parameters

Name Required Type Description
exchange Yes string Exchanges supported
pair Yes string Token Pair supported
interval No integer
start No timestamp
end No timestamp
limit No integer Interval and limit

The request returns JSON structured like the following:

[
  {
    "timestamp": 1515100800000,
    "open": 0.06354946,
    "high": 0.06377,
    "low": 0.06320008,
    "close": 0.06320008,
    "volume": 31.97875423
  },
  {
    "timestamp": 1515101100000,
    "open": 0.06354947,
    "high": 0.06379,
    "low": 0.06320003,
    "close": 0.06320005,
    "volume": 45.39787
  }
]

Responses

Code Description
200 Successful response

VWAP Data

Obtain volume weighted average price (VWAP) data for a specific token found on a supported exchange.

HTTP Request

GET /vwap/{token}

Parameters

Name Required Type Description
token Yes string Token supported
fiat No string Fiat Currency supported
interval No integer
start No timestamp
end No timestamp
limit No integer Interval and limit

The request returns JSON structured like the following:

[
  {
    "timestamp": 1515100800000,
    "vwap": 10.32
  },
  {
    "timestamp": 1515101100000,
    "vwap": 9.98
  }
]

Responses

Code Description
200 Successful response

Exchange VWAP Data

Obtain volume weighted average price (VWAP) for a specific token pair found on a supported exchange.

HTTP Request

GET /exchange-vwap/{exchange}/{pair}

Parameters

Name Required Type Description
exchange Yes string Exchanges supported
pair Yes string Token Pair supported
interval No integer
start No timestamp
end No timestamp
limit No integer Interval and limit

The request returns JSON structured like the following:

[
  {
    "timestamp": 1515100800000,
    "vwap": 10.32
  },
  {
    "timestamp": 1515101100000,
    "vwap": 9.98
  }
]

Responses

Code Description
200 Successful response

BlockChain API

Exchange Wallet Balance

Obtain the wallet balance of a specific token found on a supported exchange.

HTTP Request

GET /balance/{exchange}/{token}

Parameters

Name Required Type Description
exchange Yes string Exchanges supported
token Yes string Token supported
start No timestamp
end No timestamp
limit No integer Interval and limit

The request returns JSON structured like the following:

[
  {
    "timestamp": 1515100800000,
    "amount": 23178.43232
  },
  {
    "timestamp": 1515101100000,
    "amount": 56782.93234203
  }
]

Responses

Code Description
200 Successful response

Token Team Balance

Obtain the balance owned by a token team.

HTTP Request

GET /balance/team/{token}

Parameters

Name Required Type Description
token Yes string Token supported
start No timestamp
end No timestamp
limit No integer Interval and limit

The request returns JSON structured like the following:

[
  {
    "timestamp": 1515100800000,
    "balances": [
      {
        "token": "ETH",
        "amount": 21394.43281793
      },
      {
        "token": "BTC",
        "amount": 3242.98565341
      }
    ]
  }
]

Responses

Code Description
200 Successful response

Outstanding Transactions

We consider the following transactions as the outstanding transaction: * A transaction amount that exceeds a pre-defined threshold value. * The outstanding transaction is ranked in the top percentile within a specific period.

HTTP Request

GET /transactions/top/{token}

Parameters

Name Required Type Description
token Yes string Token supported
start No timestamp
end No timestamp
limit No integer Interval and limit

The request returns JSON structured like the following:

[
  {
    "timestamp": 1515100800000,
    "transactionId": "5b9c4d62e93fb9b5bc1f1346",
    "amount": 45890.34212,
    "token": "btc",
    "senders":[
      {
        "address": "3JrCTAR83kKHd4vNodgU9TGhNmGr8ckwXd",
        "holder": "Binance"
      }
    ],
    "receivers":[
      {
        "address": "3HvxQLkpsEfYBuu5sKjhvQNZWNkTxGF97L",
        "holder": "EXX"
      },
      {
        "address": "0xaec98a708810414878c3bcdf46aad31d",
        "holder": "EXX"
      },
    ],
    "comment": "comments"
  }, 
  {
    "timestamp": 1515101100000,
    "transactionId": "5b7e153ce213a53a517a729b",
    "amount": 989767.374283742,
    "token": "btc",
    "senders":[
      {
        "address": "1BGtxvdQRVUcR82F4nCs4C4yGgqanZCuMa",
        "holder": "Binance"
      },
      {
        "address": "1MHxTqiukBzCVvdD7LWyYxt18W2tkZUx2u",
        "holder": "Binance"
      },
      {
        "address": "14iwwXn7j5BbCfj2brDqWao5KFZojKtN4r",
        "holder": "Binance"
      }
    ],
    "receivers":[
      {
        "address": "1PYkDTq1uvh3khFiVG82nKLStwoJdRYGGL",
        "holder": "EXX"
      },
      {
        "address": "1HDowE9SBH6rRpB8WdrEh74xqZx6uBFn2e",
        "holder": "EXX"
      },
    ],
    "comment": "comments"
  }
]

Responses

Code Description
200 Successful response

Blockchain Address Balance

Obtain the latest balance of a specific blockchain address.

HTTP Request

GET /addresses/{address}/{token}

Parameters

Name Required Type Description
address Yes string Blockchain address
token Yes string Token supported

The request returns JSON structured like the following:

{
  "balance": 124.344958
}

Responses

Code Description
200 Successful response

Blockchain Transactions by Address

Obtain all transactions by a specific blockchain address.

HTTP Request

GET /addresses/{address}/{token}/transactions

Parameters

Name Required Type Description
address Yes string Blockchain address
token Yes string Token suppoeted
size No integer Page size
10 transactions will be returned each page if size is not specified
page No integer Page no
The first page is by default returned when page is not specified.

The request returns JSON structured like the following:

[
  {
    "numberOfTransctions": 2,
    "totalPages": 1,
    "pageSize": 10,
    "pageNo": 0,
    "transactions": 
    [
      {
        "timestamp": 1515100800000,
        "transactionId": "5b9c4d62e93fb9b5bc1f1346",
        "amount": 45890.34212,
        "senders":[
          {
            "address": "3JrCTAR83kKHd4vNodgU9TGhNmGr8ckwXd",
            "holder": "Binance"
          }
        ],
        "receivers":[
          {
            "address": "3HvxQLkpsEfYBuu5sKjhvQNZWNkTxGF97L",
            "holder": "EXX"
          },
          {
            "address": "0xaec98a708810414878c3bcdf46aad31d",
            "holder": "EXX"
          },
        ],
        "comment": "comments"
      }, 
      {
        "timestamp": 1515101100000,
        "transactionId": "5b7e153ce213a53a517a729b",
        "amount": 989767.374283742,
        "token": "btc",
          "senders":[
          {
            "address": "1BGtxvdQRVUcR82F4nCs4C4yGgqanZCuMa",
            "holder": "Binance"
          },
          {
            "address": "1MHxTqiukBzCVvdD7LWyYxt18W2tkZUx2u",
            "holder": "Binance"
          },
          {
            "address": "14iwwXn7j5BbCfj2brDqWao5KFZojKtN4r",
            "holder": "Binance"
          }
        ],
        "receivers":[
          {
            "address": "1PYkDTq1uvh3khFiVG82nKLStwoJdRYGGL",
            "holder": "EXX"
          },
          {
            "address": "1HDowE9SBH6rRpB8WdrEh74xqZx6uBFn2e",
            "holder": "EXX"
          },
        ],
        "comment": "comments"
      }
    ]
  }
]

Responses

Code Description
200 Successful response

Blockchain Transaction by ID

Obtain all blockchain transactions by a specific transaction ID.

HTTP Request

GET /transactions/{token}/{transactionId}

Parameters

Name Required Type Description
token Yes string Token supported
txId Yes string Transaction ID

The request returns JSON structured like the following:

{
  "timestamp": 1515100800000,
  "transactionId": "5b9c4d62e93fb9b5bc1f1346",
  "amount": 45890.34212,
  "token": "btc",
  "senders":[
    {
      "address": "3JrCTAR83kKHd4vNodgU9TGhNmGr8ckwXd",
      "holder": "Binance"
    }
  ],
  "receivers":[
    {
      "address": "3HvxQLkpsEfYBuu5sKjhvQNZWNkTxGF97L",
      "holder": "EXX"
    },
    {
      "address": "0xaec98a708810414878c3bcdf46aad31d",
      "holder": "EXX"
    },
  ],
  "comment": "comments"
}

Responses

Code Description
200 Successful response

Media Updates API

Media Update Categories

Obtain a list of all media update categories.

HTTP Request

GET /media/categories

The request returns JSON structured like this:

[
  {
    "category": "Bitcoin",
    "description": "Media updates for Bitcoin"
  },
  {
    "category": "Data & Research",
    "description": "Data and Research"
  }
]

Responses

Code Description
200 Successful response

Media Update Tags

Obtain a list of all tags for a particular media update tag.

HTTP Request

GET /media/tags

The request returns JSON structured like the following:

[
  "Bitcoin",
  "Bitcoin Price"
]

Responses

Code Description
200 Successful response

Media Updates

Obtain media updates for a particular token within a particular period. You can specify multiple categories and multiple tags as the search criteria.

The request body example:

{
  "categories": [
    "Bitcoin",
    "Ethereum"
  ],
  "tags": [
    "Events",
    "Industry",
    "Press Releases"
  ]
}

HTTP Request

POST /media/updates

Parameters

Name Required Type Description
token Yes string Token supported
start No timestamp
end No timestamp
limit No integer Default = 100
limit <= 500

The request returns JSON structured like the following:

[
  {
    "publishDate": "2018-09-20T06:21:18.504Z",
    "categories": [
      "Bitcoin",
      "Markets"
    ],
    "tags": [
      "Bitcoin",
      "Investment",
      "Finance",
      "Marketplaces"
    ],
    "subject": "Brazil’s Biggest Banks Under Investigation For Monopoly In Cryptocurrency Trade",
    "description": "Brazil’s Biggest Banks Under Investigation For Monopoly In Cryptocurrency Trade",
    "source": {
      "source": "Bitcoin.com",
      "url": "https://news.bitcoin.com/brazils-biggest-banks-under-investigation-for-monopoly-in-cryptocurrency-trade/",
      "author": "Jeffrey Gogo",
      "publish": "2018-09-19T06:21:18.504Z"
    }
  }
]

Responses

Code Description
200 Successful response

Live Stream

Get real-time, millisecond level, market data updates by connecting to our WebSocket.

WebSocket /live

Heartbeat Message

Client needs to implement ping/pong as RFC6455 defines.
Furthermore, in order to keep it alive, client needs to send ping to the server every minute.

Trade History

Subscribe & Unsubscribe Message

{ subscribe: "trade", msg: {exchange: <exchange>, pair: <pair>} }

{ unsubscribe: "trade", msg: {exchange: <exchange>, pair: <pair>} }

Parameters

Name Required Type Description
exchange Yes string Exchanges supported
pair Yes string Token Pair supported

Response

The response will have the following format:

{ site: <exchange>, currencyPair: <pair>, tradeTime: <timestamp>, price: <price>, amount: <amount>, originalId: <originalId>, isBuyMaker: <isBuyMaker> }

{
  site: binance,
  currencyPair: eth_btc,
  tradeTime: 1515100800000, 
  price: 6345.4545, 
  amount: 0.056, 
  originalId: 1278007, 
  isBuyMaker: true
}

Order Book

Subscribe & Unsubscribe Message

{ subscribe: "orderbook", msg: {exchange: <exchange>, pair: <pair>} }

{ unsubscribe: "orderbook", msg: {exchange: <exchange>, pair: <pair>} }

Parameters

Name Required Type Description
exchange Yes string Exchanges supported
pair Yes string Token Pair supported

Response

The response will have the following format:

{ site: <exchange>, currencyPair: <pair>, fetchTime: <timestamp>, asks:[ {price: <price>, amount: <amount>}, ... ], bids:[ {price: <price>, amount: <amount>}, ... ] }

{
  site: binance,
  currencyPair: eth_btc,
  fetchTime:1515100800000,
  asks:
    {price: 1.3456778, amount: 23.6},
    {price: 1.35, amount:20.67}
  ],
  bids:[
    {price: 1.345, amount: 23.6},
    {price: 1.35, amount:20.67}
  ]
}

Error Codes

Coinscious Data Services - Market Data API uses the following error codes:

Error Code Meaning
1001 Exchange not specified.
1002 Exchange not supported.
1003 Pair not specified.
1004 Pair not supported.
1005 Token not specified.
1006 Token not supported.
1007 Fiat currency not supported.
1008 Interval not supported.
1009 Limit exceeds max limit supported.
1010 Invalid data range.
1011 Date range less than interval.
2001 Address not specified.
2002 Invalid address or address not found.
2003 Transaction ID not specified.
2004 Invalid transaction ID or transaction ID not found.
3001 Media category or tag does not exist.
4001 Invalid WebSocket command.