API Documentation

Navigation

1BTCXE REST API Documentation

Welcome to the 1BTCXE REST API documentation. This API (Application Programming Interface) will allow you to access the functionality of this exchange by means of HTTP requests, making integration with your own applications possible.

Connecting to the API

You can access the API at the following url:

https://1btcxe.com/api

You are permited to make up to 60 requests a minute.

Usage

In order to use a public API method, you must make an HTTP request to the appropriate endpoint for that particular method, sending the appropriate GET or POST parameters for that method. You can also send them in the PAYLOAD of the request in JSON format.

To access protected API methods, you must obtain an API key/secret pair. Their usage is explained further ahead in this document.

Here are a few basic usage examples:

# Example request using CURL on the command line
curl "https://1btcxe.com/api/transactions" \
-d currency="EUR" \
-d limit=5

// Example valid response
{"transactions": {
	"0":{"id":"131","date":"2014-11-13 10:42:46","btc":"1.00000000","maker_type":"buy","price":"10.00","amount":"10.00","currency":"USD"},
	"1":{"id":"129","date":"2014-11-11 11:14:12","btc":"0.50000000","maker_type":"buy","price":"11.27","amount":"5.63","currency":"EUR"},
	"2":{"id":"128","date":"2014-11-11 11:13:49","btc":"0.50000000","maker_type":"buy","price":"10.91","amount":"5.46","currency":"USD"},
	"3":{"id":"127","date":"2014-11-10 18:29:15","btc":"0.50000000","maker_type":"buy","price":"11.20","amount":"5.60","currency":"USD"},
	"4":{"id":"126","date":"2014-11-10 18:25:21","btc":"0.50000000","maker_type":"buy","price":"11.20","amount":"5.60","currency":"USD"},
	"request_currency":"USD"
	}
}

// Example error response
{"errors":[{"message":"Invalid currency.","code":"INVALID_CURRENCY"}]}

Public API Methods

These methods can be accessed without an account or API key.

Stats

Returns statistics about the current state of the exchange.

GET https://1btcxe.com/api/stats

Parameters:

currency (string) - Three-letter currency code. Default is "USD". Must be a currency supported by the exchange.

Response:

bid (float) - Current bid price.
ask (float) - Current ask price.
last_price (float) - The price of the last transaction.
last_transaction_type (string) - The action performed by the taker (initiator) of the last transaction. Can be "BUY" or "SELL".
last_transaction_currency (string) - Three-letter currency code for the currency in which the last transaction took place.
daily_change (float) - The amount that the current price has fallen or risen from the last close.
daily_change_percent (float) - The percentage of the current price versus the last close.
max (float) - Today's maximum transaction price.
min (float) - Today's minimum transaction price.
open (float) - Today's open price (note: since the market is always open, it is also yesterday's close price).
total_btc_traded (int) - Total BTC transaction volume for the last 24 hours.
total_btc (int) - Total BTC in existance worldwide.
market_cap (int) - The global market cap of Bitcoin.
trade_volume (int) - Global trade volume for Bitcoin.
request_currency (string) - The currency in which this information is presented.

Historical Prices

Gives daily market close prices for the selected period.

GET https://1btcxe.com/api/historical-prices

Parameters:

currency (string) - Three-letter currency code. Default is "USD". Must be a currency supported by the exchange.
timeframe (string) - The timeframe for your request. Permitted values are "1mon", "3mon", "6mon", "1year" and "ytd". Default is "1mon".

Response:

date (string) - The date string in YYYY-MM-DD format.
price (float) - The closing price for the given date.
request_currency (string) - The currency in which this information is presented.

Order Book

Returns information on all the orders currently in the order book. Return will be grouped into two different arrays for bid and ask respectively.

GET https://1btcxe.com/api/order-book

Parameters:

currency (string) - Three-letter currency code. Default is "USD". Must be a currency supported by the exchange.

Response:

