Bitstamp API wrapper for Python

Jack Preston

Last update: Mar 9, 2022

Related tags

Third-party APIs Wrappers bitstampy

Overview

NOTICE: THIS REPOSITORY IS NO LONGER ACTIVELY MAINTAINED

It is highly unlikely that I will respond to PRs and questions about usage.

This library was written a long time ago and not kept up to date. It may still hold value for you but it's increasingly out of date with the modern Bitstampy API and Python versions.

I heartily encourage a fork and welcome any contact about taking over ownership - find me at https://twitter.com/unwttng.

bitstampy

Bitstamp API wrapper for Python

Installation

Is pretty bloody easy, as long as you've got pip installed. If you haven't, take a look at the pip documentation - it's worth getting familiar with!

pip install bitstampy

Usage

> from bitstampy import api

Public calls (no API authorisation needed)

Ticker

# Ticker information
> api.ticker()
{
    'timestamp': datetime,   # Datetime
    'volume': decimal,       # Last 24 hours volume
    'last': decimal,         # Last BTC price
    'high': decimal,         # Last 24 hours high
    'low': decimal,          # Last 24 hours low
    'bid': decimal,          # Highest buy order
    'ask': decimal           # Lowest ask order
}

Order Book

# Global order book (see live at https://www.bitstamp.net/market/order_book/)
# Parameters
## [group = True] - Group orders with same price?
##                - boolean
> api.order_book()
{
    'timestamp': datetime,      # Datetime
    'bids': [                   # List of bids
        {
            'price': decimal,   ## Price for bid
            'amount': decimal   ## Amount bid
        }, ...
    ],
    'asks': [                   # List of asks
        {
            'price': decimal,   ## Price for ask
            'amount': decimal   ## Amount asked
        }, ...
    ]
}

Transactions

# Global transactions
# Parameters
## [offset = 0]    - Skip this many transactions before starting return list
##                 - int
## [limit = 100]   - Return this many transactions after the offset
##                 - int
## [sort = 'desc'] - Results are sorted by datetime
##                 - string - api.TRANSACTIONS_SORT_DESCENDING or
##                 -        - api.TRANSACTIONS_SORT_ASCENDING
> api.transactions()
[                           # List of transactions, length 'limit'
    {
        'date': datetime,   ## Datetime
        'tid': string,      ## Transaction ID
        'price': decimal,   ## Transaction price
        'amount': decimal   ## Transaction amount
    }, ...
]

EUR/USD Conversion Rate

# Bitstamp's Dollar to Euro conversion rate
> api.eur_usd_conversion_rate()
{
    'sell': decimal,   # Conversion rate for selling
    'buy': decimal     # Conversion rate for buying
}

Private calls (authorisation required)

Every call after this point requires you to have a working API key and secret associated with your account on Bitstampy. To get one set up, head to your Account > Security > API Access. Choose a set of permissions you'd like the key to have - the meaning of each of these should be pretty clear. After you've created a key, you need to activate it - this is done via a confirmation link in an email.

