API Documentation

Endpoint URL

https://www.btcbox.co.jp/api/v1

At BTCBOX, we have  HTTP Private API that need confirmation by an API Key, and HTTP Public API that does not need any confirmation.

API Restriction

HTTP API is being executed as the following api request limit per second

  • trade_add (Send Order) : Within 5 times every second
  • trade_list (Confirmation of Order List) : Within 3 times every second
  • balance (Balance Confirmation) : Within 5 times every second

There are no other API request upper limits, but in case of the company deems repeated requests with the purpose of loading the system, please note that the company might limit the use of the API.

【Public API】

・Cryptocurrencies Information(tickers)

Request Method:GET

https://www.btcbox.co.jp/api/v1/tickers

Response

  • Acquiring Information for all four cryptocurrencies(BTC/JPY、BCH/JPY、LTC/JPY、ETH/JPY)
NameData TypeDescription
highNUMBER24 H High Price
lowNUMBER24 H Low Price
buyNUMBERBuy Quotation
sellNUMBERSell Quotation
lastNUMBERLatest Execution Price
volNUMBER24 H Trading Volume

Sample

{
  BTC_JPY: {
    high: 1120536,
    low: 1090060,
    buy: 1104140,
    sell: 1106870,
    last: 1105752,
    vol: 1015.8602
  },
  BCH_JPY: {
    high: 33296,
    low: 31992,
    buy: 32425,
    sell: 33266,
    last: 33249,
    vol: 1088.826
  },
  LTC_JPY: {
    high: 7945,
    low: 7447,
    buy: 7871,
    sell: 7878,
    last: 7874,
    vol: 716.8658
  },
  ETH_JPY: {
    high: 21570,
    low: 20421,
    buy: 21435,
    sell: 21450,
    last: 21449,
    vol: 1357.1235
  }
}

・Cryptocurrency Information(ticker)

Request Method:GET

https://www.btcbox.co.jp/api/v1/ticker

ex. ETH/JPY Realtime Rate

https://www.btcbox.co.jp/api/v1/ticker?coin=eth

Parameter

NameData TypeRequiredDescription
coinSTRINGNoBTC、BCH、LTC、ETH
(Default : BTC)

Response

NameData TypeDescription
highNUMBER24 H High Price
lowNUMBER24 H Low Price
buyNUMBERBuy Quotation
sellNUMBERSell Quotation
lastNUMBERLatest Execution Price
volNUMBER24 H Trading Volume

Sample

 {
    "high":39700,
    "low":36300,
    "buy":1.879,
    "sell":0,
    "last":38800,
    "vol":283.954
  }

・Orderbook Information(depth)

Request Method:GET

https://www.btcbox.co.jp/api/v1/depth

ex. ETH/JPY Realtime Rate

https://www.btcbox.co.jp/api/v1/depth?coin=eth

Parameter

NameData TypeRequiredDescription
coinSTRINGNoBTC,BCH,LTC, ETH
(Default: BTC)

Response

NameData TypeDescription
asksArrayDisplaying the present “Sell Order Price・Amount”
List of Orders are in Price order (High to Low)
bidsArrayDisplaying the present “Buy Order Price・Amount”
List of Orders are in Price order (Low to High)

Sample

{  
   "asks":[  
      [  
         41700,
         10
      ],
      [  
         41300,
         6
      ],
      [  
         40900,
         10
      ],
      [  
         40500,
         6
      ],
      [  
         40125,
         10.0277
      ],
      [  
         40100,
         5
      ],
      [  
         40089,
         0.509
      ],
      [  
         39800,
         14.7132
      ],
      [  
         39799,
         0.0695
      ],
      [  
         39798,
         5
      ],
      [  
         39700,
         2.89
      ],
      [  
         39000,
         0.209
      ]
   ],
   "bids":[  
      [  
         38300,
         1.879
      ],
      [  
         38100,
         1.0078
      ],
      [  
         38000,
         1.24
      ],
      [  
         37700,
         4.706
      ],
      [  
         37600,
         3.8313
      ],
      [  
         37001,
         0.146
      ],
      [  
         36999,
         5.8
      ],
      [  
         36400,
         5
      ],
      [  
         36200,
         1.3314
      ],
      [  
         36002,
         2
      ],
      [  
         36000,
         1.568
      ],
      [  
         35501,
         0.282
      ],
      [  
         35500,
         9.9
      ],
      [  
         35200,
         5.6
      ]
   ]
}

・Execution History(orders)

Acquire the latest 100 cases of execution information in ascending order of execution time.

Request Method:GET

https://www.btcbox.co.jp/api/v1/orders

ex.ETH/JPY Execution History