price (float) - The limit price of the order.
order_amount (float) - The remaining amount in BTC.
order_value (float) - The remaining value of the order in your requested currency.
converted_from (string) - The original currency in which the order was placed, if not equal to the requested currency.
request_currency (string) - The currency in which this information is presented.

Transactions

Get the latest transactions that ocurred in the exchange, ordered by date in descending order.

GET https://1btcxe.com/api/transactions

Parameters:

currency (string) - Three-letter currency code. Please note: You can omit this parameter to receive all prices will be in their native currency!
limit (int) - The amount of records to receive. Default is 10.

Response:

id (int) - A unique identifier for the transaction.
date (string) - The date string in YYYY-MM-DD format.
btc (float) - The transaction amount in BTC.
price (float) - The price at which the transaction ocurred. Will be returned in the original currency if no currency parameter is sent in the request.
price1 (float) - Only if no currency param sent - The price at which the transaction ocurred for the second party (maker), in the original currency.
amount (float) - The transction amount in the requested currency. Will be returned in the original currency if no currency parameter is sent in the request.
amount1 (float) - Only if no currency param sent - The transaction amount in the second party's (maker's) original currency.
currency (string) - The currency in which the transaction ocurred. Will be returned in the original currency if no currency parameter is sent in the request.
currency1 (string) - Only if no currency param sent - The second party's (maker's) original currency.
request_currency (string) - The currency in which this information is presented. Will return 'ORIGINAL' if amounts are in the original currency.

Protected API Methods

In order to access these methods, you must obtain an API key/secret pair to authenticate your request.

Obtaining An API Key

To get access to our API, you must generate an API key on the API Access page. You must have two-factor authentication enabled on your account to be able to view this page. Upon generating a new API key, you will be given an API secret code. This value will only be shown to you once. Please store it in a secure place, as you will need it to use it together with your API key.

Once you have generated an API key, you can allow or restrict it's holder's access to the parent account's functionality by checking or unchecking the checkboxes in the "permissions" line under the API key.

Authenticating Your Request

To authenticate a request with your API key/secret pair, you must include the following parameters in your POST parameters or the JSON PAYLOAD of your request:

api_key (string) - The API key that you generated.
nonce (int) - A random integer. Each request must have a higher nonce than the last one. You can use the current UNIX timestamp for example.
signature (string) - An HMAC-SHA256 signature of the JSON-encoded parameters of the request, signed using the API secret that was generated together with the api_key. These parameters include the api_key and nonce. This signature should then be added to the request parameters.

We know that generating a signature might be a bit intimidating if you're doing it for the first time, so please see the following examples:

// Javascript Example

// we add our public key and nonce to whatever parameters we are sending
var params = {};
params.currency = "eur";
params.price = 200;
params.api_key = api_key;
params.nonce = Math.round(new Date().getTime() / 1000);
// create the signature
var hash = CryptoJS.HmacSHA256(JSON.stringify(data), api_secret);
var hashInBase64 = CryptoJS.enc.Hex.stringify(hash);
// add signature to request parameters
params.signature = hashInBase64;

// PHP Example
// we add our public key and nonce to whatever parameters we are sending
$commands['side'] = 'sell';
$commands['type'] = 'stop';
$commands['api_key'] = $api_key;
$commands['nonce'] = time();
// create the signature
$signature = hash_hmac('sha256', json_encode($commands), $api_secret);
// add signature to request parameters
$commands['signature'] = $signature;

# Python Example
import hashlib
import hmac
// we add our public key and nonce to whatever parameters we are sending
params = {'currency': 'eur', 'price': 200, 'api_key': api_key, 'nonce': time.time()}
// create the signature
message = bytes(json.dumps(params)).encode('utf-8')
secret = bytes(api_secret).encode('utf-8')
signature = hmac.new(secret, message, digestmod=hashlib.sha256).hexdigest()
// add signature to request parameters	
params['signature'] = signature