You'll get an API key and an associated secret. Note these down in your incredibly secure password manager / encrypted system / sneaky hidden notepad of choice, because Bitstampy'll only let you view the API secret for 5 minutes after you activate it ('cus security).

Each of the following API function calls takes three additional parameters - client_id, api_key and api_secret. The API key and secret are obvious, and client_id is your customer ID on Bitstampy (the numerical one). I'll include them in the function prototypes abbreviated as c, k, s.

Let's see the rest of the calls! These are the interesting ones because they get you access to do actual stuff stuff with your account.

Account Balance

# Your account balance
> api.account_balance(c, k, s)
{
    'usd_balance': decimal,     # US Dollar balance
    'btc_balance': decimal,     # Bitcoin balance
    'usd_reserved': decimal,    # US Dollars reserved in open orders
    'btc_reserved': decimal,    # Bitcoins reserved in open orders
    'usd_available': decimal,   # US Dollars available
    'btc_available': decimal,   # Bitcoins available
    'fee': decimal              # Account trading fee (in %)
}

User Transactions

# Your transactions
# Parameters
## [offset = 0]    - Skip this many transactions before starting return list
##                 - int
## [limit = 100]   - Return this many transactions after the offset
##                 - int
## [sort = 'desc'] - Results are sorted by datetime
##                 - string - api.USER_TRANSACTIONS_SORT_DESCENDING or
##                 -        - api.USER_TRANSACTIONS_SORT_ASCENDING
> api.user_transactions(c, k, s)
[                               # List of transactions, length 'limit'
    {
        'datetime': datetime,   ## Datetime
        'id': string,           ## Transaction ID
        'type': string,         ## Transaction type - one of
                                ### api.USER_TRANSACTIONS_TYPE_DEPOSIT,
                                ### api.USER_TRANSACTIONS_TYPE_WITHDRAWAL,
                                ### api.USER_TRANSACTIONS_TYPE_MARKET_TRADE
        'usd': decimal,         ## US Dollar amount
        'btc': decimal,         ## Bitcoin amount
        'fee': decimal,         ## Transaction fee (in %)
        'order_id': decimal     ## Transaction amount
    }, ...
]

Open Orders

# Your open orders
> api.open_orders(c, k, s)
[                               # List of open orders
    {
        'datetime': datetime,   ## Datetime
        'id': string,           ## Order ID
        'type': string,         ## Order type - one of
                                ### api.OPEN_ORDERS_TYPE_BUY,
                                ### api.OPEN_ORDERS_TYPE_SELL
        'price': decimal,       ## Order price
        'amount': decimal       ## Order amount
    }, ...
]

Cancel Order

# Cancel an order
# Parameters
## order_id - ID of order to cancel
##          - string
> api.cancel_order(c, k, s)
True / False   # Returns boolean success

Buy Limit Order

# Place a buy order
## amount - Amount to buy
##        - float
## price  - Price to offer
##        - float
> api.buy_limit_order(c, k, s)
{
    'datetime': datetime,   # Datetime placed
    'id': string,           # Order ID
    'type': string,         # Order type - one of 
                            ## api.BUY_LIMIT_ORDER_TYPE_BUY,
                            ## api.BUY_LIMIT_ORDER_TYPE_SELL
    'price': decimal,       # Placed order price
    'amount': decimal       # Placed order amount
}

Sell Limit Order

# Place a sell order
## amount - Amount to sell
##        - float
## price  - Price to ask for
##        - float
> api.sell_limit_order(c, k, s)
{
    'datetime': datetime,   # Datetime placed
    'id': string,           # Order ID
    'type': string,         # Order type - one of 
                            ## api.SELL_LIMIT_ORDER_TYPE_BUY,
                            ## api.SELL_LIMIT_ORDER_TYPE_SELL
    'price': decimal,       # Placed order price
    'amount': decimal       # Placed order amount
}

Check Bitstamp Code

# Check the value of a bitstamp code
## code - Bitstamp code
##      - string
> api.check_bitstamp_code(c, k, s)
{
    'usd': decimal,   # US Dollar amount in the code
    'btc': decimal    # Bitcoin amount in the code
}

Redeem Bitstamp Code

# Redeem a bitstamp code
## code - Bitstamp code
##      - string
> api.redeem_bitstamp_code(c, k, s)
{
    'usd': decimal,   # US Dollar amount added to account by code
    'btc': decimal    # Bitcoin amount added to account by code
}

Withdrawal Requests

# Get list of withdrawal requests
> api.withdrawal_requests(c, k, s)
[                               # List of withdrawal requests
    {
        'datetime': datetime,   ## Datetime
        'id': string,           ## Withdrawal ID
        'type': string,         ## Request type - one of
                                ### api.WITHDRAWAL_REQUEST_TYPE_SEPA,
                                ### api.WITHDRAWAL_REQUEST_TYPE_BITCOIN,
                                ### api.WITHDRAWAL_REQUEST_TYPE_WIRE,
                                ### api.WITHDRAWAL_REQUEST_TYPE_BITSTAMP_CODE_1,
                                ### api.WITHDRAWAL_REQUEST_TYPE_BITSTAMP_CODE_2,
                                ### api.WITHDRAWAL_REQUEST_TYPE_MTGOX
        'status': string,       ## Request status - one of
                                ### api.WITHDRAWAL_REQUEST_STATUS_OPEN,
                                ### api.WITHDRAWAL_REQUEST_STATUS_IN_PROCESS,
                                ### api.WITHDRAWAL_REQUEST_STATUS_FINISHED,
                                ### api.WITHDRAWAL_REQUEST_STATUS_CANCELLED,
                                ### api.WITHDRAWAL_REQUEST_STATUS_FAILED
        'amount': decimal,      ## Request amount
        'data': string          ## Extra data (specific to type)
    }, ...
]

Bitcoin Withdrawal

# Withdraw bitcoins to an address
## amount  - amount to withdraw in BTC
##         - decimal
## address - bitcoin address to withdraw to
##         - string
> api.bitcoin_withdrawal(c, k, s)
True / False   # Returns boolean success

Bitcoin Deposit Address

# Get your account's address for bitcoin deposits
> api.bitcoin_deposit_address(c, k, s)
# Returns deposit address as string

Unconfirmed Bitcoin Deposits

# Retrieve list of as-yet unconfirmed bitcoin deposits into your account
> api.unconfirmed_bitcoin_deposits(c, k, s)
[                              # List of unconfirmed deposits
    {
        'amount': decimal,     ## Amount deposited
        'address': string,     ## Address deposited to
        'confirmations': int   ## How many confirmations on the deposit so far
    }, ...
]

Comments

Getting "APIError: Invalid nonce"

Hi Jack

Thanks for the API!

I'm trying to do a buy limit order and I'm getting an error. Is this a problem with Bitstampy or just something that I'm doing wrong... sorry to post this here but I could not find your email address.

bitstamp.buy_limit_order(c, k, s, 0.01, ask * 1.10)

Traceback (most recent call last): File "/Users/daniel/bitcoin/coinduit/bank/bank.py", line 17, in bitstamp.buy_limit_order(c, k, s, 0.01, ask * 1.10) File "/Library/Python/2.7/site-packages/bitstampy/api.py", line 62, in buy_limit_order .call(amount=amount, price=price) File "/Library/Python/2.7/site-packages/bitstampy/calls.py", line 86, in call return super(APIPrivateCall, self).call(**params) File "/Library/Python/2.7/site-packages/bitstampy/calls.py", line 57, in call raise APIError(response['error']) APIError: Invalid nonce

Is there something I need to do to set the nonce?

opened by dsmurrell 6
unicode objects must be encoded

maybe it's just me but: from bitstampy import api c='999999' k='xXx' s=b'xXx' api.account_balance(c, k, s)

and I get the error: TypeError: Unicode-objects must be encoded before hashing on pyhton 3.4

opened by vantessel 3
ImportError on Python 3.5

When trying to do 'from bistampy import api' i get 'ImportError: No module named calls'

A simple fix for this was to simply change the first line in api.py from 'import calls' to 'from . import calls'

opened by johan-bjareholt 3
problem with bytes, bytearray ans str

Hi, Tried to run the code on python3, and got this stacktrace. It appears to be a python3 compatability issue - the code runs perfectly on python2 Thankyou

Traceback (most recent call last): File "tr5.py", line 158, in bitstamp_USD_balance=bitstamp_balance(bs_c=bs_c, bs_k=bs_k, bs_s=bs_s, asset="usd_available") File "tr5.py", line 61, in bitstamp_balance bs_data=api.account_balance(bs_c, bs_k, bs_s) File "/home/ubuntu/btc/installstuff/bitstampy/bitstampy/api.py", line 40, in account_balance calls.APIAccountBalanceCall(client_id, api_key, api_secret) File "/home/ubuntu/btc/installstuff/bitstampy/bitstampy/calls.py", line 81, in call self.api_secret, msg=message, digestmod=hashlib.sha256) File "/usr/lib/python3.4/hmac.py", line 144, in new return HMAC(key, msg, digestmod) File "/usr/lib/python3.4/hmac.py", line 42, in init raise TypeError("key: expected bytes or bytearray, but got %r" % type(key).name) TypeError: key: expected bytes or bytearray, but got 'str'