https://www.btcbox.co.jp/api/v1/orders?coin=eth

Parameter

NameData TypeRequiredDescription
coinSTRINGNoBTC、BCH、LTC、ETH
(Default : BTC)

Response

NameData TypeDescription
dateSTRINGExecution Date (UNIX time)
priceNUMBERExecution Price
amountNUMBERExecution Amount
tidSTRINGOrder ID
typeSTRINGTrade Type(”buy” “sell”)

Sample

[  
   {  
      "date":"0",
      "price":3,
      "amount":0.1,
      "tid":"1",
      "type":"buy"
   },
   {  
      "date":"0",
      "price":32323,
      "amount":2,
      "tid":"2",
      "type":"sell"
   },
   {  
      "date":"0",
      "price":32,
      "amount":432,
      "tid":"3",
      "type":"sell"
   },
   {  
      "date":"0",
      "price":323,
      "amount":2,
      "tid":"4",
      "type":"sell"
   },
   {  
      "date":"0",
      "price":2100,
      "amount":0.3,
      "tid":"5",
      "type":"buy"
   }
]

【Private API】

About confirmation

In order to use Private API, confirmation will be necessary.

Procedure for obtaining API key

NOTE : In case the customer’s Private API is leaked to a third party,  and the assets are manipulated・traded without the customer’s designated intent, the customer may suffer loss. Please manage your Private API in a secure way.

Private API Use Order

  1. Preparing a applicable parameter, and using the private key, conduct the signature (for more detail about signature, refer to the below)
  2. Every parameter and its signatured character string (signature)  will be sent to the server in POST format. Please note that It is necessary for the sent parameter sequence and the disposition sequence of the parameter’s signature time to match.

 About Signature

Example of Balance Confirmation API:

  1. Collecting other Parameters other than Signatures : coin, key, nonce
  2. Creating a character string as : key=xxxxxx&coin=btc&nonce=1508482053
  3. Using the HMacSHA256 function, encrypt the above character string. The encryption key is the Private API Key  digested with MD5 Algorithm.
  4. Signatures and other parameter will be send to API.

 About nonce

Usually, there is no problem if it is configured with UNIX timestamp, however, in case of the system check is the same as UID, the nonce must be bigger than the previously requested nonce. Please be careful when Multithreading Programming is carried out.

・Confirmation Balance(balance)

Confirming the BTCBOX Account Balance

Request Method:POST

https://www.btcbox.co.jp/api/v1/balance

Parameter

NameData TypeRequiredDescription
coinSTRINGNoBTC、BCH、LTC、ETH
(Default : BTC)
keySTRINGYesPublic API Key
nonceSTRINGYesNonce
signatureSTRINGYesSignature

Response

NameData TypeDescription
uidNUMBERUser ID Assigned to Every Customer
nameauthNUMBERPersonal Verification Status
『0:Non Verified』『1:Verified』
moflagNUMBERSMS Verification Setting Status
『0:Not Setup』『1:Setup』
btc_balanceNUMBERBTC Balance
btc_lockNUMBERPending BTC Balance
bch_balanceNUMBERBCH Balance
bch_lockNUMBERPending BCH Balance
ltc_balanceNUMBERLTC Balance
ltc_lockNUMBERPending LTC Balance
eth_balanceNUMBERETH Balance
eth_lockNUMBERPending ETH Balance
Jpy_balanceNUMBERJPY Balance
jpy_lockNUMBERPending JPY Balance

Sample

{
    "uid":8,
    "nameauth":0,
    "moflag":0,
    "btc_balance":4.234234,
    "btc_lock":0,
    "bch_balance":234,
    "bch_lock":15,
    "ltc_balance":32429.6,
    "ltc_lock":2.4,
    "eth_balance":0,
    "eth_lock":0,
    "jpy_balance":2344581.519,
    "jpy_lock":868862.481
}

・Address Confirmation(wallet)

Acquiring the BTCBOX Coin Deposit Address

Request Method:POST

https://www.btcbox.co.jp/api/v1/wallet

Parameter

NameData TypeRequiredDescription
coinSTRINGNoBTC、BCH、LTC、ETH
(Default : BTC)
keySTRINGYesAPI Key
nonceSTRINGYesNonce
signatureSTRINGYesSignature

Response

NameData TypeDescription
resultBOOL『true』『false』
addressSTRINGCorresponding Coin Deposit Address

Sample

{  
   "result":true,
   "address":"1xxxxxxxxxxxxxxxxxxxxxxxx"
}

・Order List(trade_list)

Acquire max. 100 order details from latest Orders until the designated date (since) with Array.

Request Method:POST

https://www.btcbox.co.jp/api/v1/trade_list

Parameter