// C# Example
using System.Security.Cryptography;
// we add our public key and nonce to whatever parameters we are sending
var params1 = new List>();
params1.Add(new KeyValuePair("api_key", api_key));
params1.Add(new KeyValuePair("nonce", (Int32)(DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1))).TotalSeconds));
// create the signature
JavaScriptSerializer serializer = new JavaScriptSerializer();
var message = serializer.Serialize(params1);
secret = secret ?? "";
var encoding = new System.Text.ASCIIEncoding();
byte[] keyByte = encoding.GetBytes(secret);
byte[] messageBytes = encoding.GetBytes(message);
using (var hmacsha256 = new HMACSHA256(keyByte))
{
	byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
	var signature = BitConverter.ToString(hashmessage);
	signature = signature.Replace("-", "");
	// add signature to request parameters
	params1.Add(new KeyValuePair("signature", signature));
}

/* Java Example */
/* Dependent on Apache Commons Codec to encode in base64. */
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Hex;
/* we add our public key and nonce to whatever parameters we are sending */
Map params = new HashMap();
params.put("api_key", "demo");
params.put("nonce", ((int) (System.currentTimeMillis() / 1000L)));
/* create the signature */
String secret = "secret";
String message = new JSONObject(params).toString();
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
sha256_HMAC.init(secret_key);
String hash = Hex.encodeHexString(sha256_HMAC.doFinal(message.getBytes()));
/* add signature to request parameters */
params.put("signature", hash);

Balances and Info

Obtain the account's balances and fee levels.

POST https://1btcxe.com/api/balances-and-info

Response:

on_hold[currency][withdrawal] (float) - The amount of a currency pending withdrawal.
on_hold[currency][order] (float) - The amount of a currency in open orders.
on_hold[currency][total] (float) - The total amount of a currency that is on hold - the sum of the last two items.
available[currency] (float) - The amount of that particular currency that is currently available.
usd_volume (float) - The account's 30-day trading volume converted to USD.
fee_bracket[maker] (float) - The account's transaction fee level (as percentage), when not initiating the transaction (i.e. acting as a maker).
fee_bracket[taker] (float) - The account's transaction fee level (as percentage), when initiating the transaction (i.e. acting as a taker).
global_btc_volume (float) - Exchange-wide 24-hour transaction volume in BTC.

Open Orders

Get the account's current open orders, grouped by order side (bid or ask).

POST https://1btcxe.com/api/open-orders

Parameters:

currency (string) - Three-letter currency code. Will filter by orders of this currency. When omitted, all open orders will be displayed.

Response:

id (int) - A unique identifier for the order.
side (string) - "buy" or "sell".
type (string) - "market", "limit" or "stop".
amount (float) - The original order amount in BTC.
amount_remaining (float) - The amount that has not yet been filled in BTC.
price (float) - The current price of the order in its native currency.
avg_price_executed (float) - A weighted average of the prices at which the order has been filled, in it's native currency. Zero means it has not yet generated any transactions.
stop_price (float) - If there is the order is a stop order, the price at which the stop will be triggered.
currency (string) - The order's native currency.
status (string) - The order's current status. Possible values are 'ACTIVE','FILLED','CANCELLED_USER','OUT_OF_FUNDS','REPLACED'.
replaced (int) - If the order was edited, the order it replaced.
replaced_by (int) - If the order was replaced, the id of the order that replaced it.

User Transactions

Get a list of the account's transactions, ordered by date, in descending order.

POST https://1btcxe.com/api/user-transactions

Parameters:

currency (string) - Three-letter currency code. Will filter by transactions involving this currency. When omitted, all transactions will be displayed.
limit (int) - The amount of transactions to return.
side (string) - Filters transactions by type ("buy" or "sell").

Response:

id (int) - A unique identifier for the transaction.
date (string) - The date string in YYYY-MM-DD format.
btc (float) - The transaction amount in BTC.
side (string) - Can be "buy" or "sell".
price (float) - The price at which the transaction ocurred, in it's native currency.
amount (float) - The transction amount in it's native currency.
fee (float) - The transaction fee in the native currency.
currency (string) - The currency in which the transaction ocurred.

