Uso

Inicio Rápido

Importe el cliente, los modelos principales y los tipos de error:

import os

from cryptobot import CryptoBotClient
from cryptobot.errors import CryptoBotError
from cryptobot.models import Asset, ButtonName, Status

Cree una instancia del cliente con su token de API:

client = CryptoBotClient(
    api_token=os.environ["CRYPTOBOT_API_TOKEN"],
    is_mainnet=True,
    timeout=5.0,
)

Inicio rápido asíncrono:

from cryptobot import AsyncCryptoBotClient


async def run():
    async with AsyncCryptoBotClient(api_token=os.environ["CRYPTOBOT_API_TOKEN"], max_retries=2) as client:
        app = await client.get_me()
        print(app.name)

Operaciones Básicas

Obtener Información de la Aplicación

Obtenga información básica sobre su aplicación:

app = client.get_me()
print(f"App ID: {app.app_id}")
print(f"App Name: {app.name}")
print(f"Bot Username: {app.payment_processing_bot_username}")

Crear una Factura

Cree una factura simple para pago en criptomoneda:

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

print(f"Invoice URL: {invoice.bot_invoice_url}")
print(f"Invoice ID: {invoice.invoice_id}")

Crear una Factura con Opciones Personalizadas

Cree una factura con parámetros adicionales:

::

Realizar Transferencias

Transfiera criptomoneda a otro usuario:

::

Consultar Saldos

Obtenga sus saldos actuales:

balances = client.get_balances()
for balance in balances:
    print(f"{balance.currency_code}: {balance.available}")

Obtener Tasas de Cambio

Obtenga las tasas de cambio actuales:

rates = client.get_exchange_rates()
for rate in rates:
    print(f"1 {rate.source} = {rate.rate} {rate.target}")

También puede filtrar por monedas específicas:

::

Obtener Monedas Soportadas

Obtenga información sobre todas las monedas soportadas:

currencies = client.get_currencies()
for currency in currencies:
    print(f"{currency.name} ({currency.code})")
    print(f"  Blockchain: {currency.is_blockchain}")
    print(f"  Stablecoin: {currency.is_stablecoin}")
    print(f"  Decimals: {currency.decimals}")
    if currency.url:
        print(f"  URL: {currency.url}")

Filtrar por tipo:

::

Obtener Información de Facturas

Obtenga información sobre facturas existentes:

::

invoice_ids acepta una cadena separada por comas ("123,456") o list[int] ([123, 456]). count se valida entre 1 y 1000.

Equivalente asíncrono:

import os

from cryptobot import AsyncCryptoBotClient
from cryptobot.models import Asset, Status

async with AsyncCryptoBotClient(api_token=os.environ["CRYPTOBOT_API_TOKEN"]) as async_client:
    paid_invoices = await async_client.get_invoices(
        asset=Asset.USDT,
        invoice_ids=[123, 456],
        status=Status.paid,
        count=50,
    )

Eliminar una Factura

Elimine una factura activa que ya no sea necesaria:

deleted = client.delete_invoice(invoice_id=12345)
print("Deleted:", deleted)

Obtener Transferencias

Liste las transferencias salientes con filtros opcionales:

::

Checks Criptográficos

Cree un check que cualquier usuario de Telegram (o un usuario fijado) pueda activar:

::

Obtener y gestionar checks:

::

Estadísticas de la Aplicación

Obtenga estadísticas agregadas para su aplicación:

stats = client.get_stats(
    start_at="2026-01-01T00:00:00Z",
    end_at="2026-03-01T00:00:00Z",
)
print(f"Volume: {stats.volume}")
print(f"Unique users: {stats.unique_users_count}")
print(f"Paid invoices: {stats.paid_invoice_count}")
print(f"Conversion: {stats.conversion}")

Tanto start_at como end_at son cadenas ISO 8601 opcionales. Cuando se omiten, start_at toma por defecto las últimas 24 horas y end_at toma por defecto el momento actual.

Configuración del Entorno

Testnet vs Mainnet

Por defecto, el cliente usa el entorno mainnet. Para usar testnet (con un token de testnet), establezca is_mainnet=False:

client = CryptoBotClient(os.environ["CRYPTOBOT_TESTNET_TOKEN"], is_mainnet=False)

Timeout Personalizado

Configure el timeout de solicitudes (por defecto son 5 segundos):

client = CryptoBotClient(os.environ["CRYPTOBOT_API_TOKEN"], timeout=60)

Reintentos Integrados

El comportamiento de reintentos es opcional y está deshabilitado por defecto (max_retries=0).

