aljaz/bitfinex-api-py
1
0
Fork 0
mirror of https://github.com/aljazceru/bitfinex-api-py.git synced 2025-12-19 06:44:22 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: generate docs

Browse Source
This commit is contained in:
JacobPlaster
2019-10-09 10:41:36 +01:00
committed by Jacob Plaster
parent 3e4beb5f7e
commit d18c4aadf1
3 changed files with 757 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/regenerate_docs.md Normal file
View File

@@ -0,0 +1,19 @@
For development purposes, these are the commands used to generate the doc files.
Install pydocmd:
```
pip3 install pydoc-markdown
```
Generate REST V2 docs:
```
pydocmd simple bfxapi bfxapi.client+ bfxapi.rest.bfx_rest.BfxRest+ > ./docs/rest_v2.md
```
Generate Websocket V2 docs:
```
pydocmd simple bfxapi bfxapi.client+ bfxapi.websockets.bfx_websocket.BfxWebsocket+ > ./docs/ws_v2.md
```

450
docs/rest_v2.md Normal file
View File

@@ -0,0 +1,450 @@
# bfxapi
This module is used to interact with the bitfinex api
# bfxapi.client
This module exposes the core bitfinex clients which includes both
a websocket client and a rest interface client
## Client
```python
Client(self, API_KEY=None, API_SECRET=None, rest_host='https://api-pub.bitfinex.com/v2', ws_host='wss://api-pub.bitfinex.com/ws/2', create_event_emitter=None, logLevel='INFO', dead_man_switch=False, ws_capacity=25, *args, **kwargs)
```
The bfx client exposes rest and websocket objects
# BfxRest
```python
BfxRest(self, API_KEY, API_SECRET, host='https://api-pub.bitfinex.com/v2', loop=None, logLevel='INFO', parse_float=<class 'float'>, *args, **kwargs)
```
BFX rest interface contains functions which are used to interact with both the public
and private Bitfinex http api's.
To use the private api you have to set the API_KEY and API_SECRET variables to your
api key.
## fetch
```python
BfxRest.fetch(self, endpoint, params='')
```
Send a GET request to the bitfinex api
@return reponse
## post
```python
BfxRest.post(self, endpoint, data={}, params='')
```
Send a pre-signed POST request to the bitfinex api
@return response
## get_seed_candles
```python
BfxRest.get_seed_candles(self, symbol, tf='1m')
```
Used by the honey framework, this function gets the last 4k candles.
## get_public_candles
```python
BfxRest.get_public_candles(self, symbol, start, end, section='hist', tf='1m', limit='100', sort=-1)
```
Get all of the public candles between the start and end period.
__Attributes__
- `@param symbol symbol string`: pair symbol i.e tBTCUSD
- `@param secton string`: available values: "last", "hist"
- `@param start int`: millisecond start time
- `@param end int`: millisecond end time
- `@param limit int`: max number of items in response
- `@param tf int`: timeframe inbetween candles i.e 1m (min), ..., 1D (day),
... 1M (month)
- `@param sort int`: if = 1 it sorts results returned with old > new
@return Array [ MTS, OPEN, CLOSE, HIGH, LOW, VOLUME ]
## get_public_trades
```python
BfxRest.get_public_trades(self, symbol, start, end, limit='100', sort=-1)
```
Get all of the public trades between the start and end period.
__Attributes__
- `@param symbol symbol string`: pair symbol i.e tBTCUSD
- `@param start int`: millisecond start time
- `@param end int`: millisecond end time
- `@param limit int`: max number of items in response
@return Array [ ID, MTS, AMOUNT, RATE, PERIOD? ]
## get_public_books
```python
BfxRest.get_public_books(self, symbol, precision='P0', length=25)
```
Get the public orderbook for a given symbol.
__Attributes__
- `@param symbol symbol string`: pair symbol i.e tBTCUSD
- `@param precision string`: level of price aggregation (P0, P1, P2, P3, P4, R0)
- `@param length int`: number of price points ("25", "100")
@return Array [ PRICE, COUNT, AMOUNT ]
## get_public_ticker
```python
BfxRest.get_public_ticker(self, symbol)
```
Get tickers for the given symbol. Tickers shows you the current best bid and ask,
as well as the last trade price.
__Attributes__
- `@param symbols symbol string`: pair symbol i.e tBTCUSD
@return Array [ SYMBOL, BID, BID_SIZE, ASK, ASK_SIZE, DAILY_CHANGE,
DAILY_CHANGE_PERC, LAST_PRICE, VOLUME, HIGH, LOW ]
## get_public_tickers
```python
BfxRest.get_public_tickers(self, symbols)
```
Get tickers for the given symbols. Tickers shows you the current best bid and ask,
as well as the last trade price.
__Attributes__
- `@param symbols Array<string>`: array of symbols i.e [tBTCUSD, tETHUSD]
@return Array [ SYMBOL, BID, BID_SIZE, ASK, ASK_SIZE, DAILY_CHANGE, DAILY_CHANGE_PERC,
LAST_PRICE, VOLUME, HIGH, LOW ]
## get_derivative_status
```python
BfxRest.get_derivative_status(self, symbol)
```
Gets platform information for derivative symbol.
__Attributes__
- `@param derivativeSymbol string`: i.e tBTCF0:USTF0
@return [KEY/SYMBOL, MTS, PLACEHOLDER, DERIV_PRICE, SPOT_PRICE, PLACEHOLDER, INSURANCE_FUND_BALANCE4,
PLACEHOLDER, PLACEHOLDER, FUNDING_ACCRUED, FUNDING_STEP, PLACEHOLDER]
## get_derivative_statuses
```python
BfxRest.get_derivative_statuses(self, symbols)
```
Gets platform information for a collection of derivative symbols.
__Attributes__
- `@param derivativeSymbols Array<string>`: array of symbols i.e [tBTCF0:USTF0 ...] or ["ALL"]
@return [KEY/SYMBOL, MTS, PLACEHOLDER, DERIV_PRICE, SPOT_PRICE, PLACEHOLDER, INSURANCE_FUND_BALANCE4,
PLACEHOLDER, PLACEHOLDER, FUNDING_ACCRUED, FUNDING_STEP, PLACEHOLDER]
## get_wallets
```python
BfxRest.get_wallets(self)
```
Get all wallets on account associated with API_KEY - Requires authentication.
@return Array <models.Wallet>
## get_active_orders
```python
BfxRest.get_active_orders(self, symbol)
```
Get all of the active orders associated with API_KEY - Requires authentication.
__Attributes__
- `@param symbol string`: pair symbol i.e tBTCUSD
@return Array <models.Order>
## get_order_history
```python
BfxRest.get_order_history(self, symbol, start, end, limit=25, sort=-1)
```
Get all of the orders between the start and end period associated with API_KEY
- Requires authentication.
__Attributes__
- `@param symbol string`: pair symbol i.e tBTCUSD
- `@param start int`: millisecond start time
- `@param end int`: millisecond end time
- `@param limit int`: max number of items in response
@return Array <models.Order>
## get_active_position
```python
BfxRest.get_active_position(self)
```
Get all of the active position associated with API_KEY - Requires authentication.
@return Array <models.Position>
## get_order_trades
```python
BfxRest.get_order_trades(self, symbol, order_id)
```
Get all of the trades that have been generated by the given order associated with API_KEY
- Requires authentication.
__Attributes__
- `@param symbol string`: pair symbol i.e tBTCUSD
- `@param order_id string`: id of the order
@return Array <models.Trade>
## get_trades
```python
BfxRest.get_trades(self, symbol, start, end, limit=25)
```
Get all of the trades between the start and end period associated with API_KEY
- Requires authentication.
__Attributes__
- `@param symbol string`: pair symbol i.e tBTCUSD
- `@param start int`: millisecond start time
- `@param end int`: millisecond end time
- `@param limit int`: max number of items in response
@return Array <models.Trade>
## get_funding_offers
```python
BfxRest.get_funding_offers(self, symbol)
```
Get all of the funding offers associated with API_KEY - Requires authentication.
@return Array <models.FundingOffer>
## get_funding_offer_history
```python
BfxRest.get_funding_offer_history(self, symbol, start, end, limit=25)
```
Get all of the funding offers between the start and end period associated with API_KEY
- Requires authentication.
__Attributes__
- `@param symbol string`: pair symbol i.e tBTCUSD
- `@param start int`: millisecond start time
- `@param end int`: millisecond end time
- `@param limit int`: max number of items in response
@return Array <models.FundingOffer>
## get_funding_loans
```python
BfxRest.get_funding_loans(self, symbol)
```
Get all of the funding loans associated with API_KEY - Requires authentication.
@return Array <models.FundingLoan>
## get_funding_loan_history
```python
BfxRest.get_funding_loan_history(self, symbol, start, end, limit=25)
```
Get all of the funding loans between the start and end period associated with API_KEY
- Requires authentication.
__Attributes__
- `@param symbol string`: pair symbol i.e tBTCUSD
- `@param start int`: millisecond start time
- `@param end int`: millisecond end time
- `@param limit int`: max number of items in response
@return Array <models.FundingLoan>
## get_funding_credit_history
```python
BfxRest.get_funding_credit_history(self, symbol, start, end, limit=25)
```
Get all of the funding credits between the start and end period associated with API_KEY
- Requires authentication.
__Attributes__
- `@param symbol string`: pair symbol i.e tBTCUSD
- `@param start int`: millisecond start time
- `@param end int`: millisecond end time
- `@param limit int`: max number of items in response
@return Array <models.FundingCredit>
## submit_funding_offer
```python
BfxRest.submit_funding_offer(self, symbol, amount, rate, period, funding_type='LIMIT', hidden=False)
```
Submits a new funding offer
__Attributes__
- `@param symbol string`: pair symbol i.e fUSD
- `@param amount float`: funding size
- `@param rate float`: percentage rate to charge per a day
- `@param period int`: number of days for funding to remain active once accepted
## submit_cancel_funding_offer
```python
BfxRest.submit_cancel_funding_offer(self, fundingId)
```
Cancel a funding offer
__Attributes__
- `@param fundingId int`: the id of the funding offer
## submit_wallet_transfer
```python
BfxRest.submit_wallet_transfer(self, from_wallet, to_wallet, from_currency, to_currency, amount)
```
Transfer funds between wallets
__Attributes__
- `@param from_wallet string`: wallet name to transfer from i.e margin, exchange
- `@param to_wallet string`: wallet name to transfer to i.e margin, exchange
- `@param from_currency string`: currency symbol to tranfer from i.e BTC, USD
- `@param to_currency string`: currency symbol to transfer to i.e BTC, USD
- `@param amount float`: amount of funds to transfer
## get_wallet_deposit_address
```python
BfxRest.get_wallet_deposit_address(self, wallet, method, renew=0)
```
Get the deposit address for the given wallet and protocol
__Attributes__
- `@param wallet string`: wallet name i.e margin, exchange
- `@param method string`: transfer protocol i.e bitcoin
## create_wallet_deposit_address
```python
BfxRest.create_wallet_deposit_address(self, wallet, method)
```
Creates a new deposit address for the given wallet and protocol.
Previously generated addresses remain linked.
__Attributes__
- `@param wallet string`: wallet name i.e margin, exchange
- `@param method string`: transfer protocol i.e bitcoin
## submit_wallet_withdraw
```python
BfxRest.submit_wallet_withdraw(self, wallet, method, amount, address)
```
Submits a request to withdraw crypto funds to an external wallet.
__Attributes__
- `@param wallet string`: wallet name i.e margin, exchange
- `@param method string`: transfer protocol i.e bitcoin
- `@param amount float`: amount of funds to withdraw
- `@param address string`: external address to withdraw to
## submit_order
```python
BfxRest.submit_order(self, symbol, price, amount, market_type='LIMIT', hidden=False, price_trailing=None, price_aux_limit=None, oco_stop_price=None, close=False, reduce_only=False, post_only=False, oco=False, time_in_force=None, leverage=None, gid=None)
```
Submit a new order
__Attributes__
- `@param gid`: assign the order to a group identifier
- `@param symbol`: the name of the symbol i.e 'tBTCUSD
- `@param price`: the price you want to buy/sell at (must be positive)
- `@param amount`: order size: how much you want to buy/sell,
a negative amount indicates a sell order and positive a buy order
- `@param market_type Order.Type`: please see Order.Type enum
amount decimal string Positive for buy, Negative for sell
- `@param hidden`: if True, order should be hidden from orderbooks
- `@param price_trailing`: decimal trailing price
- `@param price_aux_limit`: decimal auxiliary Limit price (only for STOP LIMIT)
- `@param oco_stop_price`: set the oco stop price (requires oco = True)
- `@param close`: if True, close position if position present
- `@param reduce_only`: if True, ensures that the executed order does not flip the opened position
- `@param post_only`: if True, ensures the limit order will be added to the order book and not
match with a pre-existing order
- `@param oco`: cancels other order option allows you to place a pair of orders stipulating
that if one order is executed fully or partially, then the other is automatically canceled
- `@param time_in_force`: datetime for automatic order cancellation ie. 2020-01-01 10:45:23
- `@param leverage`: the amount of leverage to apply to the order as an integer
## submit_cancel_order
```python
BfxRest.submit_cancel_order(self, orderId)
```
Cancel an existing open order
__Attributes__
- `@param orderId`: the id of the order that you want to update
## submit_update_order
```python
BfxRest.submit_update_order(self, orderId, price=None, amount=None, delta=None, price_aux_limit=None, price_trailing=None, hidden=False, close=False, reduce_only=False, post_only=False, time_in_force=None, leverage=None)
```
Update an existing order
__Attributes__
- `@param orderId`: the id of the order that you want to update
- `@param price`: the price you want to buy/sell at (must be positive)
- `@param amount`: order size: how much you want to buy/sell,
a negative amount indicates a sell order and positive a buy order
- `@param delta`: change of amount
- `@param price_trailing`: decimal trailing price
- `@param price_aux_limit`: decimal auxiliary Limit price (only for STOP LIMIT)
- `@param hidden`: if True, order should be hidden from orderbooks
- `@param close`: if True, close position if position present
- `@param reduce_only`: if True, ensures that the executed order does not flip the opened position
- `@param post_only`: if True, ensures the limit order will be added to the order book and not
match with a pre-existing order
- `@param time_in_force`: datetime for automatic order cancellation ie. 2020-01-01 10:45:23
- `@param leverage`: the amount of leverage to apply to the order as an integer
## set_derivative_collateral
```python
BfxRest.set_derivative_collateral(self, symbol, collateral)
```
Update the amount of callateral used to back a derivative position.
__Attributes__
- `@param symbol of the derivative i.e 'tBTCF0`:USTF0'
- `@param collateral`: amount of collateral/value to apply to the open position