Existing Bitcoin Deposit Addresses

Get a list of the account's existing addresses for receiving Bitcoin.

POST https://1btcxe.com/api/btc-deposit-address/get

Parameters:

limit (int) - The amount of addresses to return.

Response:

address (string) - The address for depositing Bitcoin.
date (string) - The date created in YYYY-MM-DD HH:MM:SS format.

Get New Bitcoin Deposit Addresses

Get a new Bitcoin deposit address for the account.

POST https://1btcxe.com/api/btc-deposit-address/new

Response:

address (string) - The address for depositing Bitcoin.

Get Deposits

Get a list of deposits (BTC or fiat) made to the account, ordered by date, in descending order.

POST https://1btcxe.com/api/deposits/get

Parameters:

currency (string) - Three-letter currency code. Will filter by deposits involving this currency. When omitted, all deposits will be displayed.
limit (int) - The amount of deposits to return.
status (string) - Filters deposits by status ("pending", "completed" or "cancelled").

Response:

id (int) - A unique identifier for the deposit.
date (string) - The date string in YYYY-MM-DD HH:MM:SS format.
currency (string) - The currency of the deposit.
amount (float) - The amount of the deposit, in the deposit currency.
status (string) - The current status of the transaction. Can be "PENDING", "COMPLETED" or "CANCELLED".
account_number (int) - The account number from which the deposit was made (only for fiat deposits).
address (string) - The Bitcoin address from which the deposit was made (only for BTC deposits).

Get Withdrawals

Get a list of withdrawals (BTC or fiat) from the account, ordered by date, in descending order.

POST https://1btcxe.com/api/withdrawals/get

Parameters:

currency (string) - Three-letter currency code. Will filter by withdrawals involving this currency. When omitted, all withdrawals will be displayed.
limit (int) - The amount of withdrawals to return.
status (string) - Filters withdrawals by status ("pending", "completed" or "cancelled").

Response:

id (int) - A unique identifier for the withdrawal.
date (string) - The date string in YYYY-MM-DD HH:MM:SS format.
currency (string) - The currency of the withdrawal.
amount (float) - The amount of the withdrawal, in the withdrawal currency.
status (string) - The current status of the transaction. Can be "PENDING", "COMPLETED" or "CANCELLED".
account_number (int) - The account number to which the withdrawal was made (only for fiat withdrawal).
address (string) - The Bitcoin address to which the withdrawal was made (only for BTC withdrawals).

Place One (or Many) New Orders

Place one or many new orders from your account. To place multiple orders, you can send a multidimensional array called orders, which should contain all the parameters in each array element as specified below.

POST https://1btcxe.com/api/orders/new

Parameters:

side (string) - Can be "buy" or "sell".
type (string) - Can be "market", "limit" or "stop". "stop" orders can contain both a stop_price and limit_price - they will be processed in an OCO (One Cancels the Other) fashion, which means that whichever one is executed first will cancel the other.
currency (string) - Three-letter currency code. The currency in which the order will be placed.
limit_price (float) - The limit price for the order, in the order currency.
stop_price (float) - The stop price for the order, in the order currency. A "stop" order can have both a stop and limit price as explained in "type".
amount (float) - The amount of BTC to buy or sell.
orders (array) - This parameter is used only if you intend to place multiple orders in one API request. It should be an array or JSON string containing all the previous parameters for each element, such that orders[n] = ['side'=>x,'type'=>y,...]. It can be a simple array of HTTP parameters, or can be formatted as JSON.

Response:

transactions (int) - The amount of transactions that ocurred upon placing the order.
new_order (int) - The amount of new orders placed (will return 2 if a stop order has both a limit_price and stop_price defined).
id (int) - A unique identifier for the withdrawal.
side (string) - Can be "buy" or "sell".
type (string) - Can be "market", "limit" or "stop".
amount (float) - The original BTC amount to buy or sell.
amount_remaining (float) - The outstanding (yet to be filled) BTC amount on the order.
price (float) - The current price of the order in its native currency.
avg_price_executed (float) - A weighted average of the prices at which the order has been filled, in it's currency. Zero means it has not yet generated any transactions.
stop_price (float) - If there is the order is a stop order, the price at which the stop will be triggered.
currency (string) - The order's native currency.
status (string) - The order's current status. Possible values are 'ACTIVE','FILLED','CANCELLED_USER','OUT_OF_FUNDS','REPLACED'.
oco (boolean) - If a stop order has both stop and limit prices, this will true since whichever is executed first will cancel the other.

Edit One (or Many) Orders

Edit one or many of the orders that you have placed. To edit multiple orders, you can send a multidimensional array called orders, which should contain all the parameters in each array element as specified below.

POST https://1btcxe.com/api/orders/edit

Parameters:

id (int) - The unique identifier of the order that you wish to edit.
type (string) - Can be "market", "limit" or "stop". "stop" orders can contain both a stop_price and limit_price - they will be processed in an OCO (One Cancels the Other) fashion, which means that whichever one is executed first will cancel the other.
limit_price (float) - The limit price for the order, in the order currency.
stop_price (float) - The stop price for the order, in the order currency. A "stop" order can have both a stop and limit price as explained in "type".
amount (float) - The amount of BTC to buy or sell.
orders (array) - This parameter is used only if you intend to edit multiple orders in one API request. It should be an array or JSON string containing all the previous parameters for each element, such that orders[n] = ['id'=>x,'type'=>y,...]. It can be a simple array of HTTP parameters, or can be formatted as JSON.

Response:

transactions (int) - The amount of transactions that ocurred upon editing the order.
edit_order (int) - The amount of new orders placed (will return 2 if a stop order order has both a limit_price and stop_price defined).
id (int) - A new id for the order (the previous order id will be marked "REPLACED"). This allows for tracking user changes to an order.
side (string) - Can be "buy" or "sell".
type (string) - Can be "market", "limit" or "stop".
amount (float) - The BTC amount remaining on the order at the time it was edited.
amount_remaining (float) - The outstanding (yet to be filled) BTC amount on the order.
price (float) - The current price of the order in its native currency.
avg_price_executed (float) - A weighted average of the prices at which the order has been filled, in it's currency. Zero means it has not yet generated any transactions.
stop_price (float) - If there is the order is a stop order, the price at which the stop will be triggered.
currency (string) - The order's currency.
status (string) - The order's current status. Possible values are 'ACTIVE','FILLED','CANCELLED_USER','OUT_OF_FUNDS','REPLACED'.
replaced (int) - The order it replaced.
oco (boolean) - If a stop order has both stop and limit prices, this will true since whichever is executed first will cancel the other.

Cancel One, Many or ALL Orders

Cancel one or many active orders. To cancel multiple orders, you can send a multidimensional array called orders, which should contain all the parameters in each array element as specified below. To cancel ALL orders, simply send a parameter called all - there is no need to send anything else.

POST https://1btcxe.com/api/orders/cancel

Parameters:

id (int) - The unique identifier of the order that you wish to edit.
orders (array) - This parameter is used only if you intend to get the status of multiple orders in one API call. It should be an array or JSON string containing an id parameter for each element, such that orders[n] = ['id'=>x]. It can be a simple array of HTTP parameters, or can be formatted as JSON.
all (bool) - Sending this parameter will cancel ALL orders. Use with caution!

Response:

id (int) - A unique identifier for the order.
side (string) - Can be "buy" or "sell".
type (string) - Can be "market", "limit" or "stop".
amount (float) - The original BTC amount when the order was placed or edited.
amount_remaining (float) - The outstanding (yet to be filled) BTC amount on the order.
price (float) - The current price of the order in its native currency.
avg_price_executed (float) - A weighted average of the prices at which the order has been filled, in it's currency. Zero means it has not yet generated any transactions.
stop_price (float) - If there is the order is a stop order, the price at which the stop will be triggered.
currency (string) - The order's currency.
status (string) - The order's current status. Possible values are 'ACTIVE','FILLED','CANCELLED_USER','OUT_OF_FUNDS','REPLACED'.
replaced (int) - The order it replaced, if it has been edited.
replaced_by (int) - The order that replaced it, if "REPLACED".

