Skip to main content

altpay-py

Official Python SDK for the AltPay crypto-payments API. Synchronous and asynchronous clients, typed models, request signing and webhook verification in one package. Built on httpx and pydantic v2.

pip install altpay-py
import altpay  # the distribution is altpay-py; the import name is altpay

Quick start

from decimal import Decimal
from altpay import AltPay, Credentials

client = AltPay(Credentials(
    merchant_id="YOUR_MERCHANT_ID",
    api_key="vc_live_...",
    api_secret="YOUR_API_SECRET",
))

invoice = client.invoices.create(
    uuid="order-42",                 # your idempotency key / order reference
    amount=Decimal("100.00"),
    fiat_currency="USD",
    url_callback="https://example.com/altpay/webhook",
)
print(invoice.url)                   # hosted checkout URL to redirect the payer to

# later, check on it
invoice = client.invoices.get(order_id=invoice.order_id)
print(invoice.status)                # PaymentStatus.WAITING | PAID | EXPIRED | ...

Async

The async client mirrors the sync one. await the calls.

from altpay import AsyncAltPay, Credentials

async with AsyncAltPay(creds) as client:
    invoice = await client.invoices.create(
        uuid="order-42", amount="100.00", fiat_currency="USD",
    )
    print(invoice.url)

What you can do

Resource Method Endpoint
client.invoices create(...) create an invoice
get(order_id=... | uuid=...) fetch one invoice
list(status=..., cursor=..., limit=...) page through invoices
services() available methods, limits and fees
balance(fiat_currency=...) balance valued in one fiat, per asset
assets(fiat_currency=...) per-token balance with allocation + withdrawable
create_wallet(network=..., order_id=...) static deposit wallet
list_wallets(limit=..., offset=...) list static wallets
wallet_deposits(wallet_uuid=...) deposits received at a static wallet
client.withdrawals estimate_fee(asset=..., network=...) preview payout fees
create(asset=..., amount=..., address=..., idempotency_key=...) request a payout to a trusted address
list(limit=..., offset=...) list payout requests
client.account get() merchant + API-key identity
balance() paid volume per method (native asset)
statistics() aggregate counts and USD volume

Webhooks

AltPay POSTs a signed payment.updated event to your url_callback when an invoice is paid. Always verify the signature before trusting the body, and pass the raw request bytes, not the re-serialized JSON.

from altpay import WebhookVerifier

verifier = WebhookVerifier(WEBHOOK_SECRET, target="/altpay/webhook")

# inside your handler (framework-agnostic):
event = verifier.parse(raw_body, request_headers)   # raises AuthenticationError on a bad sig
if event.status == "paid":
    fulfil_order(event.merchant_reference)

verifier.verify(raw_body, headers) returns a bool if you prefer to branch yourself.

Verification is not deduplication: AltPay may deliver the same event more than once, and both copies verify. Make fulfilment idempotent by keying it on event.payment_id, so a repeat is a no-op.

Withdrawals (payouts)

Request a payout with client.withdrawals. For safety the public API can only send to an address you already trusted in the dashboard (adding one requires your 2FA), so a leaked API key cannot invent a new destination. At most it can repeat a payout to an address you already trust.

fee = client.withdrawals.estimate_fee(asset="USDT", network="USDT_TRC20")

payout = client.withdrawals.create(
    asset="USDT",
    amount="50.00",
    address="T...",                 # must already be a trusted address for USDT
    network="USDT_TRC20",
    idempotency_key="payout-42",    # a retry with the same key returns the original payout
)
print(payout.status)                # WithdrawalStatus.PENDING (an operator approves it)

Always pass idempotency_key: the amount is reserved from your balance the moment the request is accepted, and the key is what makes a network retry return the original payout instead of debiting you twice. A trusted-but-wrong address still moves funds, so verify it before calling.

Errors

Every failure is an AltPayError. Network problems raise AltPayTransportError; anything the API rejected raises an APIError subclass keyed by HTTP status. Each carries the server's machine-readable detail, a human hint, and the request_id for support.

from altpay import AuthenticationError, RateLimitError, ValidationError, NotFoundError

try:
    client.invoices.create(uuid="o1", amount="100", fiat_currency="USD")
except AuthenticationError as e:
    ...   # bad credentials / clock skew / revoked key  (HTTP 401, detail="invalid_signature")
except ValidationError as e:
    ...   # a field failed validation                   (HTTP 400, detail="invalid_request")
except RateLimitError as e:
    sleep(e.retry_after or 1)                            # HTTP 429
except NotFoundError as e:
    ...                                                  # HTTP 404

The full catalogue, with every detail value and how to fix it, is at https://docs.altpay.money/docs/http-codes.

Configuration

AltPay(
    credentials,
    base_url="https://api.altpay.money",  # override for staging
    timeout=30.0,                          # per-request seconds
    max_retries=2,                         # retry transient errors (5xx, 429, network) with backoff
    http_client=my_httpx_client,           # bring your own httpx.Client (proxies, custom TLS)
)

Authentication

Each request is signed with HMAC-SHA256 over a canonical string of the merchant id, API key, timestamp, nonce, body hash, method and path. The SDK signs every request; the secret never leaves your process. The primitives (for custom transport or testing) live in altpay.signing. Full spec: https://docs.altpay.money/docs/authentication.

Requirements

  • Python 3.10+
  • httpx >= 0.24, pydantic >= 2.0

License

MIT

Metadata

Release files for altpay-py 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for altpay-py 0.1.3
File Size Uploaded Provenance Actions
altpay_py-0.1.3.tar.gz 30.6 kB Without provenance Details for altpay_py-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for altpay-py 0.1.3
File Interpreter ABI Platform Actions
altpay_py-0.1.3-py3-none-any.whl Python 3 none any Details for altpay_py-0.1.3-py3-none-any.whl

Total release size: 66.5 kB

Release files / altpay_py-0.1.3.tar.gz

Download URL altpay_py-0.1.3.tar.gz
Size 30.6 kB
Tags Source
SHA-256 checksum
How to use checksums
dae4cf6e41dabb8972fd0cdc1aee5cfc8740ec6f6dc3812b7d0f532aaf2fb28f
BLAKE2b-256 checksum
How to use checksums
8a60384c9abd59bee428443b73d92ee9726b3a8fc46a00442b297bc37053f8f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.0

Release files / altpay_py-0.1.3-py3-none-any.whl

Download URL altpay_py-0.1.3-py3-none-any.whl
Size 35.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3f1e68ef5c95fb5bfdaee4510e93df9738a2737590b0e1e9c60f4e7e21c8108e
BLAKE2b-256 checksum
How to use checksums
9a0649f7ab97fc779e8eeef3756316b67120f18f83f8f79d7fc8074dcb726768
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.0

Security for altpay-py 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page