cryptopay-python-sdk

Sync + async Python client for the Telegram Crypto Pay API.

Supports Python 3.9+, type-annotated, and has no heavy dependencies — just httpx for async and requests for sync.

Install

pip install cryptopay-python-sdk

Quick start

Async (recommended)

import asyncio
from crypto_pay_api import CryptoPayAsync, CryptoPayConfig

async def main():
    cfg = CryptoPayConfig(token="YOUR_TOKEN")
    async with CryptoPayAsync(cfg) as cp:
        invoice = await cp.create_invoice(asset="USDT", amount=5)
        print(invoice["pay_url"])

asyncio.run(main())

Sync

from crypto_pay_api import CryptoPay, CryptoPayConfig

cfg = CryptoPayConfig(token="YOUR_TOKEN")
with CryptoPay(cfg) as cp:
    invoice = cp.create_invoice(asset="USDT", amount=5)
    print(invoice["pay_url"])

Both clients are context managers that close the underlying HTTP session automatically.

Configuration

from crypto_pay_api import CryptoPayConfig

cfg = CryptoPayConfig(
    token="YOUR_TOKEN",          # required — get it from @CryptoBot on Telegram
    network="mainnet",           # "mainnet" (default) or "testnet"
    timeout=20.0,                # request timeout in seconds (default: 20.0)
    base_url_override=None,      # override the API base URL if needed
)

Methods

All methods are available on both CryptoPay (sync) and CryptoPayAsync (async) with identical signatures.

App

Invoices

create_invoice parameters:

Checks

Transfers

Webhook verification

Verify incoming webhooks from Crypto Pay using the built-in helper:

from crypto_pay_api import verify_webhook_signature

is_valid = verify_webhook_signature(
    token="YOUR_TOKEN",
    raw_body=request.body,                                    # raw bytes
    signature_header=request.headers["crypto-pay-api-signature"],
)

if not is_valid:
    return 403

Error handling

from crypto_pay_api import CryptoPayAPIError, CryptoPayHTTPError

try:
    invoice = cp.create_invoice(asset="USDT", amount=5)
except CryptoPayAPIError as e:
    # API returned ok=false (e.g. invalid token, bad params)
    print(e.error_code)  # string error code from the API
    print(e.raw)         # full raw response dict
except CryptoPayHTTPError as e:
    # Network error or non-2xx HTTP response
    print(e)

Error hierarchy:

CryptoPayError          ← base class
├── CryptoPayAPIError   ← API returned ok=false
└── CryptoPayHTTPError  ← network / HTTP-level error

License

MIT