NameData TypeRequiredDescription
coinSTRINGNoBTC、BCH、LTC、ETH
(Default : BTC)
keySTRINGYesAPI Key
nonceSTRINGYesNonce
sinceNUMBERNoDesignated Date
UNIX Timestamp(UTC Time)
Default: 0
signatureSTRINGYesSignature

Response

NameData TypeDescription
idNUMBEROrder ID
datetimeSTRING
(YYYY-MM-DD hh:mm:ss)
Order Date
typeSTRINGOrder Type
(”buy” “sell”)
priceNUMBEROrder Price
amount_originalNUMBEROrder Amount
amount_outstandingNUMBERPending Amount

Sample

[  
   {  
      "id":"7",
      "datetime":"2014-10-20 13:27:38",
      "type":"buy",
      "price":42750,
      "amount_original":0.235,
      "amount_outstanding":0.235
   },
   {  
      "id":"6",
      "datetime":"2014-10-20 13:27:15",
      "type":"buy",
      "price":43299,
      "amount_original":4.789,
      "amount_outstanding":4.789
   },
   {  
      "id":"5",
      "datetime":"2014-10-20 13:26:52",
      "type":"buy",
      "price":42500,
      "amount_original":14,
      "amount_outstanding":14
   },
   {  
      "id":"4",
      "datetime":"2014-10-20 13:26:23",
      "type":"buy",
      "price":43200,
      "amount_original":0.4813,
      "amount_outstanding":0.4813
   },
   {  
      "id":"3",
      "datetime":"2014-10-20 13:25:57",
      "type":"buy",
      "price":43200,
      "amount_original":0.4813,
      "amount_outstanding":0.4813
   }
]

・Order Details(trade_view)

Acquire the designated order content

Request Method:POST

https://www.btcbox.co.jp/api/v1/trade_view

Parameter

NameData TypeRequiredDescription
coinSTRINGNoBTC,BCH,LTC,ETH
(Default : BTC)
idSTRINGYesOrder ID
keySTRINGYesAPI Key
nonceSTRINGYesNonce
signatureSTRINGYesSignature

Response

NameData TypeDescription
idNUMBEROrder ID
datetimeSTRINGOrder Date
(yyyy-mm-dd hh:mm:ss)
typeSTRINGOrder Type
Buy Order , Sell Order
priceNUMBEROrder Price
amount_originalNUMBEROrder Amount
amount_outstandingNUMBERPending Amount
statusSTRINGOrder Status
『wait:Un-Execute』
『part:Partial Execution』
『cancelled:Cancelation Settled』
『all:All Executions Settled』

Sample

{  
   "id":11,
   "datetime":"2014-10-21 10:47:20",
   "type":"sell",
   "price":42000,
   "amount_original":1.2,
   "amount_outstanding":1.2,
   "status":"closed",
   "trades":[  

   ]
}

・Cancel an Order(trade_cancel)

Cancel the designated orders.

Request Method:POST

https://www.btcbox.co.jp/api/v1/trade_cancel

Parameter

NameData TypeRequiredDescription
coinSTRINGNoBTC,BCH,LTC,ETH
(Default : BTC)
idNUMBERYesOrder ID
keySTRINGYesPublic API Key
nonceNUMBERYesNonce
signatureSTRINGYesSignature

Response

NameData TypeDescription
resultBOOLResult
『true:Cancelled』
『false:Cancellation Failed』
idNUMBEROrder ID of Cancellation

Sample

{
    result: true,
    id: 11
}

・Send Order(trade_add)

Send an order with designated terms

Request Method:POST

https://www.btcbox.co.jp/api/v1/trade_add

Parameter

NameData TypeRequiredDescription
coinSTRINGNoBTC、BCH、LTC、ETH
(Default : BTC)
keySTRINGYesPublic API Key
nonceNUMBERYesNonce
amountNUMBERYesOrder Amount
priceNUNBERYesOrder Price
typeSTRINGYesOrder Type
Buy Order, Sell Order
signatureSTRINGYesSignature

Response

NameData TypeDescription
resultBOOLResult
『true:Settled Order』
『false:Failed Order』
idNUMBERGenerated Order ID

Sample

{
    "result":true,
    "id":11
}

Error Code

Error CodeDescription
100Must input the mandatory parameters.
101Invalid Parameter
102The coin does not exist
103The key does not exist
104Signature is not match
105No authority
106The request is expired. (nonce error)
107The price must be a whole number
200No Balance
201The trading number is too small
202The Price needs to be between 0~1000000.
203The order does not exist
301Not confirmed
401System Error
402Request is too frequent
403It is a un-open API
404IP limit does not require a source

【Sample Code】

Python

