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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.