bitbank-sdk

Python SDK for the bitbank REST API.

Market data (ticker, depth, candles, transactions) and trading (orders, cancellations, trade history) in one dependency-light package.

Installation

pip install git+https://github.com/tomoking2004/bitbank-sdk.git

Quick start

import os
from bitbank import fetch_ticker, fetch_depth, fetch_recent_candles
from bitbank import fetch_assets, create_limit_order

api_key = os.environ["BITBANK_API_KEY"]
api_secret = os.environ["BITBANK_API_SECRET"]

# Public — no credentials required
ticker = fetch_ticker("btc_jpy")
depth = fetch_depth("btc_jpy")

# Chart data: the most recent 200 one-hour candles
# Each entry is [open, high, low, close, volume, timestamp(ms)]
candles = fetch_recent_candles("btc_jpy", "1hour", limit=200)

# Private — API key and secret required
assets = fetch_assets(api_key, api_secret)

order = create_limit_order(
    api_key, api_secret,
    pair="btc_jpy",
    side="buy",
    amount="0.01",
    price="5000000",
)

Error handling

A returned value is always real data; every failure raises:

Exception	Meaning
BitbankAPIError	The exchange rejected the request. .code holds the bitbank error code (e.g. 60001 insufficient funds, 10009 rate limited), and the message includes its description.
BitbankNetworkError	Connection error, timeout, or a non-JSON response. The request may or may not have reached the exchange.
BitbankError	Base class of both.

from bitbank import BitbankAPIError, BitbankNetworkError, create_market_order

try:
    order = create_market_order(api_key, api_secret, "btc_jpy", "buy", "0.01")
except BitbankAPIError as e:
    if e.code == 60001:       # insufficient funds — reduce the amount
        ...
    elif e.code in (10009, 70011):  # busy / rate limited — back off and retry
        ...
    else:
        raise
except BitbankNetworkError:
    # The order may still have been placed! Check fetch_active_orders /
    # fetch_trade_history before retrying, or the retry may buy twice.
    ...

Design notes (safety)

• Fail loud. No function silently returns a default on failure, so a trading decision can never be made on missing data.
• No automatic retries. Whether a failed order should be retried is a trading decision; the SDK never re-sends a request on its own.
• No withdrawal endpoints, by design. Use an API key with only the "info" and "trade" permissions; even a fully compromised bot built on this SDK cannot move funds off the exchange.
• Nonce-safe. Nonces are strictly increasing even across threads. Still, use one process (or separate API keys) per bot — bitbank requires nonces to increase per key.
• Bounded waits. Every request times out after 10 s by default; change this with bitbank.set_timeout(30.0).

Package layout

Module	Responsibility
bitbank.public	Market data — no authentication required
bitbank.private	Account and trading — API key and secret required
bitbank.types	Type aliases (Pair, Side, OrderType, PositionSide, CandleType)
bitbank.errors	Exceptions and the bitbank error-code table (ERROR_CODES)

Everything is re-exported at the top level, so from bitbank import ... is all you need.

API

Public

Function	Description
fetch_ticker(pair)	Latest ticker (sell, buy, high, low, open, last, vol)
fetch_tickers()	Tickers for all pairs
fetch_tickers_jpy()	Tickers for all JPY pairs
fetch_depth(pair)	Order book (asks, bids)
fetch_transactions(pair, yyyymmdd=None)	Executed trades (latest, or for a UTC date)
fetch_candlestick(pair, candle_type, date)	OHLCV candles for one date period
fetch_recent_candles(pair, candle_type, limit=100)	Most recent limit candles, spanning date boundaries
fetch_circuit_break_info(pair)	Circuit breaker status
fetch_pairs()	Pair definitions (price/amount digits, min/max order size)
fetch_spot_status()	Trading status per pair (NORMAL, BUSY, ...)

Candle types: 1min, 5min, 15min, 30min, 1hour (date = YYYYMMDD), 4hour, 8hour, 12hour, 1day, 1week, 1month (date = YYYY).

Private

All private functions take api_key and api_secret as the first two arguments. To avoid repeating them, bind once with functools.partial(create_order, api_key, api_secret).

Function	Description
fetch_assets(...)	Asset balances
create_order(...)	Place any order type
create_limit_order(...)	Limit order
create_market_order(...)	Market order
create_stop_order(...)	Stop market order
create_stop_limit_order(...)	Stop limit order
create_take_profit_order(...)	Take-profit order (margin)
create_stop_loss_order(...)	Stop-loss order (margin)
cancel_order(...)	Cancel an order
cancel_orders(...)	Cancel multiple orders
fetch_order(...)	Look up one order by ID
fetch_orders_info(...)	Look up multiple orders by ID
fetch_active_orders(...)	Open orders
fetch_trade_history(...)	The user's executed trades
fetch_margin_positions(...)	Open margin positions

License

MIT © 2026 tomoking2004