client = CryptoBotClient(
    api_token=os.environ["CRYPTOBOT_API_TOKEN"],
    timeout=30.0,
    max_retries=3,
    retry_backoff=0.5,
    retryable_status_codes={429, 500, 502, 503, 504},
)

Cuando está presente, el encabezado de respuesta Retry-After se respeta automáticamente antes del siguiente intento.

Convertir Pagos Entrantes

Convierta automáticamente los pagos a un activo diferente usando swap_to:

invoice = client.create_invoice(
    asset=Asset.TON,
    amount=20,
    description="Swap TON to USDT on receipt",
    swap_to="USDT",
)
print(invoice.bot_invoice_url)

Manejo de Errores

Todos los errores de la API lanzan cryptobot.errors.CryptoBotError:

from cryptobot.errors import CryptoBotError

try:
    client.transfer(user_id=12345, asset=Asset.BTC, amount=10, spend_id="test")
except CryptoBotError as exc:
    print(f"Error code: {exc.code}")
    print(f"Error name: {exc.name}")

Integración de Webhook

Usar el Servidor Webhook Integrado

CryptoBot Python incluye un listener de webhook basado en FastAPI para manejar notificaciones de pago:

import os

from cryptobot.webhook import InMemoryReplayKeyStore, Listener


def handle_webhook(headers, data):
    if data.get("update_type") == "invoice_paid":
        payload = data.get("payload", {})
        print("Paid invoice:", payload.get("invoice_id"))


listener = Listener(
    host="0.0.0.0",
    callback=handle_webhook,
    api_token=os.environ["CRYPTOBOT_API_TOKEN"],
    replay_store=InMemoryReplayKeyStore(),
    replay_ttl_seconds=3600,
    port=2203,
    url="/webhook",
    log_level="info",
)
listener.listen()

El listener verifica automáticamente las firmas, puede rechazar payloads de webhook duplicados/repetidos y proporciona un banner de inicio. callback puede ser síncrono (def) o asíncrono (async def).

Para claves de deduplicación de repetición personalizadas, proporcione replay_key_resolver:

def replay_key_resolver(data, raw_body, headers):
    payload = data.get("payload", {})
    invoice_id = payload.get("invoice_id")
    if invoice_id is not None:
        return f"invoice_paid:{invoice_id}"
    return None

Manejador de Webhook Personalizado

También puede crear su propio manejador de webhook y verificar firmas con check_signature:

::

Activos Disponibles

La biblioteca soporta estos activos (vea cryptobot.models.Asset para la lista canónica):

::

Patrones Avanzados

Paginación con iteradores

Cuando trabaje con muchos registros, prefiera los ayudantes de iteradores paginados integrados. Están disponibles para facturas, transferencias y checks.

Facturas:

::

Transferencias:

for transfer in client.iter_transfers(asset=Asset.TON, page_size=100):
    print(transfer.transfer_id, transfer.amount)

Checks:

for check in client.iter_checks(asset=Asset.USDT, status="active", page_size=100):
    print(check.check_id, check.bot_check_url)

La paginación asíncrona funciona con async for:

import os

from cryptobot import AsyncCryptoBotClient
from cryptobot.models import Asset, Status

async with AsyncCryptoBotClient(api_token=os.environ["CRYPTOBOT_API_TOKEN"]) as async_client:
    async for page in async_client.iter_invoice_pages(
        asset=Asset.USDT,
        status=Status.paid,
        page_size=100,
        start_offset=0,
    ):
        print("page size:", len(page))

    async for invoice in async_client.iter_invoices(
        asset=Asset.USDT,
        status=Status.paid,
        page_size=100,
        start_offset=0,
    ):
        print(invoice.invoice_id, invoice.status)

Todas las variantes de iteradores soportan start_offset y validan page_size en el rango 1..1000.

Verificación de Estado de Factura

Cree una función auxiliar para verificar el estado de la factura:

::

Calcular Ingresos Totales

Calcule los ingresos totales de facturas pagadas:

::

Precios Multi-Moneda

Cree facturas que permitan a los usuarios pagar en diferentes monedas:

::

Mejores Prácticas

Siempre maneje las excepciones al hacer llamadas a la API
Use spend_ids únicos para transferencias para prevenir duplicados
Valide la entrada del usuario antes de crear facturas o transferencias
Almacene los tokens de API de forma segura usando variables de entorno
Use un token de testnet dedicado con is_mainnet=False durante el desarrollo
Implemente la verificación adecuada de firma de webhook por seguridad
Establezca tiempos de expiración de factura apropiados para evitar facturas obsoletas
Use paginación al obtener grandes cantidades de facturas
Verifique el estado de la factura antes de procesar pedidos
Registre todas las transacciones para auditorías y depuración