What Is API?

Bitstamp application programming interface (API) allows our clients to access and control their accounts, using custom written software.

With the inclusion of the new BTC/EUR currency pair, we've added new endpoints for some API calls (info about specific calls below). The old endpoints are still available and have not changed. We strongly suggest however, that you refer to the v2 API for future references. Please note that API v2 endpoints rounding is different, than the one used on the old endpoints.

Request limits

Do not make more than 8000 requests per 10 minutes or we will ban your IP address. For real time data please refer to the websocket API.

Public Data Functions

Ticker

Passing any GET parameters, will result in your request being rejected.

Hourly ticker

Passing any GET parameters, will result in your request being rejected.

Order book

Transactions

Trading pairs info

OHLC data

EUR/USD conversion rate

API authentication

All private API calls require authentication. We have two authentication possibilities:

V1 authentication method

For a successful authentication you need to provide your API key, a signature and a nonce parameter.

API key

To get an API key, go to "Account", "Security" and then "API Access". Set permissions and click "Generate key".

Nonce

Nonce is a regular integer number. It must be increased with every request you make. Read more about it here. Example: if you set nonce to 1 in your first request, you must set it to at least 2 in your second request. You are not required to start with 1. Maximum value for nonce is 9223372036854775807. A common practice is to use unix time for that parameter.

Signature

Signature is a HMAC-SHA256 encoded message containing nonce, customer ID (can be found here) and API key. The HMAC-SHA256 code must be generated using a secret key that was generated with your API key. This code must be converted to it's hexadecimal representation (64 uppercase characters).

A short code example on how to generate a signature can be seen here:

import hmac
import hashlib

message = nonce + customer_id + api_key
signature = hmac.new(
    API_SECRET,
    msg=message,
    digestmod=hashlib.sha256).hexdigest().upper()

V2 authentication method

We introduced a new authentication method that allows for easier nonce handling and is much safer since all relevant content is signed.

Since we strive for simplicity and better security, we encourage you to use this new authentication method.

For a successful authentication you need to provide the following authorization headers in your request:

This is available only for API V2 endpoints.

Please note that you do not need to set key, signature and nonce request parameters using this authentication method. You also do not need to set Content-Type header if there is no body.

string_to_sign is your signature message. Content-Type should not be added to the string if request.body is empty.

The following have to be combined into a single string:

"BITSTAMP" + " " + api_key + \
HTTP Verb + \
url.host + \
url.path + \
url.query + \
Content-Type + \
X-Auth-Nonce + \
X-Auth-Timestamp + \
X-Auth-Version + \
request.body

Below are the details describing each part of the signature message.

Authentication examples:

import hashlib
import hmac
import time
import requests
import uuid
import sys

client_id = 'client_id'
api_key = 'api_key'
API_SECRET = b'api_key_secret'

timestamp = str(int(round(time.time() * 1000)))
nonce = str(uuid.uuid4())
content_type = 'application/x-www-form-urlencoded'
payload = {'offset': '1'}

if sys.version_info.major >= 3:
    from urllib.parse import urlencode
else:
    from urllib import urlencode

payload_string = urlencode(payload)

# '' (empty string) in message represents any query parameters or an empty string in case there are none
message = 'BITSTAMP ' + api_key + \
    'POST' + \
    'www.bitstamp.net' + \
    '/api/v2/user_transactions/' + \
    '' + \
    content_type + \
    nonce + \
    timestamp + \
    'v2' + \
    payload_string
message = message.encode('utf-8')
signature = hmac.new(API_SECRET, msg=message, digestmod=hashlib.sha256).hexdigest()
headers = {
    'X-Auth': 'BITSTAMP ' + api_key,
    'X-Auth-Signature': signature,
    'X-Auth-Nonce': nonce,
    'X-Auth-Timestamp': timestamp,
    'X-Auth-Version': 'v2',
    'Content-Type': content_type
}
r = requests.post(
    'https://www.bitstamp.net/api/v2/user_transactions/',
    headers=headers,
    data=payload_string
    )
if not r.status_code == 200:
    raise Exception('Status code not 200')

string_to_sign = (nonce + timestamp + r.headers.get('Content-Type')).encode('utf-8') + r.content
signature_check = hmac.new(API_SECRET, msg=string_to_sign, digestmod=hashlib.sha256).hexdigest()
if not r.headers.get('X-Server-Auth-Signature') == signature_check:
    raise Exception('Signatures do not match')

print(r.content)

        

package com.example.AuthenticationExample;

import org.apache.commons.codec.binary.Hex;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.UUID;

