aiorocket2.client¶

aiorocket2 client module.

This module provides xRocketClient — an async-first wrapper around the xRocket Pay HTTP API. The client implements retries, consistent error handling and typed model conversion for responses.

Example¶

Simple invoice creation:

import asyncio
from aiorocket2 import xRocketClient

async def main():
        async with xRocketClient(api_key="YOUR_API_KEY", testnet=True) as client:
                invoice = await client.create_invoice(currency="TON", amount=0.01)
                print(invoice.id, invoice.url)

asyncio.run(main())

Notes¶

Methods are asynchronous; integrate the client into your bot’s event loop.
Where parameters expect enum types (see aiorocket2.enums) prefer passing
enum members (for example Network.TON) to avoid typos.

Classes

xRocketClient(api_key, *[, testnet, ...])

Asynchronous client for the xRocket Pay API.

class aiorocket2.client.xRocketClient(api_key, *, testnet=False, base_url=None, session=None, timeout=30.0, retries=3, backoff_base=0.25, user_agent='aiorocket2/2.0 (+https://github.com/RimMirK/aiorocket2)')[source]¶

Bases: Tags

Asynchronous client for the xRocket Pay API.

The client composes all tag mixins (see aiorocket2.tags) and exposes high-level helpers for sending requests, handling retries and converting responses into typed models. Typical usage is via an async context manager which ensures the underlying HTTP session is closed automatically.

Example:

async with xRocketClient(api_key="KEY") as client:
    inv = await client.create_invoice(currency="TON", amount=0.01)
    print(inv.url)

Parameters:

api_key (str)
testnet (bool)
base_url (Optional[str])
session (Optional[aiohttp.ClientSession])
timeout (float)
retries (int)
backoff_base (float)
user_agent (str)

__init__(api_key, *, testnet=False, base_url=None, session=None, timeout=30.0, retries=3, backoff_base=0.25, user_agent='aiorocket2/2.0 (+https://github.com/RimMirK/aiorocket2)')[source]¶

Initialize the client.

Parameters:

api_key (str) – Your xRocket Pay API key.
testnet (bool) – If True, use the staging/test environment.
base_url (str | None) – Optional override for the base API URL.
session (ClientSession | None) – Optional aiohttp session to reuse.
timeout (float) – aiohttp total timeout (seconds).
retries (int) – Number of retries for network/5xx errors.
backoff_base (float) – Base delay for exponential backoff (seconds).
user_agent (str) – Custom User-Agent header value.

Return type:

None

async aclose()[source]¶

Close the underlying aiohttp session if it was created by this client.

Return type:: None

async check_health()¶

Return API status as a aiorocket2.enums.Status enum.

Returns:: Service status reported by the API.
Return type:: Status
Raises:: xRocketAPIError – If the request fails.

async create_invoice(currency, amount=None, min_payment=None, num_payments=1, description=None, hidden_message=None, comments_enabled=False, callback_url=None, payload=None, expired_in=0, platform_id=None)¶

amount (float): Optional. Invoice amount. 9 decimal places, others cut off. Minimum 0. Maximum 1_000_000 min_payment (float): Optional. Min payment only for multi invoice if invoice amount is None. Minimum 0. Maximum 1_000_000 num_payments (int): Optional. Num payments for invoice. Minimum 0. Maximum 1_000_000 description (str): Optional. Description for invoice. Maximum 1000 hidden_message (str): Optional. Hidden message after invoice is paid. Maximum 2000 comments_enabled (bool): Optional. Allow comments. Default False callback_url (str): Optional. Url for Return button after invoice is paid. Maximum 500 payload (str): Optional. Any data. Invisible to user, will be returned in callback. Maximum 4000 expired_in (int): Optional. Invoice expire time in seconds, max 1 day, 0 - none expired. Minimum 0. Maximum 86400. Default 0 platform_id (str): Optional. Platform identifier

Create invoice.

Parameters:

currency (str) – Currency code, for example "TON". Use xRocketClient.get_available_currencies() to list valid currencies.
amount (float) – Optional fixed invoice amount. Use decimal precision up to 9 fractional places; values are truncated by the API.
min_payment (float) – Optional minimum payment for multi-pay invoices.
num_payments (int) – Number of allowed partial payments (default 1).
description (str) – Visible description for the payer (max 1000 chars).
hidden_message (str) – Message shown to the payer after successful payment.
comments_enabled (bool) – Allow comments on the invoice.
callback_url (str) – Return/callback URL (optional).
payload (str) – Opaque string returned in callbacks — useful for your internal IDs.
expired_in (int) – Expiry in seconds (0 — never expire).
platform_id (str) – Optional platform identifier.

