Python SDK

cryptunnel on PyPI wraps the merchant API for Python 3.10+. It is async-first - built for bots on aiogram and for async web frameworks - with a blocking mirror for scripts. httpx is its only dependency.

pip install cryptunnel

Everything the package does is a plain HTTP call you can also make yourself - see the API reference. The package saves you the request building, the error mapping and the two parts people get wrong: webhook verification and polling.

Construction

from cryptunnel import Cryptunnel, CryptunnelSync

# async - inside a bot or a web framework
cryptunnel = Cryptunnel("<merchant id>", "<api key>", sandbox=True)

# blocking - scripts and one-off calls
cryptunnel = CryptunnelSync("<merchant id>", "<api key>", sandbox=True)

The async client is a context manager (async with Cryptunnel(...) as cryptunnel:) and has an explicit await cryptunnel.close(); the sync one mirrors both.

Methods

Every method exists on both clients with the same name, arguments and return value - await it on Cryptunnel, call it on CryptunnelSync. Each returns the decoded JSON of its endpoint as a dict.

create_widget_payment and create_h2h_payment are idempotent on external_id: a retry after a timeout returns the payment you already created. Repeating an external_id with a different amount or currency raises ValidationError with code PAYMENT_ALREADY_EXISTS.

get_payment returns two shapes and the status tells them apart: a created or expired payment has no amount, currency or wallet_address, because nobody has picked a currency for it yet. Read them with payment.get("amount") unless you know the status - see Payment statuses.

Errors

Every failure is a subclass of CryptunnelError; branch on the class and read the raw API code from .code.

from cryptunnel import RateLimitError, ValidationError

try:
    cryptunnel.create_h2h_payment(10, "USD", "order-3", "DOGE")
except ValidationError as error:
    print(error.code)  # WALLET_NOT_FOUND - no active DOGE wallet on this merchant
except RateLimitError as error:
    print(error.retry_after)

Verifying a webhook

Pass the raw body bytes exactly as received - parsing and re-serialising the JSON changes the signature. The helper reads x-webhook-timestamp and x-webhook-signature from any header mapping, in any casing.

from flask import request
from cryptunnel import verify_webhook

@app.post("/cryptunnel")
def callback():
    if not verify_webhook(WEBHOOK_SECRET, request.headers, request.get_data()):
        return "", 401
    payment = request.get_json()
    ...
    return "", 200

from aiohttp import web
from cryptunnel import verify_webhook

async def callback(request: web.Request):
    raw_body = await request.read()
    if not verify_webhook(WEBHOOK_SECRET, request.headers, raw_body):
        return web.Response(status=401)
    payment = await request.json()
    ...
    return web.Response(status=200)

The full contract - payload fields, retries, deduplication - is on the webhooks page.

Waiting for a payment

wait_for_payment polls every 5 seconds, backing off to 30, honours Retry-After on a 429, and raises PaymentTimeoutError after 30 minutes. It exists for scripts and development. In production the webhook is the guarantee: a buyer who closes the page still produces a callback, a polling process that dies does not.

Links

• Package: pypi.org/project/cryptunnel
• Source and issues: github.com/cryptunnel/cryptunnel-python
• Telegram bot recipe - the whole flow on aiogram