public class Authentication {
    public static void main(String[] args) {
        String apiKey = String.format("%s %s", "BITSTAMP", "api_key");
        String apiKeySecret = "api_key_secret";
        String httpVerb = "POST";
        String urlHost = "www.bitstamp.net";
        String urlPath = "/api/v2/user_transactions/";
        String urlQuery = "";
        String timestamp = String.valueOf(System.currentTimeMillis());
        String nonce = UUID.randomUUID().toString();
        String contentType = "application/x-www-form-urlencoded";
        String version = "v2";
        String payloadString = "offset=1";
        String signature = apiKey +
            httpVerb +
            urlHost +
            urlPath +
            urlQuery +
            contentType +
            nonce +
            timestamp +
            version +
            payloadString;

        try {
            SecretKeySpec secretKey = new SecretKeySpec(apiKeySecret.getBytes(), "HmacSHA256");
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(secretKey);
            byte[] rawHmac = mac.doFinal(signature.getBytes());
            signature = new String(Hex.encodeHex(rawHmac)).toUpperCase();

            HttpClient client = HttpClient.newHttpClient();
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://www.bitstamp.net/api/v2/user_transactions/"))
                .POST(HttpRequest.BodyPublishers.ofString(payloadString))
                .setHeader("X-Auth", apiKey)
                .setHeader("X-Auth-Signature", signature)
                .setHeader("X-Auth-Nonce", nonce)
                .setHeader("X-Auth-Timestamp", timestamp)
                .setHeader("X-Auth-Version", version)
                .setHeader("Content-Type", contentType)
                .build();

            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() != 200) {
                throw new RuntimeException("Status code not 200");
            }

            String serverSignature = response.headers().map().get("x-server-auth-signature").get(0);
            String responseContentType = response.headers().map().get("Content-Type").get(0);
            String stringToSign = nonce + timestamp + responseContentType + response.body();

            mac.init(secretKey);
            byte[] rawHmacServerCheck = mac.doFinal(stringToSign.getBytes());
            String newSignature = new String(Hex.encodeHex(rawHmacServerCheck));

            if (!newSignature.equals(serverSignature)) {
                throw new RuntimeException("Signatures do not match");
            }

            System.out.println(response.body());

        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}

        

#include <curl/curl.h>
#include <openssl/hmac.h>
#include <uuid/uuid.h>

#include <iostream>
#include <string>
#include <chrono>
#include <iomanip>

static size_t write_call_back(void *contents, size_t size, size_t nmemb, void *userp)
{
    ((std::string*)userp)->append((char*)contents, size * nmemb);
    return size * nmemb;
}

std::string b2a_hex(char *byte_arr, int n)
{
    const static std::string hex_codes = "0123456789abcdef";
    std::string hex_string;
    for ( int i = 0; i < n ; ++i ) {
        unsigned char bin_value = byte_arr[i];
        hex_string += hex_codes[( bin_value >> 4 ) & 0x0F];
        hex_string += hex_codes[bin_value & 0x0F];
    }
    return hex_string;
}

std::string url_encode(std::string data)
{
    std::string res = data;
    CURL *curl = curl_easy_init();

    if(curl) {
        char *output = curl_easy_escape(curl, data.c_str(), data.length());
        if(output) {
            res = output;
            curl_free(output);
        }
    }

    return res;
}


int main() {

    const std::string api_key = "api_key";
    const std::string api_secret = "api_key_secret";

    std::chrono::milliseconds timestamp = std::chrono::duration_cast< std::chrono::milliseconds >(
            std::chrono::system_clock::now().time_since_epoch()
    );

    uuid_t uuid;
    uuid_string_t nonce;
    uuid_generate(uuid);
    uuid_unparse_lower(uuid, nonce);

    std::string x_auth = "BITSTAMP " + api_key;
    std::string x_auth_nonce = nonce;
    std::string x_auth_timestamp = std::to_string(timestamp.count());
    std::string x_auth_version = "v2";
    std::string content_type = "application/x-www-form-urlencoded";
    std::string payload = url_encode("{offset:1}");

    std::string http_method = "POST";
    std::string url_host = "www.bitstamp.net";
    std::string url_path = "/api/v2/user_transactions/";
    std::string url_query = "";

    std::string data_to_sign = "";
    data_to_sign.append(x_auth);
    data_to_sign.append(http_method);
    data_to_sign.append(url_host);
    data_to_sign.append(url_path);
    data_to_sign.append(url_query);
    data_to_sign.append(content_type);
    data_to_sign.append(x_auth_nonce);
    data_to_sign.append(x_auth_timestamp);
    data_to_sign.append(x_auth_version);
    data_to_sign.append(payload);

    // calculate hmac signature
    unsigned char* result;
    unsigned int len = 20;
    result = (unsigned char*)malloc(sizeof(char) * len);

    HMAC_CTX ctx;
    HMAC_CTX_init(&ctx);

    HMAC_Init_ex(&ctx, api_secret.c_str(), api_secret.length(), EVP_sha256(), NULL);
    HMAC_Update(&ctx, (unsigned char*)data_to_sign.c_str(), data_to_sign.length());
    HMAC_Final(&ctx, result, &len);
    HMAC_CTX_cleanup(&ctx);

    std::string x_auth_signature = b2a_hex( (char *)result, 32 );
    free(result);

    // send request
    CURL *curl;
    CURLcode res;
    std::string read_buffer;

    curl = curl_easy_init();

    if(curl) {

        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, ("X-Auth: " + x_auth).c_str());
        headers = curl_slist_append(headers, ("X-Auth-Signature: " + x_auth_signature).c_str());
        headers = curl_slist_append(headers, ("X-Auth-Nonce: " + x_auth_nonce).c_str());
        headers = curl_slist_append(headers, ("X-Auth-Timestamp: " + x_auth_timestamp).c_str());
        headers = curl_slist_append(headers, ("X-Auth-Version: " + x_auth_version).c_str());
        headers = curl_slist_append(headers, ("Content-Type: " + content_type).c_str());

        std::string url = "https://" + url_host + url_path + url_query;

        curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload.c_str());
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_call_back);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &read_buffer);

        res = curl_easy_perform(curl);

        if(res != CURLE_OK) {
            std::cout << "curl_easy_perform() failed: " << curl_easy_strerror(res) << std::endl;
        }

        std::cout << "curl_easy_perform() response: " << read_buffer << std::endl;

        curl_easy_cleanup(curl);

    }

    return 0;

}
    
        

