aiorocket2.tags¶

Tag composition for aiorocket2.

The upstream API groups endpoints by tags (for example app, tg-invoices, multi-cheque). Each tag is implemented as a mixin-like class in this package and then composed into the Tags helper. The main client aiorocket2.client.xRocketClient inherits from Tags to expose all convenience methods on the client instance.

Available tags¶

Version — API version helpers
App — application-level operations (balance, transfer, withdrawals)
MultiCheque — multi-cheque (voucher) endpoints
TgInvoices — invoice creation and retrieval
WithdrawalLink — on-chain withdrawal link helper
Currencies — currency listing helper
Health — lightweight health check

Classes

Tags()

General class to join all tags together

class aiorocket2.tags.Tags[source]¶

Bases: Version, App, MultiCheque, TgInvoices, WithdrawalLink, Currencies, Health

General class to join all tags together

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