288
docs/ws_v2.md Normal file
View File

@@ -0,0 +1,288 @@
# bfxapi
This module is used to interact with the bitfinex api
# bfxapi.client
This module exposes the core bitfinex clients which includes both
a websocket client and a rest interface client
## Client
```python
Client(self, API_KEY=None, API_SECRET=None, rest_host='https://api-pub.bitfinex.com/v2', ws_host='wss://api-pub.bitfinex.com/ws/2', create_event_emitter=None, logLevel='INFO', dead_man_switch=False, ws_capacity=25, *args, **kwargs)
```
The bfx client exposes rest and websocket objects
# BfxWebsocket
```python
BfxWebsocket(self, API_KEY=None, API_SECRET=None, host='wss://api-pub.bitfinex.com/ws/2', manageOrderBooks=False, dead_man_switch=False, ws_capacity=25, logLevel='INFO', parse_float=<class 'float'>, *args, **kwargs)
```
More complex websocket that heavily relies on the btfxwss module.
This websocket requires authentication and is capable of handling orders.
https://github.com/Crypto-toolbox/btfxwss
### Subscribable events:
- `all` (array|json): listen for all messages coming through
- `connected:` () called when a connection is made
- `disconnected`: () called when a connection is ended (A reconnect attempt may follow)
- `stopped`: () called when max amount of connection retries is met and the socket is closed
- `authenticated` (): called when the websocket passes authentication
- `notification` (Notification): incoming account notification
- `error` (array): error from the websocket
- `order_closed` (Order, Trade): when an order has been closed
- `order_new` (Order, Trade): when an order has been created but not closed. Note: will not be called if order is executed and filled instantly
- `order_confirmed` (Order, Trade): When an order has been submitted and received
- `wallet_snapshot` (array[Wallet]): Initial wallet balances (Fired once)
- `order_snapshot` (array[Order]): Initial open orders (Fired once)
- `positions_snapshot` (array): Initial open positions (Fired once)
- `wallet_update` (Wallet): changes to the balance of wallets
- `status_update` (json): new platform status info
- `seed_candle` (json): initial past candle to prime strategy
- `seed_trade` (json): initial past trade to prime strategy
- `funding_offer_snapshot` (array): opening funding offer balances
- `funding_loan_snapshot` (array): opening funding loan balances
- `funding_credit_snapshot` (array): opening funding credit balances
- `balance_update` (array): when the state of a balance is changed
- `new_trade` (array): a new trade on the market has been executed
- `trade_update` (array): a trade on the market has been updated
- `new_candle` (array): a new candle has been produced
- `margin_info_updates` (array): new margin information has been broadcasted
- `funding_info_updates` (array): new funding information has been broadcasted
- `order_book_snapshot` (array): initial snapshot of the order book on connection
- `order_book_update` (array): a new order has been placed into the ordebrook
- `subscribed` (Subscription): a new channel has been subscribed to
- `unsubscribed` (Subscription): a channel has been un-subscribed
## ERRORS
dict() -> new empty dictionary
dict(mapping) -> new dictionary initialized from a mapping object's
(key, value) pairs
dict(iterable) -> new dictionary initialized as if via:
d = {}
for k, v in iterable:
d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs
in the keyword argument list. For example: dict(one=1, two=2)
## enable_flag
```python
BfxWebsocket.enable_flag(self, flag)
```
Enable flag on websocket connection
__Attributes__
- `flag (int)`: int flag value
## subscribe_order_book
```python
BfxWebsocket.subscribe_order_book(self, symbol)
```
Subscribe to an orderbook data feed
__Attributes__
- `@param symbol`: the trading symbol i.e 'tBTCUSD'
## subscribe_candles
```python
BfxWebsocket.subscribe_candles(self, symbol, timeframe)
```
Subscribe to a candle data feed
__Attributes__
- `@param symbol`: the trading symbol i.e 'tBTCUSD'
## subscribe_trades
```python
BfxWebsocket.subscribe_trades(self, symbol)
```
Subscribe to a trades data feed
__Attributes__
- `@param symbol`: the trading symbol i.e 'tBTCUSD'
## subscribe_ticker
```python
BfxWebsocket.subscribe_ticker(self, symbol)
```
Subscribe to a ticker data feed
__Attributes__
- `@param symbol`: the trading symbol i.e 'tBTCUSD'
## subscribe_derivative_status
```python
BfxWebsocket.subscribe_derivative_status(self, symbol)
```
Subscribe to a status data feed
__Attributes__
- `@param symbol`: the trading symbol i.e 'tBTCUSD'
## subscribe
```python
BfxWebsocket.subscribe(self, *args, **kwargs)
```
Subscribe to a new channel
__Attributes__
- `@param channel_name`: the name of the channel i.e 'books', 'candles'
- `@param symbol`: the trading symbol i.e 'tBTCUSD'
- `@param timeframe`: sepecifies the data timeframe between each candle (only required
for the candles channel)
## unsubscribe
```python
BfxWebsocket.unsubscribe(self, *args, **kwargs)
```
Unsubscribe from the channel with the given chanId
__Attributes__
- `@param onComplete`: function called when the bitfinex websocket resoponds with
a signal that confirms the subscription has been unsubscribed to
## resubscribe
```python
BfxWebsocket.resubscribe(self, *args, **kwargs)
```
Unsubscribes and then subscribes to the channel with the given Id
This function is mostly used to force the channel to produce a fresh snapshot.
## unsubscribe_all
```python
BfxWebsocket.unsubscribe_all(self, *args, **kwargs)
```
Unsubscribe from all channels.
## resubscribe_all
```python
BfxWebsocket.resubscribe_all(self, *args, **kwargs)
```
Unsubscribe and then subscribe to all channels
## submit_order
```python
BfxWebsocket.submit_order(self, *args, **kwargs)
```
Submit a new order
__Attributes__
- `@param gid`: assign the order to a group identifier
- `@param symbol`: the name of the symbol i.e 'tBTCUSD
- `@param price`: the price you want to buy/sell at (must be positive)
- `@param amount`: order size: how much you want to buy/sell,
a negative amount indicates a sell order and positive a buy order
- `@param market_type Order.Type`: please see Order.Type enum
amount decimal string Positive for buy, Negative for sell
- `@param hidden`: if True, order should be hidden from orderbooks
- `@param price_trailing`: decimal trailing price
- `@param price_aux_limit`: decimal auxiliary Limit price (only for STOP LIMIT)
- `@param oco_stop_price`: set the oco stop price (requires oco = True)
- `@param close`: if True, close position if position present
- `@param reduce_only`: if True, ensures that the executed order does not flip the opened position
- `@param post_only`: if True, ensures the limit order will be added to the order book and not
match with a pre-existing order
- `@param oco`: cancels other order option allows you to place a pair of orders stipulating
that if one order is executed fully or partially, then the other is automatically canceled
- `@param time_in_force`: datetime for automatic order cancellation ie. 2020-01-01 10:45:23
- `@param leverage`: the amount of leverage to apply to the order as an integer
- `@param onConfirm`: function called when the bitfinex websocket receives signal that the order
was confirmed
- `@param onClose`: function called when the bitfinex websocket receives signal that the order
was closed due to being filled or cancelled
## update_order
```python
BfxWebsocket.update_order(self, *args, **kwargs)
```
Update an existing order
__Attributes__
- `@param orderId`: the id of the order that you want to update
- `@param price`: the price you want to buy/sell at (must be positive)
- `@param amount`: order size: how much you want to buy/sell,
a negative amount indicates a sell order and positive a buy order
- `@param delta`: change of amount
- `@param price_trailing`: decimal trailing price
- `@param price_aux_limit`: decimal auxiliary Limit price (only for STOP LIMIT)
- `@param hidden`: if True, order should be hidden from orderbooks
- `@param close`: if True, close position if position present
- `@param reduce_only`: if True, ensures that the executed order does not flip the opened position
- `@param post_only`: if True, ensures the limit order will be added to the order book and not
match with a pre-existing order
- `@param time_in_force`: datetime for automatic order cancellation ie. 2020-01-01 10:45:23
- `@param leverage`: the amount of leverage to apply to the order as an integer
- `@param onConfirm`: function called when the bitfinex websocket receives signal that the order
was confirmed
- `@param onClose`: function called when the bitfinex websocket receives signal that the order
was closed due to being filled or cancelled
## cancel_order
```python
BfxWebsocket.cancel_order(self, *args, **kwargs)
```
Cancel an existing open order
__Attributes__
- `@param orderId`: the id of the order that you want to update
- `@param onConfirm`: function called when the bitfinex websocket receives signal that the
order
was confirmed
- `@param onClose`: function called when the bitfinex websocket receives signal that the order
was closed due to being filled or cancelled
## cancel_order_group
```python
BfxWebsocket.cancel_order_group(self, *args, **kwargs)
```
Cancel a set of orders using a single group id.
## cancel_all_orders
```python
BfxWebsocket.cancel_all_orders(self, *args, **kwargs)
```
Cancel all existing open orders
This function closes all open orders.
## cancel_order_multi
```python
BfxWebsocket.cancel_order_multi(self, *args, **kwargs)
```
Cancel existing open orders as a batch
__Attributes__
- `@param ids`: an array of order ids
- `@param gids`: an array of group ids