Returns:

Parsed invoice model returned by the API.

Return type:

Invoice

Raises:

xRocketAPIError – When API returns non-success or for network errors.

Notes

Prefer passing enum members where available; for currency codes the current API accepts strings, but using a canonical source reduces typos.
For accounting-sensitive flows consider using decimal.Decimal to construct amounts before converting to float.

Example

>>> async with xRocketClient(api_key="KEY") as client:
...     inv = await client.create_invoice(currency="TON", amount=0.005, description="Tip")
...     print(inv.id, inv.url)

async create_multi_cheque(currency, cheque_per_user, users_number, ref_program, password=None, description=None, send_notifications=True, enable_captcha=True, telegram_resources_ids=None, for_premium=False, linked_wallet=False, disabled_languages=None, enabled_countries=None)¶

Create a multi-cheque (voucher) for multiple activations.

Parameters:

currency (str) – Currency code such as "TON". Use xRocketClient.get_available_currencies() to list valid currencies.
cheque_per_user (float) – Amount reserved per activation (up to 9 decimals).
users_number (int) – Number of activations (integer, minimum 1).
ref_program (int) – Referral program percentage (0-100).
password (str) – Optional password for the cheque (max length 100).
description (str) – Optional description for the cheque (max length 1000).
send_notifications (bool) – Whether to send activation notifications.
enable_captcha (bool) – Enable captcha for activation flow.
telegram_resources_ids (List[Union[int, str]]) – Telegram resource ids (group/channel ids).
for_premium (bool) – Restrict activation to Telegram Premium users.
linked_wallet (bool) – Require linked wallet for activation.
disabled_languages (List[str]) – Languages to disable.
enabled_countries (List[Country]) – Pass members of the Country enum (for example [Country.US, Country.GB]). The client converts enums to their API string values internally.

Returns:

Model representing created cheque.

Return type:

Cheque

Raises:

xRocketAPIError – On API or validation errors.

Example

>>> from aiorocket2.enums import Country
>>> async with xRocketClient(api_key="KEY") as client:
...     chk = await client.create_multi_cheque(currency="TON", cheque_per_user=0.001, users_number=50, ref_program=0, enabled_countries=[Country.US])
...     print(chk.id, chk.inviteUrl)

async create_withdrawal(network, address, currency, amount, withdrawal_id, comment)¶

Create a withdrawal to an external address.

Parameters:

network (Network) – Network code.
address (str) – Withdrawal address.
currency (str) – Currency code.
amount (float) – Amount to withdraw (up to 9 decimals).
withdrawal_id (str) – Unique idempotency identifier (<=50 chars).
comment (str) – Optional comment (<=50 chars).

Returns:

Created withdrawal record.

Return type:

Withdrawal

Raises:

xRocketAPIError – On validation or API errors.

async delete_invoice(invoice_id)¶

Delete an invoice.

Parameters:: invoice_id (int) – Invoice identifier.
Returns:: On successful deletion.
Return type:: True
Raises:: xRocketAPIError – If deletion fails.

async delete_multi_cheque(cheque_id)¶

Delete a multi-cheque by id.

Parameters:: cheque_id (str) – Cheque identifier.
Returns:: On success.
Return type:: True
Raises:: xRocketAPIError – If deletion fails.

async edit_multi_cheque(cheque_id, password=None, description=None, send_notifications=None, enable_captcha=None, telegram_resources_ids=None, for_premium=None, linked_wallet=None, disabled_languages=None, enabled_countries=None)¶

Update properties of an existing multi-cheque.

Parameters:

cheque_id (int) – Cheque identifier.
password (str) – Optional password (max 100 chars).
description (str) – Optional description (max 1000 chars).
send_notifications (bool) – Whether to send activation notifications.
enable_captcha (bool) – Enable captcha for activation.
telegram_resources_ids (List[Union[int,str]]) – IDs of telegram resources.
for_premium (bool) – Restrict activation to Telegram Premium users.
linked_wallet (bool) – Require linked wallet for activation.
disabled_languages (List[str]) – Languages to disable.
enabled_countries (List[Country]) – Allowed countries.

