CryptoBot Python

Unofficial, but friendly client for the Crypto Bot API. Provides Pythonic models, sane defaults, and synchronous helpers so you can issue invoices or payouts with minimal boilerplate.

Features

• Lean synchronous client powered by httpx
• Dataclass models for invoices, balances, currencies, and exchange rates
• Enum-based guard rails for assets, statuses, and button names
• Optional testnet support and configurable request timeout
• FastAPI webhook example to bootstrap integrations

Installation

CryptoBot Python targets Python 3.9+. Install it from PyPI:

pip install cryptobot-python

Quick Start

Grab an API token from @CryptoBot in Telegram, then create a client and start issuing invoices:

from cryptobot import CryptoBotClient
from cryptobot.models import Asset

client = CryptoBotClient("YOUR_API_TOKEN")

invoice = client.create_invoice(
    asset=Asset.USDT,
    amount=5.25,
    description="Coffee order #42",
)

print(invoice.bot_invoice_url)

Invoices, balances, currencies, and transfers are returned as dataclasses, so attributes are available using dot access. For low-level control, check the API reference.

Handling Errors

All API failures raise cryptobot.errors.CryptoBotError. Inspect the error for the Crypto Bot error code and name:

try:
    client.transfer(user_id=12345, asset=Asset.TON, amount=0.5, spend_id="demo")
except CryptoBotError as exc:
    print(exc.code, exc.name)

Local Development

Clone the repo and install development dependencies with Poetry:

poetry install

Use the helper Makefile targets while iterating:

make lint      # flake8 checks for cryptobot/ and tests/
make test      # pytest with coverage report
make docs      # rebuild the Sphinx documentation

To experiment with the webhook example, run:

poetry run uvicorn cryptobot.webhook:app --reload

Contributing

Bug reports, feature ideas, and pull requests are welcome. Please run make lint and make test before opening a PR, and update the docs when modifying public APIs. See AGENTS.md for more contributor guidance.

Credits

This project started with Cookiecutter and the audreyr/cookiecutter-pypackage template.