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.1.1

Shared authentication has been removed. Fragment requests now use your own cookie session, with explicit authentication using your own wallet when needed.

Remove shared_auth_seed and wallet_auth constructor arguments and stop using nokyc_mode or NoKycBatchResult. Supply cookies directly, load them from session storage, or call FragmentClient.authenticate() with your own wallet before constructing the client. No built-in wallet is used for authentication or payment.

ProfileInfo.identity_verified and ProfileInfo.wallet_verified were removed in 14.1.0 with the old profile page.

Live checks on November 2, 2026 returned request IDs and unsigned native-TON transactions for Stars, Premium, both giveaway types, and Ads top-ups without a verification challenge in the tested session. No payments were submitted. Withdrawals and asset mutations require valid operation links or assets and were not exercised by that check.

Choose your workflow

All Fragment HTTP operations require a user-owned cookie session. Native automatic payments additionally require a wallet-connected session.

Constructing a client without cookies is supported for offline validation and wallet utilities. It does not trigger authentication. Explicit login and cookie refresh use only the seed supplied by the caller.

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.
• 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   /   MIT License