Fragment API Python

One async client. Explicit payment states. A complete Fragment workspace.

Stars · Premium · Gifts · Usernames · Numbers · Ads · Gateway

Read the documentation   /   Explore examples   /   Report an issue

Built for explicit workflows

fragment-api-py is an unofficial asynchronous Python SDK for Fragment.com.

Browse the marketplace, resolve recipients, prepare transactions for external signing, or configure a payer wallet for automatic broadcasting. Work with typed results instead of treating every accepted request as a completed purchase.

Release 14.0.0

Single-submission batches, durable payment recovery, and coordinated payer access.

Choose your workflow

Account operations require a user-owned cookie session. Native automatic payments in cookie mode additionally require a wallet-connected session.

Restricted wallet authentication does not bypass Fragment verification requirements. The shared authentication wallet is separate from the configured payer.

Installation

Python 3.10 or newer

Install from PyPI with pip install fragment-api-py.

Optional integrations:

Automatic TON payments require a valid mnemonic and a provider key from Tonconsole or Toncenter.

Start with an example

The repository keeps executable examples in one place rather than duplicating code throughout the documentation.

Browse the complete example guide

Batches, fees, and recovery

batch_purchase(items) prepares all invoices and submits their combined messages in one wallet transaction. A batch that exceeds wallet capacity is rejected before broadcasting; it is never silently split. In preparation mode, result.transaction contains the combined payload for external signing.

Native TON purchases include a separate 1.5% service fee (FEE_BASIS_POINTS = 150), sent to FEE_ADDRESS in FragmentAPI/types/constants.py. This is additional to network fees and separate from voluntary support. Inspect payment_nanoton, fee_nanoton, gas_reserve_nanoton, and required_nanoton before signing. The percentage fee does not apply to USDT or external EVM payments.

Automatic payments durably record the signed BOC before broadcast. Use list_payments(), get_payment(operation_id), and reconcile_payment(operation_id) to recover after cancellation or restart without repeating a blockchain payment. The default journal and wallet locks are stored under ~/.fragment-api; deployments must preserve that directory.

See payment batches and recovery for result semantics, confirmation limits, operator resolution, and coordination across processes/hosts.

Payment networks

Availability is subject to Fragment's response and operation-specific restrictions. Ads and Gateway recharge flows use native TON.

Know what happened

Documentation

Operational notes

• Reuse a client and close it with an asynchronous context manager or aclose().
• Keep payer credentials, session cookies, and login codes out of source control and logs.
• Use your own sender account for external signing.
• Never deposit funds into the shared authentication wallet.
• Local clients/processes sharing a payer use OS wallet locks and a durable journal. Multi-host deployments must configure shared payment storage and distributed locks.
• Fragment HTML and private endpoints can change independently of this package.
• This project is not affiliated with or endorsed by Fragment, Telegram, or TON.

Support the project

Development, maintenance, and issue reports are welcome.

TON address

UQAcsdD09x9dzj7Jc-MznN-SLUxPPMmwKQxsC2Ax_F03TBAH

GitHub   /   Documentation   /   Telegram   /   MIT License