API - Bitvolo Web Services

The Bitvolo API lets you perform advanced functions and automate the Bitvolo system (e.g. create new transactions, find an existing transaction). To use the API you must be familiar with a programming language such as PHP, Java, Ruby or ASP.NET.

Authentication and security

API Key Click this button to get your API key. You will need it to authenticate all calls made to the API

API calls are by default only protected by your secret API key. Never use this key in client-side scripts (e.g. javascript) and make sure it's well protected. Use this key only with the SSL-protected endpoint listed below. For extra security, API keys can be protected by only allowing calls from specified IP addresses and/or by allowing calls only to specific methods. Another recommended security measure is usage of the hash key. If enabled, all calls must include the parameter hash_timestamp with the current timestamp at the time of making the call AND the parameter hash_key which is the MD5 hash of a text which includes both the secret hash key and timestamp. See the Request format section below for details.

Request format

The API uses the REST request format: a simple GET or POST HTTP action. The REST end point URL is: https://bitvolo.com/rest/

Here's a sample test request: https://bitvolo.com/rest/?method=api_test

Required parameters

All API requests require the following parameters:
method - this is the method being called
api_key - your API key (note: the API key is required for all methods except api_test). Click here to get your key

Other required parameters - only when the hash key is enabled

hash_timestamp int - this is the current timestamp (seconds since the Unix Epoch: January 1 1970 00:00:00 GMT)
hash_key string - MD5 hash of the concatenated string containing: the hash key, hash_timestamp and method parameters (without any separating character). Make sure the timestamp included in the hash key calculation is exactly the same as the hash_timestamp parameter and that the time is correct. For example, a PHP call can be made as follows in case your API key is ABC and the hash key is DEF:
$hash_timestamp = time();
$output = file_get_contents("https://bitvolo.com/rest/?method=get_account_info&api_key=ABC&hash_timestamp=" . $hash_timestamp . "&hash_key=" . md5("DEF" . $hash_timestamp . "get_account_info"))

Optional parameters

language - by specifying a 2-letter (ISO 639-1) language code (all capital letters e.g. EN, DE, FR, ES, IT) you can change the language of the text values returned in the data key

Response format

The Bitvolo API uses JSON (JavaScript Object Notation) as the response format. This is one of the most popular data formats (more info about this format at json.org) fully supported by all popular scripting languages. The response uses a named array for the output data with text-based keys.

Successful responses

Here's a sample response (returned by the api_test method):
{"data":"API Test Response","response_code":0,"response_message":"Method api_test executed successfully."}

Successful responses will contain the response data in the data key. This is usually another named array but in the response above, it's a simple string 'API Test response'.

The response_code key will always contain the value of 0 (success) and response_message will say Method xyz executed successfully.

Failure responses

Failure responses will contain one of the following failure codes in the response_code key:
1 - authentication error (e.g. invalid API key) or invalid method
3 - invalid input data
4 - other error from the method you're calling
5 - call rejected because of API overuse; please see below for the allowed limits
6 - fatal error (could occur e.g. if the call takes too long to complete)


API Methods

The following API methods are currently available:

Accounts

get_account_info Returns information for given account
set_account_address Sets a new receiving address for given coin. Note that you cannot pass network tokens here, e.g. for Stellar/MOBI, you can only set the address for the base coin (XLM). Use set_network_tokens to specify which tokens you'll accept within given network (e.g. Stellar).
set_network_tokens Use this function to set the tokens you will be accepting for given network. Currently you can use tokens with the following networks: ETH

Transactions

confirm_transaction This method confirms a pending transaction. You must pass one of the following parameters which identify the transaction: transaction_id or reference_number. You can optionally assign a transaction hash to the transaction.
create_transaction Use this method instead of our standard UI integration in order to create a new pending transaction in Bitvolo. The transaction price can be specified in a cryptocurrency or in a fiat currency in which case it's converted to the cryptocurrency and the amount to be sent is returned by this method.
get_transaction_info Fetches information of a pending or completed transaction. You must pass one of the following parameters which identify the transaction: transaction_id, reference_number or hash.
list_completed_transactions Lists all completed transactions that were created within given time period. A maximum of 500 transactions will be listed. For further items use the 'page' parameter
list_pending_transactions Lists all pending transactions that were created within given time period. A maximum of 500 transactions will be listed. For further items use the 'page' parameter

Sample code

You'll find a PHP sample in the list_completed_transactions function.

API playground

You'll find the API playground where you can easily test any API function here

API usage limits

The below limits are set by default. Please contact us if you need higher limits with a detailed explanation of your planned API usage.

The API should not receive simultaneous calls for a single API key. If this happens, the remaining calls will always wait for the original call to complete before being executed. You should therefore never do simultaneous calls, do only one at a time. If you do API calls triggered by user action (e.g. API call on your webpage), this can of course happen but will not cause any issues. The second (and third etc..) simultaneous call will simply get a 1-sec delay before being executed. Your calls will not fail due to this restriction.

We also use a rate limit throttling. In case of a heavy usage in a 10-second period, we'll add delays (1-4 seconds based on total running time in the previous 10 seconds). Also here your calls will not fail but will simply be delayed.

One reason your calls can fail with the error code 5 is if you exceed the usage limits: