• BTC/USD
    1. BTC/EUR
    2. EUR/USD
  • 575.02 USD

Bitstamp

CELEBRATING 5 YEARSMenu
Show menu

API

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 600 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.

Request
GEThttps://www.bitstamp.net/api/ticker/ (returns data for the BTC/USD currency pair)
GEThttps://www.bitstamp.net/api/v2/ticker/btcusd/API v2
GEThttps://www.bitstamp.net/api/v2/ticker/btceur/API v2
GEThttps://www.bitstamp.net/api/v2/ticker/eurusd/API v2
Response (JSON)
lastLast BTC price.
highLast 24 hours price high.
lowLast 24 hours price low.
vwapLast 24 hours volume weighted average price.
volumeLast 24 hours volume.
bidHighest buy order.
askLowest sell order.
timestampUnix timestamp date and time.
openFirst price of the day.

Hourly ticker

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

Request
GEThttps://www.bitstamp.net/api/ticker_hour/ (returns data for the BTC/USD currency pair)
GEThttps://www.bitstamp.net/api/v2/ticker_hour/btcusd/API v2
GEThttps://www.bitstamp.net/api/v2/ticker_hour/btceur/API v2
GEThttps://www.bitstamp.net/api/v2/ticker_hour/eurusd/API v2
Response (JSON)
Returns a JSON dictionary like the ticker call, with the calculated values being from within an hour.

Order book

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

Request
GEThttps://www.bitstamp.net/api/order_book/ (returns data for the BTC/USD currency pair)
GEThttps://www.bitstamp.net/api/v2/order_book/btcusd/API v2
GEThttps://www.bitstamp.net/api/v2/order_book/btceur/API v2
GEThttps://www.bitstamp.net/api/v2/order_book/eurusd/API v2
Response (JSON)
Returns a JSON dictionary with "bids" and "asks". Each is a list of open orders and each order is represented as a list holding the price and the amount.

Transactions

Request
GEThttps://www.bitstamp.net/api/transactions/ (returns data for the BTC/USD currency pair)
GEThttps://www.bitstamp.net/api/v2/transactions/btcusd/API v2
GEThttps://www.bitstamp.net/api/v2/transactions/btceur/API v2
GEThttps://www.bitstamp.net/api/v2/transactions/eurusd/API v2
Request parameters
time (Optional)The time interval from which we want the transactions to be returned. Possible values are minute, hour (default) or day.
Response (JSON) - descending list of transactions. Every transaction dictionary contains:
dateUnix timestamp date and time.
tidTransaction ID.
priceBTC price.
amountBTC amount.
type0 (buy) or 1 (sell).

EUR/USD conversion rate

Request
GEThttps://www.bitstamp.net/api/eur_usd/
Response (JSON)
buyBuy conversion rate.
sellSell conversion rate.

API authentication

All private API calls require authentication. 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. 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:

Python
import hmac
import hashlib

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

Authentication errors

API key not foundCheck your API key value
IP address not allowedThis IP address has no permission to use this API key
No permission foundAPI key hasn't got permission for calling this function
Invalid nonceCheck your nonce value. It must be greater than last nonce used
Invalid signaturePosted signature doesn't match with ours
Authentication failedCan't find customer with selected API key
Missing key, signature and nonce parametersParameters were not posted in API request

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.

Request
POSThttps://www.bitstamp.net/api/balance/
POSThttps://www.bitstamp.net/api/v2/balance/API v2
POSThttps://www.bitstamp.net/api/v2/balance/btcusd/API v2
POSThttps://www.bitstamp.net/api/v2/balance/btceur/API v2
POSThttps://www.bitstamp.net/api/v2/balance/eurusd/API v2
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
Response (JSON)
usd_balanceUSD balance.
btc_balanceBTC balance.
eur_balanceEUR balance.
usd_reservedUSD reserved.
btc_reservedBTC reserved.
eur_reservedEUR reserved.
usd_availableUSD available for trading.
btc_availableBTC available for trading.
eur_availableEUR available for trading.
If https://www.bitstamp.net/api/v2/balance/
btcusd_feeCustomer BTC/USD trading fee.
btceur_feeCustomer BTC/EUR trading fee.
eurusd_feeCustomer EUR/USD trading fee.
Other
feeCustomer trading fee.

Balance errors

Authentication errors

User transactions

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

Request
POSThttps://www.bitstamp.net/api/user_transactions/ (returns all transactions)
POSThttps://www.bitstamp.net/api/v2/user_transactions/ (returns all transactions)API v2
POSThttps://www.bitstamp.net/api/v2/user_transactions/btcusd/API v2
POSThttps://www.bitstamp.net/api/v2/user_transactions/btceur/API v2
POSThttps://www.bitstamp.net/api/v2/user_transactions/eurusd/API v2
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
offsetSkip that many transactions before returning results (default: 0).
limitLimit result to that many transactions (default: 100; maximum: 1000).
sortSorting by date and time: asc - ascending; desc - descending (default: desc).
Response (JSON): success - Returns a descending list of transactions, represented as dictionaries.
datetimeDate and time.
idTransaction ID.
typeTransaction type: 0 - deposit; 1 - withdrawal; 2 - market trade; 14 - sub account transfer.
usdUSD amount.
eur (v2 calls only)EUR amount.
btcBTC amount.
btc_usd (or btc_eur if available)Exchange rate.
feeTransaction fee.
order_idExecuted order ID.
Response (JSON): failure
status (v2 calls only)"error"
reason (v2 calls only)The reason for the error.