・PHP

<?php

$api = new apidemo('Public Key', 'Private Key', 'btc');
$api->get_balance();

class apidemo
{

	/**
	 * API URL
	 *
	 * @var string
	 */
	private $apiurl = 'https://www.btcbox.co.jp/api/v1/';

	/**
	 * Public Key
	 * Apply address:https://www.btcbox.co.jp/api/secret/keys/
	 *
	 * @var string
	 */
	private $key;

	/**
	 * Private Key
	 * Apply address:https://www.btcbox.co.jp/api/secret/keys/
	 *
	 * @var string
	 */
	private $passphrase;

	/**
	 * Coin
	 */
	public $coin;

	/**
	 * construct
	 */
	public function __construct($key = false, $passphrase = false, $coin = 'btc')
	{
		$this->key = $key;
		$this->passphrase = $passphrase;
		$this->coin = $coin;
	}

	/**
	 * Market
	 *
	 * @return array
	 * @access open
	 */
	public function ticker()
	{
		return $this->request('ticker', array(), 'GET', false);
	}

	/**
	 * Depth
	 *
	 * @return array
	 * @access open
	 */
	public function get_depth()
	{
		return $this->request('depth', array(), 'GET', false);
	}

	/**
	 * Get Orders
	 *
	 * @param $since -1~9999999999
	 *
	 * @return array
	 * @access open
	 */
	public function get_trades($since = -1)
	{
		return $this->request('orders', array('since' => $since), 'GET', false);
	}

	/**
	 * Account Balance
	 *
	 * @return array
	 * @access readonly
	 */
	public function get_balance()
	{
		return $this->request('balance', array(), 'POST');
	}

	/**
	 * Wallet Adress
	 *
	 * @return array
	 * @access readonly
	 */
	public function get_wallet()
	{
		return $this->request('wallet', array(), 'POST');
	}

	/**
	 * Get your recent orders
	 *
	 * @param integer $since After a time(Default All)
	 * @param string open|all $type type
	 *
	 * @return array
	 * @access readonly
	 */
	public function get_orders($since = 0, $type = 'all')
	{
		return $this->request('trade_list', array('since' => $since, 'type' => $type), 'POST');
	}


	/**
	 * Order Details
	 *
	 * @param integer $orderid Orders Id
	 *
	 * @return array
	 * @access readonly
	 */
	public function fetch_order($orderid)
	{
		return $this->request('trade_view', array('id' => $orderid), 'POST');
	}

	/**
	 * Cancel Order
	 *
	 * @param integer $orderid Order ID
	 *
	 * @return array
	 * @access full
	 */
	public function cancel_order($orderid)
	{
		return $this->request('trade_cancel', array('id' => $orderid), 'POST');
	}

	/**
	 * Trade
	 *
	 * @param float $amount number
	 * @param float $price price
	 *
	 * @return array
	 * @access full
	 */
	public function add($amount, $price, $type)
	{
		return $this->request('trade_add', array('amount' => $amount, 'price' => $price, 'type' => $type), 'POST');
	}

	/**
	 * Request
	 *
	 * @param string $method API Url
	 * @param array $params Parameters
	 * @param string GET|POST $http_method Request method
	 * @param bool $auth is Verify
	 *
	 * @return array
	 */
	protected function request($method, $params = array(), $http_method = 'GET', $auth = true)
	{
		# coin
		$params['coin'] = $this->coin;
		if ($auth) {
			# Unique number
			$mt = explode(' ', microtime());
			$params['nonce'] = $mt[1] . substr($mt[0], 2, 2);
			# verify information
			$params['key'] = $this->key;
			$params['signature'] = hash_hmac('sha256', http_build_query($params, '', '&'), md5($this->passphrase));
		}
		# data string
		$data = http_build_query($params, '', '&');
		$data = $this->do_curl($method, $data, ($http_method == 'GET' ? 'GET' : 'POST'));
		return $data;
	}

	/**
	 * Request
	 */
	private function do_curl($path, $data, $http_method)
	{
		static $ch = null;
		$url = $this->apiurl . $path;
		if (is_null($ch)) {
			$ch = curl_init();
			curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
			curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; Btcbox PHP client; ' . php_uname('s') . '; PHP/' . phpversion() . ')');
		}
		if ($http_method == 'GET') {
			$url .= '?' . $data;
		} else {
			curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
		}
		curl_setopt($ch, CURLOPT_URL, $url);
		curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
		if (!$response = curl_exec($ch)) {
			throw new Exception('Could not get reply: ' . curl_error($ch));
		}
		if (!$data = json_decode($response, true)) {
			throw new Exception('Invalid data received');
		}
		return $data;
	}
}