Status of One (or Many) Orders

Obtain the current state of one or many of the orders that have been placed by the account. To get multiple orders, you can send a multidimensional array called orders, which should contain all the parameters in each array element as specified below.

POST https://1btcxe.com/api/orders/status

Parameters:

id (int) - The unique identifier of the order that you wish to edit.
orders (array) - This parameter is used only if you intend to get the status of multiple orders in one API call. It should be an array or JSON string containing an id parameter for each element, such that orders[n] = ['id'=>x]. It can be a simple array of HTTP parameters, or can be formatted as JSON.

Response:

id (int) - A unique identifier for the order.
side (string) - Can be "buy" or "sell".
type (string) - Can be "market", "limit" or "stop".
amount (float) - The original BTC amount when the order was placed or edited.
amount_remaining (float) - The outstanding (yet to be filled) BTC amount on the order.
price (float) - The current price of the order in its native currency.
avg_price_executed (float) - A weighted average of the prices at which the order has been filled, in it's currency. Zero means it has not yet generated any transactions.
stop_price (float) - If there is the order is a stop order, the price at which the stop will be triggered.
currency (string) - The order's currency.
status (string) - The order's current status. Possible values are 'ACTIVE','FILLED','CANCELLED_USER','OUT_OF_FUNDS','REPLACED'.
replaced (int) - The order it replaced, if it has been edited.
replaced_by (int) - The order that replaced it, if "REPLACED".

Make a Withdrawal

To make a withdrawal from your account to an existing Bitcoin address or fiat bank account. Please note, you must link the desired bank account number to your account in the bank accounts page in order for this feature to work. Otherwise, your withdrawals will fail.

POST https://1btcxe.com/api/withdrawals/new

Parameters:

currency (string) - The three-letter abbreviation for the currency that you wish to withdraw. It must match the currency on the account if you are withdrawing fiat.
amount (float) - The amount that you wish to withdraw, in the above currency.
address (string) - For BTC withdrawals, the Bitcoin address to which you wish to withdraw.
account_number (int) - For Fiat withdrawals, the bank account to which you would like to withdraw your currency.

Response:

id (int) - A unique identifier for the withdrawal.
date (string) - The date string in YYYY-MM-DD HH:MM:SS format.
currency (string) - The currency of the withdrawal.
amount (float) - The amount of the withdrawal, in the withdrawal currency.
status (string) - The current status of the transaction. Can be "PENDING", "COMPLETED" or "CANCELLED".
account_number (int) - The account number to which the withdrawal was made (only for fiat withdrawal).
address (string) - The Bitcoin address to which the withdrawal was made (only for BTC withdrawals).

Scroll

API Documentation

Navigation

1BTCXE REST API Documentation

Connecting to the API

Usage

Public API Methods

Stats

Parameters:

Response:

Historical Prices

Parameters:

Response:

Order Book

Parameters:

Response:

Transactions

Parameters:

Response:

Protected API Methods

Obtaining An API Key

Authenticating Your Request

Balances and Info

Response:

Open Orders

Parameters:

Response:

User Transactions

Parameters:

Response:

Existing Bitcoin Deposit Addresses

Parameters:

Response:

Get New Bitcoin Deposit Addresses

Response:

Get Deposits

Parameters:

Response:

Get Withdrawals

Parameters:

Response:

Place One (or Many) New Orders

Parameters:

Response:

Edit One (or Many) Orders

Parameters:

Response:

Cancel One, Many or ALL Orders

Parameters:

Response:

Status of One (or Many) Orders

Parameters:

Response:

Make a Withdrawal

Parameters:

Response:

Navigation

About 1BTCXE

Bitcoin Info