Welcome to BitEx’s documentation!¶
BitEx is a FOSS library for accessing Crypto-exchange APIs in a convenient way.
It extends requests
and implements a standardized set of methods to interact
with exchanges, covering the most commonly used functionality:
Acquiring the order book.
Acquiring the latest ticker.
Acquiring trades.
Placing new orders.
Cancelling orders.
Acquiring an order’s status.
Fetching a wallet’s value.
Fetching a wallet’s deposit address.
Withdrawing coins from the wallet.
Additionally, it provides the option to request endpoints which are not one of the above using a shorthand.
Note
The implementation of additional methods and their naming is dependent on the plugin and its author for the exchange you’re accessing.
Diving right in¶
A minimal, working example:
>>>from bitex import BitexSession, BitexAuth
>>>auth_obj = BitexAuth(key, secret)
>>>session = BitexSession(auth=auth_obj)
>>>session.ticker("exchange_name", "BTCUSD")
<BitexResponse [200 OK]>
If you’d like to access a private endpoint of an API, you’ll likely need
a custom BitexAuth
class, extending its BitexAuth.__call__()
method:
class BitexAuthSubClass(BitexAuth):
def __init__(key, secret):
super(BitexSessionSubclass, self).__init__(auth)
def __call__(request):
request.headers = {'SUPER-SECRET': (self.secret_as_bytes + self.key_as_bytes).encode()}
return request
>>>auth_obj = BitexAuthSubClass(key, secret)
>>>session = BitexSession(auth=auth_obj)
>>>order_options={'price': 100000, 'size': 10, 'type': 'market'}
>>>session.new_order('exchange_name', "BTCUSD", params=order_options)
<BitexResponse [200 OK]>
In the example above, we used bitex’s set of standardized methods for accessing the change. However, you may also request data using the bitex short-hand notation.
Making your life easier: the BitEx URL Short-Hand Notation¶
The short-hand notation unifies urls and aims to make using and writing plugins easier.
The short-hand looks like this:
<exchange>:<instrument>/<endpoint>[/<action>]
exchange refers to the exchange you want to request data from. instrument is either a single currency or a currency pair. endpoint describes the kind of endpoint you’d like to use:
trades
book
ticker
wallet
order
The latter two endpoint types support actions, which are listed below:
wallet actions :
deposit
withdraw
Additionally, a amount parameter is always present on the withdraw action.
order actions:
new
status
cancel
The previous examples would look as follows, if they used the shorthand instead:
>>>auth_obj = BitexAuthSubClass(key, secret)
>>>session = BitexSession(auth=auth_obj)
>>>session.get("SomeExchange:ticker/BTCUSD")
<BitexResponse [200 OK]>
>>>order_options={'price': 100000, 'size': 10, 'type': 'market'}
>>>session.post("SomeExchange:BTCUSD/order/new", params=order_options)
<BitexResponse [200 OK]>
As long as a plugin for SomeExchange is installed, bitex-framework
will convert the
short-hand to a fully-qualified URL under the hood.
-
class
bitex.
BitexHTTPAdapter
(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)[source]¶ Custom HTTP Adapter for
Bitex
.It replaces
requests.Response
as the default response class when building the response, with either an adequate plugin-supplied class orbitex-framework
‘s own defaultBitexResponse
class.-
build_response
(req: bitex.request.BitexPreparedRequest, resp: urllib3.response.HTTPResponse) → bitex.response.BitexResponse[source]¶ Build a
BitexResponse
from the given req and resp.The method is largely identical to
HTTPAdapter.build_response()
, and only differs in the class type used when constructing a response.This class is taken firstly from any valid plugin that supplies an adequate class for the exchange that was queried (as stated in
BitexPreparedRequest.exchange
), orbitex-framework
‘s own defaultBitexResponse
class.- Parameters
req (BitexPreparedRequest) – The
BitexPreparedRequest
used to generate the response.resp (HTTPResponse) – The urllib3 response object.
-
-
class
bitex.
BitexSession
(auth: Optional[bitex.auth.BitexAuth] = None)[source]¶ Custom
requests.Session
object for keep-alive http connections to API endpoints.It expects a
BitexAuth
instance or subclass thereof on instantiation, and assigns it as the default authentication object for any requests made via this class’s instance.Using one of these methods requires an adequate plugin to be installed for exchange. If no such plugin is present, an
bitex.exceptions.MissingPlugin
exception is raised bybitex.request.BitexPreparedRequest
.Using the bitex short-hand is not mandatory, but supported. You may as well construct the entire url of an endpoint you’d like to reach manually, and
bitex-framework
will do the right thing.-
cancel_order
(exchange: str, pair: str, method: str = 'DELETE', **kwargs) → bitex.response.BitexResponse[source]¶ Cancel an order with the given order_id for pair at the given exchange.
- Parameters
exchange (str) – The exchange you’d like to request data from.
pair (str) – The currency pair to place the order for.
order_id – The order id of the order you’d like to cancel.
method (str) – The HTTP method to use when placing the order. This defaults to DELETE.
kwargs (Any) – Additional keyword arguments which are passed on to
requests.Session.request()
.
- Return type
-
deposit
(exchange: str, currency: str, method: str = 'GET', **kwargs) → bitex.response.BitexResponse[source]¶ Request the deposit address of the given currency’s wallet.
-
new_order
(exchange: str, pair: str, method: str = 'POST', **kwargs) → bitex.response.BitexResponse[source]¶ Create a new order for pair at the given exchange.
- Parameters
- Return type
-
order_status
(exchange: str, pair: str, method: str = 'GET', **kwargs) → bitex.response.BitexResponse[source]¶ Request the order status for order_id and pair at the given exchange.
- Parameters
- Return type
-
orderbook
(exchange: str, pair: str, method: str = 'GET', **kwargs) → bitex.response.BitexResponse[source]¶ Request order book data for the given pair at the given exchange.
- Parameters
-
prepare_request
(request: bitex.request.BitexRequest) → bitex.request.BitexPreparedRequest[source]¶ Prepare a
BitexPreparedRequest
object for transmission.This implementation extends
requests.Session.prepare_request
by making a call tobitex.list_loaded_plugins
and checking if we have any plugins that may provide a customBitexPreparedRequest
class.
-
request
(method, url, private=False, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None) → bitex.response.BitexResponse[source]¶ Construct a
BitexRequest
, prepare and send it.url may either be a URL starting with http/https, or a
bitex-framework
short-hand url in the format of <exchange>:<instrument>/<data>/<action>.
-
ticker
(exchange: str, pair: str, method: str = 'GET', **kwargs) → bitex.response.BitexResponse[source]¶ Request ticker data for the given pair at the given exchange.
- Parameters
-
trades
(exchange: str, pair: str, method: str = 'GET', **kwargs) → bitex.response.BitexResponse[source]¶ Request trade data for the given pair at the given exchange.
- Parameters
-
wallet
(exchange: str, currency: str, method: str = 'GET', **kwargs) → bitex.response.BitexResponse[source]¶ Request wallet data for the given pair at the given exchange.
- Parameters
-
withdraw
(exchange: str, currency: str, amount: str, method: str = 'PUT', **kwargs) → bitex.response.BitexResponse[source]¶ Request a withdrawal of the given currency at the given exchange.
- Parameters
exchange (str) – The exchange you’d like to request data from.
currency (str) – The currency to withdraw.
amount (str) – The amount to withdraw.
method (str) – The HTTP method to use when requesting the data. This defaults to GET.
kwargs (Any) – Additional keyword arguments which are passed on to
requests.Session.request()
.
-