User_transactions errors

Authentication errors
Invalid offsetOffset should be positive number
Limit too largeMax value of limit parameter is 1000
Invalid limitLimit parameter should be number from 1 to 1000
Invalid sort parameterSort parameter can only be 'asc' or 'desc'

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.

Request
POSThttps://www.bitstamp.net/api/open_orders/ (returns data for the BTC/USD currency pair)
POSThttps://www.bitstamp.net/api/v2/open_orders/btcusd/API v2
POSThttps://www.bitstamp.net/api/v2/open_orders/btceur/API v2
POSThttps://www.bitstamp.net/api/v2/open_orders/eurusd/API v2
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
Response (JSON): success - Returns a list of open orders, where each order is represented as a dictionary.
idTransaction ID.
datetimeDate and time.
type Type: 0 - buy; 1 - sell.
price Price.
amountAmount.
Response (JSON): failure
status (v2 calls only)"error"
reason (v2 calls only)The reason for the error.

Open_orders errors

Authentication errors

Order status

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

Request
POSThttps://www.bitstamp.net/api/order_status/
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
idOrder ID.
Response (JSON)
status In Queue, Open or Finished.
transactionsEach transaction in dictionary is represented as a list of tid, usd, price, fee, btc, datetime and type (0 - deposit; 1 - withdrawal; 2 - market trade).

Order_status errors

Authentication errors
Missing id POST paramId parameter missing
Invalid order idOrder id parameter can only be number
Order not foundOrder with that id was not found in our system

Cancel order

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

Request
POSThttps://www.bitstamp.net/api/cancel_order/
POSThttps://www.bitstamp.net/api/v2/cancel_order/API v2
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
idOrder ID.
Response (JSON): success
If https://www.bitstamp.net/api/v2/cancel_order/
idOrder id.
amountOrder amount.
priceOrder price.
typeOrder type.
If https://www.bitstamp.net/api/cancel_order/
"True"Order has been found and canceled.
Response (JSON): failure
errorThe reason for the error.

Cancel_order errors

Authentication errors
Missing id POST paramId parameter missing
Invalid order idOrder id parameter can only be number
Order not foundOrder with that id was not found in our system

Cancel all orders

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

Request
POSThttps://www.bitstamp.net/api/cancel_all_orders/
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
Response (JSON)
This call will cancel all open orders.Returns "true" if all orders have been canceled, "false" if it failed.

Cancel_all_orders errors

Authentication errors

Buy limit order

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

Request
POSThttps://www.bitstamp.net/api/buy/ (sets the order for the BTC/USD currency pair)
POSThttps://www.bitstamp.net/api/v2/buy/btcusd/API v2
POSThttps://www.bitstamp.net/api/v2/buy/btceur/API v2
POSThttps://www.bitstamp.net/api/v2/buy/eurusd/API v2
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
amountAmount.
pricePrice.
limit_priceIf the order gets executed, a new sell order will be placed, with "limit_price" as its price.
Response (JSON): success
idOrder ID.
datetimeDate and time.
type0 (buy) or 1 (sell).
pricePrice.
amountAmount.
Response (JSON): failure
status (v2 calls only)"error"
reason (v2 calls only)The reason for the error.

Buy errors

Authentication errors
Missing amount and/or price POST parametersMissing one or both parameters
'parameter': Enter a number. Use "." as a decimal point.'parameter' can only be number
Minimum order size is 5 USDOrder value must be at least $5
Price is more than 20% above market price.Order price must not exceed 20% of current price
You need 'order_value' USD to open that order. You have only 'available_fiat' USD available. Check your account balance for details.Account has less 'available_fiat' that are required to make this order
Sell if executed price must be higher than buy price.'limit_price' must be larger than 'price' parameter

Sell limit order

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

Request
POSThttps://www.bitstamp.net/api/sell/ (sets the order for the BTC/USD currency pair)
POSThttps://www.bitstamp.net/api/v2/sell/btcusd/API v2
POSThttps://www.bitstamp.net/api/v2/sell/btceur/API v2
POSThttps://www.bitstamp.net/api/v2/sell/eurusd/API v2
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
amountAmount.
pricePrice.
limit_priceIf the order gets executed, a new buy order will be placed, with "limit_price" as its price.
Response (JSON): success
idOrder ID.
datetimeDate and time.
type0 (buy) or 1 (sell).
pricePrice.
amountAmount.
Response (JSON): failure
status (v2 calls only)"error"
reason (v2 calls only)The reason for the error.

Sell errors

