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

Bitstamp

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

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()

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.
feeCustomer trading fee.

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.

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.

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

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/
Request parameters
keyAPI key.
signatureSignature.
nonceNonce.
idOrder ID.
Response (JSON)
Returns "true" if order has been found and canceled.

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.

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.

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.

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.

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 deposit address

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

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.

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

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