Returns:

Updated cheque model.

Return type:

Cheque

Raises:

xRocketAPIError – On validation or API errors.

async get_available_currencies()¶

Return available currencies from the API.

Returns:: Parsed list of currency models.
Return type:: List[Currency]
Raises:: xRocketAPIError – If the request fails.

async get_info()¶

Return information about the current application.

Returns:: Application info including balances.
Return type:: Info
Raises:: xRocketAPIError – On API or network errors.

async get_invoice(invoice_id)¶

Return a single invoice by id.

Parameters:: invoice_id (int) – Invoice identifier.
Returns:: Parsed invoice model.
Return type:: Invoice
Raises:: xRocketAPIError – If invoice is not found or API error occurs.

async get_invoices(limit=100, offset=0)¶

Return paginated list of invoices.

Parameters:

limit (int) – Number of items to return (1-1000). Default 100.
offset (int) – Result offset (>=0). Default 0.

Returns:

Paginated result with results list of Invoice.

Return type:

PaginatedInvoice

Raises:

xRocketAPIError – If the API returns an error.

async get_multi_cheque(cheque_id)¶

Return details for a single multi-cheque.

Parameters:: cheque_id (int) – Cheque identifier.
Returns:: Parsed cheque model.
Return type:: Cheque
Raises:: xRocketAPIError – If the cheque is not found or API reports an error.

async get_multi_cheques(limit=100, offset=0)¶

Return paginated list of multi-cheques.

Parameters:

limit (int) – Number of items to return (1-1000). Default 100.
offset (int) – Result offset (>=0). Default 0.

Returns:

Paginated result with results containing Cheque.

Return type:

PaginatedCheque

Raises:

xRocketAPIError – If the API returns an error.

async get_version()¶

Return the upstream API version string.

Returns:: Version string, for example "1.3.1".
Return type:: str
Raises:: xRocketAPIError – If the API request fails.

Example:

version = await client.get_version()

async get_withdrawal(withdrawal_id)¶

Return withdrawal details by id.

Parameters:: withdrawal_id (str) – Unique withdrawal id used in your system.
Returns:: Withdrawal details.
Return type:: Withdrawal
Raises:: xRocketAPIError – If the withdrawal is not found or API returns error.

async get_withdrawal_fees(currency=None)¶

Return withdrawal fee information for supported coins.

Parameters:: currency (str) – Optional currency code to filter fees by.
Returns:: Fee metadata per coin.
Return type:: List[WithdrawalCoin]
Raises:: xRocketAPIError – If the API returns an error.

async get_withdrawal_link(currency, network, address, amount=0, comment=None, platform=None)¶

Get a withdrawal link for on-chain withdrawals.

Parameters:

currency (str) – Currency code (use xRocketClient.get_available_currencies()).
network (Network) – Network enum member (e.g. Network.TON).
address (str) – Target on-chain address.
amount (float) – Optional withdrawal amount (default 0).
comment (str) – Optional comment attached to withdrawal.
platform (str) – Optional platform identifier.

Returns:

Telegram application link for withdrawal.

Return type:

Optional[str]

Raises:

xRocketAPIError – If the API returns an error or no link is available.

Example

>>> from aiorocket2.enums import Network
>>> async with xRocketClient(api_key="KEY") as client:
...     link = await client.get_withdrawal_link(currency="TON", network=Network.TON, address="EQ...", amount=0.1)
...     print(link)

async get_withdrawal_status(withdrawal_id)¶

Return status for a withdrawal.

This is a thin helper around get_withdrawal() that returns the parsed WithdrawalStatus enum.

Parameters:: withdrawal_id (str) – Unique withdrawal id.
Returns:: Current status.
Return type:: WithdrawalStatus
Raises:: xRocketAPIError – If the API call fails.

async send_transfer(tg_user_id, currency, amount, transfer_id, description=None)¶

Make an internal transfer to a Telegram user.

Parameters:

tg_user_id (int) – Target Telegram user id. If unknown to the API the request will fail with a 400 error.
currency (str) – Currency code (see Currencies.get_available_currencies()).
amount (float) – Transfer amount (up to 9 decimals).
transfer_id (str) – Idempotency/unique transfer id in your system to prevent duplicate transfers.
description (str) – Optional transfer description.

Returns:

Model with transfer details.

Return type:

Transfer