Authentication errors
Missing amount and/or price POST parametersMissing one or both parameters
'parameter': Enter a number. Use "." as a decimal point.'parameter' can only be number
Minimum order size is $5Order value must be at least $5
Price is more than 20% below market price.Order price must not exceed 20% of current price
You have only 'available_btc' BTC available. Check your account balance for details.Account has less 'available_btc' that are required to make this order
Buy if executed price must be lower than sell price.'limit_price' must be lower than 'price' parameter

Withdrawal requests

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

Request
POSThttps://www.bitstamp.net/api/withdrawal_requests/
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
Response (JSON)
idOrder ID.
datetimeDate and time.
type0 (SEPA), 1 (bitcoin) or 2(WIRE transfer).
amountAmount.
status0 (open), 1 (in process), 2 (finished), 3 (canceled) or 4 (failed).
dataAdditional withdrawal request data.

Withdrawal_requests errors

Authentication errors

Bitcoin withdrawal

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

Request
POSThttps://www.bitstamp.net/api/bitcoin_withdrawal/
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
amountBitcoin amount.
addressBitcoin address.
instant0 (false) or 1 (true). If the destination address supports BitGo Instant deposits and you need instant delivery of Bitcoins with zero confirmations. Additional fees apply.
Response (JSON)
idWithdrawal ID.

Bitcoin_withdrawal errors

Authentication errors
Missing amount and/or address POST parametersOne or both parameters missing
Instant parameter needs to be an integer (0 - false or 1 - true)Instant parameter can only be 0 or 1
User not verifiedYou need to verify account before withdrawal
Bitcoin withdrawals are currently unavailable for your account.Contact support for additional information.
Not allowed to withdraw to specified bitcoin addressAPI key is set for withdrawing to another bitcoin address
Ensure this value is greater than or equal to 0.00006000Minimum withdrawal amount is 0.00006
Ensure this value has at least 25 characters (it has x)
Ensure this value has at most 34 characters (it has x)
Address parameter must be between 25 and 34 characters long
Enter a number. Use "." as a decimal point.Amount parameter can only be number
You have only 'available' BTC available. Check your account balance for details.Account has less 'available' BTC that are required to make this withdrawal

Bitcoin deposit address

Request
POSThttps://www.bitstamp.net/api/bitcoin_deposit_address/
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
Response (JSON)
Returns your bitcoin deposit address.

Bitcoin_deposit_address errors

Authentication errors

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.

Request
POSThttps://www.bitstamp.net/api/unconfirmed_btc/
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
Response (JSON) - list of unconfirmed bitcoin transactions. Each transaction is represented as dictionary
amountBitcoin amount.
addressDeposit address used.
confirmationsNumber of confirmations.

Unconfirmed_btc errors

Authentication errors

Ripple withdrawal

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

Request
POSThttps://www.bitstamp.net/api/ripple_withdrawal/
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
amountCurrency amount.
addressBitcoin address.
currencyCurrency.
Response (JSON)
Returns "true" if successful.

Ripple_withdrawal errors

Authentication errors
Missing amount and/or address and/or currency POST parametersOne or all parameters are missing
User not verifiedYou need to verify account before withdrawal
Ripple withdrawals are currently unavailable for your account.Contact support for additional information.
Ensure this value has at least 25 characters (it has x)
Ensure this value has at most 50 characters (it has x)
Address parameter must be between 25 and 50 characters long
'parameter': Enter a number. Use "." as a decimal point.'parameter' can only be number
You have only 'available' 'currency' available. Check your account balance for details.Account has less 'available' 'currency' that are required to make this withdrawal

Ripple 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.

Request
POSThttps://www.bitstamp.net/api/ripple_address/
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
Response (JSON)
Returns your ripple deposit address.

Ripple_address errors

Authentication errors

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.

Request
POSThttps://www.bitstamp.net/api/v2/transfer-to-main/API v2
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
amountAmount.
currencyCurrency.
subAccount (Optional)The Sub Account unique identifier.
Response (JSON)
status"ok" or "error"
reason (available only if status is "error")Additional error info.

Transfer-to-main errors

Authentication errors
'parameter': Enter a number. Use "." as a decimal point.'parameter' can only be number
You have only 'available' 'currency' available. Check your account balance for details.Account has less 'available' 'currency' that are required to make this transfer
Select a valid choice. X is not one of the available choices.X is not valid currency. Possible choices BTC, USD, EUR.
Sub account with identifier "X" does not exist.Can't find sub account with id X.

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.

Request
POSThttps://www.bitstamp.net/api/v2/transfer-from-main/API v2
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
amountAmount.
currencyCurrency.
subAccountThe Sub Account unique identifier.
Response (JSON)
status"ok" or "error"
reason (available only if status is "error")Additional error info.

Transfer-from-main errors

Authentication errors
'parameter': Enter a number. Use "." as a decimal point.'parameter' can only be number
You have only 'available' 'currency' available. Check your account balance for details.Account has less 'available' 'currency' that are required to make this transfer
Select a valid choice. X is not one of the available choices.X is not valid currency. Possible choices BTC, USD, EUR.
Sub account with identifier "X" does not exist.Can't find sub account with id X.