opened by amnonmel 1
Finish off README documentation

Still a couple of API calls which are supported but aren't listed in the README.md documentation. I've been working in the same order as the API documentation page so it's everything after the last documented one to go.
enhancement

opened by unwitting 0

What type to use for client_id, api_key, api_secret

c = '12345'
k = 'xxxxx'
s = 'yyyyy'
api.account_balance(c, k, s)

~/.virtualenvs/bitstamp/lib/python3.6/site-packages/bitstampy/api.py in account_balance(client_id, api_key, api_secret)
     38 def account_balance(client_id, api_key, api_secret):
     39     return (
---> 40         calls.APIAccountBalanceCall(client_id, api_key, api_secret)
     41         .call()
     42     )

~/.virtualenvs/bitstamp/lib/python3.6/site-packages/bitstampy/calls.py in call(self, **params)
     79         message = nonce + self.client_id + self.api_key
     80         signature = hmac.new(
---> 81             self.api_secret, msg=message, digestmod=hashlib.sha256)
     82         signature = signature.hexdigest().upper()
     83         params.update({

~/.virtualenvs/bitstamp/lib/python3.6/hmac.py in new(key, msg, digestmod)
    142     method.
    143     """
--> 144     return HMAC(key, msg, digestmod)

~/.virtualenvs/bitstamp/lib/python3.6/hmac.py in __init__(self, key, msg, digestmod)
     40 
     41         if not isinstance(key, (bytes, bytearray)):
---> 42             raise TypeError("key: expected bytes or bytearray, but got %r" % type(key).__name__)
     43 
     44         if digestmod is None:

TypeError: key: expected bytes or bytearray, but got 'str'

Changed key to bytes :

k = b'xxxxx' Then :

api.account_balance(c, k, s)

TypeError                                 Traceback (most recent call last)
<ipython-input-27-35f3ae0e7115> in <module>()
----> 1 api.account_balance(c, k, s)

~/.virtualenvs/bitstamp/lib/python3.6/site-packages/bitstampy/api.py in account_balance(client_id, api_key, api_secret)
     38 def account_balance(client_id, api_key, api_secret):
     39     return (
---> 40         calls.APIAccountBalanceCall(client_id, api_key, api_secret)
     41         .call()
     42     )

~/.virtualenvs/bitstamp/lib/python3.6/site-packages/bitstampy/calls.py in call(self, **params)
     77     def call(self, **params):
     78         nonce = self._get_nonce()
---> 79         message = nonce + self.client_id + self.api_key
     80         signature = hmac.new(
     81             self.api_secret, msg=message, digestmod=hashlib.sha256)

TypeError: must be str, not bytes

I am rather confused. Could you please clarify the argument types to use for client_id, api_key, api_secret ? Thanks

opened by Salan54 1

Sub-Account support with the Bitstamp API

Now supports transfers from Bitstamp Main account to sub-account and from sub-account to main... Also the nonce is more robust (one decimal place greater)

opened by richardsj 0