Repository navigation
Home
Documentation / 14.0.0
Authentication, payments, marketplace data, and account operations.
Note
Payment batches, durable recovery, and process coordination below describe version 14.0.0. Review the migration notes when upgrading from version 13.
| Step | Read | Outcome |
|---|---|---|
| 01 / Configure | Client and Authentication | Choose a session, payer, and persistence strategy |
| 02 / Integrate | Purchases and Giveaways | Understand invoices and payment states |
| 02a / Recover | Payment Batches and Recovery | Submit one wallet message and recover interrupted payments |
| 03 / Discover | Marketplace and Search | Search assets and consume pagination |
| 04 / Operate | Asset Management | Manage user-owned assets and sessions |
| 05 / Observe | Data Models · Exceptions and Limits | Interpret results without guessing |
| 06 / Run | Examples | Select an executable workflow |
Install fragment-api-py from PyPI with pip install fragment-api-py.
Python 3.10+ is required.
Optional extras are redis, qr, and dev. For example, pip install "fragment-api-py[redis,qr]" adds Redis storage and terminal QR rendering.
Supply your own Fragment cookies.
This mode permits account-scoped operations, subject to Fragment authorization. Configure a payer separately when an operation requires an on-chain payment.
Minimum cookie keys: stel_ssid, stel_dt, and stel_token.
Automatic account-mode TON payments also require stel_ton_token.
Omit cookies to select wallet_auth.
The SDK authenticates a restricted Fragment session using a shared V5R1 wallet proof. The configured payer seed remains separate.
Allowed workflows include recipient search, price queries, marketplace reads, and supported purchase requests. Profile, private history, asset management, sessions, anonymous-number account operations, and withdrawals are blocked.
Important
wallet_auth is a capability restriction, not a promise of verification-free access.
Fragment may still require identity verification.
nokyc_mode remains only a compatibility alias.
| Configuration | Outcome |
|---|---|
| Payer seed and provider key | Automatic TON broadcasting where supported |
| Sender account or derivable payer account, without automatic payment credentials | Unsigned TON preparation |
| EVM method | External EVM invoice |
For external signing, supply the real signer's TON Connect account. Do not use the shared authentication wallet as your payment identity.
| Methods | Network | Asset |
|---|---|---|
ton, gram
|
TON | TON |
usdt_ton, usdt_gram
|
TON | USDT |
usdt_eth |
Ethereum | USDT |
usdt_pol |
Polygon | USDT |
usdc_eth |
Ethereum | USDC |
usdc_base |
Base | USDC |
usdc_pol |
Polygon | USDC |
EVM methods return invoices. The SDK does not broadcast EVM transactions.
| Version 13 behavior | Version 14 behavior |
|---|---|
| Separate invoice broadcasts in a batch | Prepare all invoices, then submit one wallet message |
| Continue after some item preparation errors | Raise before sending if batch preparation fails |
| Arbitrarily large batches | Reject capacity overflow without automatically splitting |
| Shared auth wallet can be a fallback sender | Require an explicit sender account or payer seed |
| Generic page completion can confirm a purchase | Require completion correlated with the invoice id |
| Payment recovery is application-owned | Durable signed-intent journal and recovery APIs |
| A client-instance lock coordinates sends | OS payer lock across local processes; shared adapters for multiple hosts |
| Historical native service fee | 1.5% of explicit native principal, separate from network fees |
Preserve ~/.fragment-api or configure persistent payment storage, keep the original Fragment session for invoice confirmation, and use BatchResult.transaction for a single external signature. Do not also broadcast the component invoices. See Payment Batches and Recovery.
| Previous behavior or assumption | Version 13 |
|---|---|
| MarketApp fallback | Removed; restricted wallet-proof authentication replaces it |
marketapp_token |
Removed from the constructor |
MarketAppAPIError |
Removed |
| “No KYC” as a guarantee | Not provided |
| Batch means one transaction | Version 13 processed invoices separately; version 14 restores one combined wallet submission |
| Sent means delivered | Check fulfillment fields |
| Confirmation from seqno or balance changes | Not used as proof of this invoice |
Highload version HIGHLOAD_V3
|
Use HighloadV3R1
|
| Sender can always be changed after preparation | Preserve the requested sender identity |
| All USDT lookup failures mean zero balance | An unavailable balance can be None
|
| Float and boolean quantities are accepted | Integer inputs are strict |
| Shared session can manage an account | Account operations are blocked |
Supported compatibility names include ConfigError, topup_gram, topup_ton, gram payment aliases, ton_price, ton_rate, and NoKycBatchResult.
- Batches validate and prepare all invoices before a single wallet submission; capacity/preparation failures send nothing.
- Native fees use
FEE_BASIS_POINTS / 100percent (150means 1.5%), independently of network fees. - A signed BOC and invoice contexts are journaled before automatic broadcast.
-
get_payment,list_payments,reconcile_payment, and evidence-basedresolve_paymentsupport recovery without automatic repayment. - TON preparation requires a real payer seed or complete
sender_account; the shared auth wallet is never a payer. - Fulfillment requires a completion response matching the invoice id; uncorrelated page state stays unconfirmed.
See Payment Batches and Recovery for the execution contract and deployment requirements.
- Never store funds in the shared authentication wallet.
- Do not print mnemonics, cookies, OAuth tokens, login codes, or signed BOCs.
- Session storage is not an encrypted secret vault.
- Reconcile uncertain broadcasts instead of creating replacement payments.
- OS wallet locks coordinate local clients/processes sharing the same home and journal. Multiple hosts need shared storage and a distributed lock factory.
- Server behavior and HTML can change without an SDK release.
This is an unofficial project, not an official Fragment or Telegram API.
Repository · Examples · Issues · Telegram