Client and Authentication

Client and Authentication

14.0.0 / Integration

Home / Client and Authentication / Next: Purchases

---

Configuration reference

FragmentClient accepts the following constructor parameters.

Parameter	Default	Meaning
cookies	None	Dictionary, JSON string, or Cookie header string
seed	None	Payer mnemonic
api_key	None	TON provider key
api_provider	tonapi	tonapi or toncenter
wallet_version	V5R1	Payer wallet contract
timeout	30.0	Fragment HTTP session timeout
proxy	None	Fragment/auth HTTP or SOCKS proxy
session_storage	None	Optional user-session persistence backend
session_id	None	Persistence identifier
auto_refresh_cookies	False	Refresh proof after supported session-expiration responses
shared_auth_seed	Built-in value	Restricted authentication seed override
sender_account	None	Complete external signer's TON Connect account
gas_reserve_nanoton	50_000_000	Native balance reserve used during preflight
confirmation_timeout	60.0	Purchase fulfillment polling window
wallet_auth	Inferred	Explicit capability-mode override
payment_storage	SQLitePaymentStorage()	Durable automatic-payment journal
wallet_lock_factory	Local OS file lock	Callable receiving canonical payer address and returning an async context manager

The parameters beginning with shared_auth_seed are keyword-only.

The proxy setting is passed to Fragment and authentication sessions. The current blockchain-provider factory does not forward this proxy setting to tonutils.

Wallet versions

Version	Configured message limit
V4R2	4
V5R1	255
HighloadV2	254
HighloadV3R1	64,516
WalletTg	255

Names are resolved case-insensitively. These limits follow the installed contract classes and apply to the complete combined wallet message list, including the native fee message. A batch is never automatically split.

The installed tonutils version must expose the required wallet classes and transfer APIs. Preparation can reject a payload when the installed transfer builder cannot preserve its state initialization.

Mnemonics

The validator accepts 12-, 18-, and 24-word phrases that pass basic TON mnemonic validation.

A phrase with the correct word count is not necessarily valid. Placeholder words in old examples are not usable wallet credentials.

Use the correct contract version for the actual payer wallet.

Cookies

Supported formats:

• A string-to-string dictionary.
• A JSON object string.
• A semicolon-separated Cookie header string.

Cookie mode validates stel_ssid, stel_dt, and stel_token.

stel_ton_token is additionally required by automatic cookie-mode invoice payments and account transaction helpers.

Account read methods do not all locally require stel_ton_token; the server still decides whether the supplied session is authorized.

Providing an empty cookie value does not create a full account session. Without usable cookies, the default mode is restricted wallet authentication.

Explicit authentication

FragmentClient.authenticate performs wallet proof followed by interactive Telegram authentication when needed.

Argument	Default
seed	Required
wallet_version	V5R1
phone	None
print_qr	True
on_status	None
timeout	30.0
proxy	None

When phone is omitted, the flow uses an OAuth link and optional terminal QR rendering.

Progress callbacks receive a status and payload. Current emitted statuses include qr_link, phone_sent, consumed, and confirmed. A refreshed QR token is reported through another qr_link event.

The callback may be synchronous or asynchronous.

The utility-level authentication function has an auth_timeout parameter, defaulting to 180 seconds. The static client wrapper does not expose that parameter.

Source: authentication.py

Refreshing a session

refresh_cookies() refreshes wallet proof.

• Restricted mode uses the shared authentication seed.
• Cookie mode requires the configured payer seed.
• It does not silently launch Telegram OAuth.
• It invalidates cached Fragment API hashes.
• Full-account cookies are persisted when storage is configured.

Refreshing wallet proof does not guarantee that an expired Telegram login becomes valid again.

With auto_refresh_cookies=True, the client retries once after recognized session expired or unauthorized application responses.

External sender accounts

sender_account must include:

Key	Meaning
address	TON account address
chain	Mainnet identifier, -239
publicKey	Account public key
walletStateInit	Account state initialization

It takes precedence over local account derivation.

If automatic broadcasting is enabled, the signing wallet must match the invoice sender.

For external signing, configure the actual external account. The shared authentication wallet is never selected as a payer or external-signing fallback. A missing payer seed and missing sender_account cause TON preparation to fail before invoice initialization.

Session storage

FileSessionStorage

Parameter	Default
directory	.fragment_sessions
file_extension	.json

Session identifiers are mapped to SHA-256-based filenames. Writes use a temporary file followed by atomic replacement.

RedisSessionStorage

Parameter	Default
redis_url	redis://localhost:6379/0
prefix	fragment:session:
ttl	None

Install the redis extra. A configured TTL must be a positive integer.

Close Redis storage with aclose() or its compatibility alias close(). Closing FragmentClient does not close an independently supplied Redis storage backend.

Shared storage interface

• save(session_id, cookies, metadata=None)
• load(session_id)
• delete(session_id)
• exists(session_id)
• load_metadata(session_id)

Calling save without metadata preserves existing metadata. The client itself supplies its cookie-mode metadata when saving.

Storage failures are propagated rather than treated as missing sessions.

Loading through FragmentClient

from_storage(session_storage, session_id, **kwargs) loads a session.

If no session exists:

• Without a seed, it raises CookieError.
• With a seed, it initiates explicit full authentication.

Use a direct storage lookup first if your application must never start an interactive login unexpectedly.

Restricted shared-wallet sessions are not persisted by the client.

Source: session_storage.py

Payment persistence and coordination

Session storage holds Fragment cookies; payment storage is a separate interface for signed intents and receipts. SQLitePaymentStorage(path=None) defaults to ~/.fragment-api/payments.sqlite3. A custom PaymentStorage implements async save(record), get(operation_id), and list(sender_address=None).

The journal stores signed BOCs and invoice contexts, without mnemonic phrases, provider API keys, or cookies. Preserve it across restarts and protect its access. Closing a client does not delete payment records.

Default OS locks under ~/.fragment-api/wallet-locks coordinate local clients/processes sharing the same home and journal. A custom wallet_lock_factory(address) must return an async context manager holding an exclusive payer lock through signing, journal persistence, send, and wallet sequence observation. Multiple hosts require both a shared store and a distributed lock factory.

Recovery methods are get_payment, list_payments, reconcile_payment, and resolve_payment. See Payment Batches and Recovery for signatures, deployment requirements, and operator evidence rules.

Timeouts must be finite positive numeric values; booleans and numeric strings are rejected.

Lifecycle and properties

Use an asynchronous context manager or call aclose().

The client owns one reusable HTTP session, created lazily. Closing is idempotent, and session cleanup still runs if persistence fails.

Property	Meaning
wallet_auth	Restricted capability mode
nokyc_mode	Compatibility alias for wallet_auth
has_wallet	Payer seed and provider key are configured
has_cookies	Cookie dictionary is nonempty
has_ton_token	Wallet-session cookie is present
session_storage	Configured persistence backend

has_cookies does not prove that a session is valid or that it represents a full account.

---

Home · Purchases and Giveaways · Examples