Private Functions

Account balance

This API call is cached for 10 seconds. This call will be executed on the account (Sub or Main), to which the used API key is bound to.

User transactions

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Crypto Transactions

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

Open orders

This API call is cached for 10 seconds. This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Order status

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Cancel order

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Cancel all orders

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Buy limit order

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Buy market order

By placing a market order you acknowledge that the execution of your order depends on the market conditions and that these conditions may be subject to sudden changes that cannot be foreseen.

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Buy instant order

By placing an instant order you acknowledge that the execution of your order depends on the market conditions and that these conditions may be subject to sudden changes that cannot be foreseen.

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Sell limit order

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Sell market order

By placing a market order you acknowledge that the execution of your order depends on the market conditions and that these conditions may be subject to sudden changes that cannot be foreseen.

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Sell instant order

By placing an instant order you acknowledge that the execution of your order depends on the market conditions and that these conditions may be subject to sudden changes that cannot be foreseen.

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

'Order could not be placed' error response

Should you receive the error response 'Order could not be placed' when trying to place an order, please retry order placement.

Withdrawal requests

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Bitcoin withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

XRP withdrawal

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Litecoin withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

Ether withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

Bitcoin Cash withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

Stellar Lumens withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

Paxos Standard withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

Chainlink withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

OMG Network withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

USD Coin withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

DAI withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

Kyber Network withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

Maker withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

0x withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

Gemini Dollar withdrawal

This call will be executed on the account, to which the used API key is bound to. This call is for your main account only.

Ripple withdrawal

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Bitcoin deposit address

XRP deposit address

This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Litecoin deposit address

Ether deposit address

Bitcoin Cash deposit address

Stellar Lumens deposit address

Paxos Standard deposit address

Chainlink deposit address

OMG Network deposit address

USD Coin deposit address

DAI deposit address

Kyber Network deposit address

Maker deposit address

0x deposit address

Gemini Dollar deposit address

Ripple IOU deposit address

This API call is cached for 60 seconds. This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Unconfirmed bitcoin deposits

This API call is cached for 60 seconds. This call will be executed on the account (Sub or Main), to which the used API key is bound to.

Transfer balance from Sub to Main account

Transfers the desired balance from a Sub Account to your Main Account. Can be called by either the Main Account or a Sub Account, but requires a permission in both cases. The subAccount parameter must be provided if the Main Account is initiating the call. If a Sub Account is making the call, then it is the target Sub Account for the transfer and no further clarification is required. In that case, passing this parameter will have no additional effect.

Transfer balance from Main to Sub Account

Transfers the desired balance from your Main Account to a Sub Account, specified by the subAccount parameter. This call can only be performed by your Main Account.

Open bank withdrawal

Opens a bank withdrawal request (SEPA or international). Withdrawal requests opened via API are automatically confirmed (no confirmation e-mail will be sent), but are processed just like withdrawals opened through the platform's interface. This call can only be performed by your Main Account.

Bank withdrawal status

Checks the status of a bank withdrawal request. This call can only be performed by your Main Account.

Cancel bank withdrawal

Cancels a bank withdrawal request. This call can only be performed by your Main Account.

New liquidation address

Creates new liquidation address which will automatically sell your BTC for specified liquidation_currency.

Liquidation address info

Shows transactions (BTC to liquidation_currency) for liquidation address.