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.0
Current Fragment account headers, updated giveaway requests, and ordinary API error handling without a separate KYC workflow.
| Area | What changed |
|---|---|
| Profile | get_profile() reads the full page header; the removed /my/profile route is no longer requested |
| Account fields | Name, photo, wallet address and label; username is empty because the header does not expose it |
| API errors | KYC-specific classification is removed; VerificationError remains an import alias of FragmentAPIError |
| Giveaways | Stars recipient search sends only query, matching the current Fragment interface |
| Marketplace | Wallet owners and history support the current gram.org/address/ explorer links |
ProfileInfo.identity_verified and ProfileInfo.wallet_verified were removed with the old profile page. Applications should stop reading these fields. Historical wallet-auth aliases such as nokyc_mode remain available.
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
| Workflow | Configuration | Result |
|---|---|---|
| Account browsing | Your Fragment cookies | Marketplace and user-owned account data |
| Restricted session | No cookies; wallet authentication | Allowed public and purchase workflows |
| External TON signing | A complete sender account or an offline-derived payer account, without automatic payment credentials | PreparedTransaction |
| Automatic TON payment | Payer seed and blockchain API key | Broadcast receipt with explicit confirmation state |
| EVM payment | Supported EVM payment method | An invoice for external payment |
Account operations require a user-owned cookie session. Native automatic payments in cookie mode additionally require a wallet-connected session.
The shared authentication wallet is separate from the configured payer. Account-management restrictions protect shared-wallet state and remain in effect.
Installation
Python 3.10 or newer
Install from PyPI with pip install fragment-api-py.
Optional integrations:
| Extra | Installation |
|---|---|
| Redis storage | pip install "fragment-api-py[redis]" |
| Terminal QR rendering | pip install "fragment-api-py[qr]" |
| Development tools | pip install "fragment-api-py[dev]" |
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.
| Your goal | Start here |
|---|---|
| Configure the client | Basic setup |
| Authenticate a full account | Authentication |
| Understand restricted mode | Wallet authentication |
| Buy Stars or Premium | Stars · Premium |
| Prepare an external payment | External signing |
| Search gifts and attributes | Marketplace search |
| Handle payment outcomes | Error handling |
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
| Method | Network | Asset | SDK behavior |
|---|---|---|---|
ton, gram |
TON | TON | Prepare or broadcast |
usdt_ton, usdt_gram |
TON | USDT | Prepare or broadcast |
usdt_eth |
Ethereum | USDT | External invoice |
usdt_pol |
Polygon | USDT | External invoice |
usdc_eth |
Ethereum | USDC | External invoice |
usdc_base |
Base | USDC | External invoice |
usdc_pol |
Polygon | USDC | External invoice |
Availability is subject to Fragment's response and operation-specific restrictions. Ads and Gateway recharge flows use native TON.
Know what happened
| State | Meaning |
|---|---|
| Prepared | An unsigned transaction exists; nothing has been broadcast |
| Broadcast | The wallet call returned; fulfillment has not necessarily completed |
| Confirmed | The purchase flow observed Fragment's completion signal |
| Unknown | The broadcast outcome could not be established; reconciliation is required |
Documentation
|
Integration Client and authentication |
Marketplace and operations Marketplace and search |
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
1 maintainer
Metadata
1 maintainer
Release files for fragment-api-py 14.1.0
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 |
|---|---|---|---|---|
| fragment_api_py-14.1.0.tar.gz | 73.4 kB | Without provenance | Details for fragment_api_py-14.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fragment_api_py-14.1.0-py3-none-any.whl | Python 3 | none | any | Details for fragment_api_py-14.1.0-py3-none-any.whl |
Total release size: 163.3 kB
Release files / fragment_api_py-14.1.0.tar.gz
| Download URL | fragment_api_py-14.1.0.tar.gz |
|---|---|
| Size | 73.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
856e90c7c607d4d8d359e5538d4213e69582acb2ea296153829b421071f4c97a
|
|
BLAKE2b-256 checksum How to use checksums |
dfff81c854780470ac4c4229b8f9d96cf2aeb9cf4ca8b8c1a4b39ed39b12b7e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / fragment_api_py-14.1.0-py3-none-any.whl
| Download URL | fragment_api_py-14.1.0-py3-none-any.whl |
|---|---|
| Size | 89.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3c3300b9155e126fe253c7aaa9e8c0e385aedb95876e1b02ff5d1ee90ba360a5
|
|
BLAKE2b-256 checksum How to use checksums |
68cc9d3af9f1b304ceb65185b6e6678e5a4824e42a2da1faeb752422d42b6a2e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for fragment-api-py 14.1.0
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.
