Examples

Examples

14.0.0 / Executable workflows

Home / Examples

---

Source, not copied snippets

Examples live in the repository so that configuration, execution guards, and lifecycle handling stay in one place.

Open the examples directory

Read workspace configuration

This page explains which example to choose and what it does. Python source is linked rather than duplicated here.

How execution works

Each script exposes named actions.

Use its --help option to see the available actions. Run scripts from the repository root using their file path.

All examples use environment variables through _common.py.

Execution classes

Class	Meaning
Read	Fetches data without enabling automatic payment
Prepare	Creates an unsigned TON invoice
Invoice	Creates an unpaid external EVM invoice
Pay	May broadcast a transaction; requires --execute
Mutate	Changes account state; requires --execute
Local	Demonstrates behavior without network access

--execute authorizes the selected example action. Review the source and configured destination before using it.

01 / Setup and authentication

File	Actions	How it works
basic_setup.py	read, payer, highload, external	Builds configurations and displays credential-free client information
authentication.py	qr, phone	Runs interactive Telegram authentication and saves cookies without printing them
wallet_auth.py	quote, restrictions, purchase	Demonstrates restricted sessions and separation of authentication wallet from payer
session_storage.py	files, redis	Loads an existing full session and closes Redis resources explicitly

Start here: basic_setup.py, then authentication.py if you need user-owned account operations.

The session-storage example intentionally does not start interactive authentication when a session is missing.

02 / Stars, Premium, and giveaways

File	Actions	How it works
purchase_stars.py	recipient, prepare, purchase, usdt, hidden-sender	Separates recipient lookup, unsigned preparation, and native or USDT payment
purchase_premium.py	recipient, prepare, purchase, evm	Demonstrates three-month gifts and an external Base invoice
batch_purchase.py	prepare, purchase, highload	Prepares all invoices, sends one combined wallet message, and retains per-invoice outcomes
giveaways.py	recipients, prepare, stars, premium	Uses total Stars packages and separately configured Premium winner counts

Important: batch succeeded includes prepared items. It does not mean that every recipient has received the service.

Batches use one wallet submission for both ordinary and highload wallets. Highload mode increases capacity; downstream invoice fulfillment remains independent. In preparation mode, sign result.transaction once, not each component invoice. See Payment Batches and Recovery.

03 / External payment integrations

File	Actions	How it works
external_signing.py	prepare, confirm	Exports the complete unsigned TON message list and separately reports an already broadcast signed BOC
evm_payment_automation.py	ethereum, base, polygon	Requests EVM invoices and displays exact raw token amounts for an external integration

The historical EVM example filename is retained, but the updated example deliberately does not broadcast EVM transactions.

For external TON signing:

• Use the actual signer's account.
• Preserve every outgoing message.
• Observe expiration.
• Keep the original Fragment session available.
• Do not treat confirm_request as a fulfillment receipt.

The exported unsigned JSON file does not contain or restore the original Fragment session.

04 / Ads and Gateway

File	Actions	How it works
topup_grams.py	recipient, prepare, topup, unified	Shows native TON Ads top-ups and the unified purchase dispatcher
gateway_and_ads.py	quote, prepare-gateway, gateway, ads	Quotes Gateway credits and recharges explicitly supplied account identifiers

topup_grams.py keeps its historical filename. The native asset is TON.

05 / Marketplace discovery

File	Actions	How it works
search_marketplace.py	usernames, numbers, gifts, filters, filtered	Uses bounded pagination, repeated-cursor protection, and exact gift filter values
item_details.py	username, number, gift, history	Reads asset details and follows a public history cursor
prices.py	stars, custom, premium	Reads package and custom-quantity prices

Use filters before filtered to discover valid collection-specific values.

These examples do not enable an automatic payer.

06 / Account operations

File	Actions	How it works
wallet_and_profile.py	wallet, profile, sessions, terminate, refresh	Separates blockchain balance inspection from private profile and session operations
transaction_history.py	stars, premium, topups	Reads user-owned purchase history
marketplace_bids_and_auctions.py	assets, bids, bid, offer, auction, sell, cancel, destinations, assign, subscribe, unsubscribe	Manages explicitly selected owned assets and marketplace actions

The assignment example disables automatic bot-assignment payment so that a returned payment requirement can be reviewed first.

The session-termination example requires an exact session ID. It does not terminate the first session in a list.

07 / Transfers, withdrawals, and numbers

File	Actions	How it works
nft_transfers_and_withdrawals.py	recipient, transfer, nft-init, nft-confirm, stars-init, stars-confirm, ads-init, ads-confirm	Keeps withdrawal initialization separate from explicit challenge approval
anonymous_numbers.py	code, poll, enable, disable, terminate	Reads code availability without logging the code and guards account mutations

Use these only with a user-owned full-account session.

Withdrawal approval hashes and opaque state belong to the original approval flow.

08 / Integration behavior

File	Actions	How it works
raw_api_calls.py	search, prices, confirm	Demonstrates raw response handling and original-session BOC reporting
error_handling.py	validation, restrictions, purchase	Separates local validation, capability restrictions, wallet failures, and broadcast uncertainty
backward_compatibility.py	aliases	Checks retained names and properties without network access
logging_setup.py	console, library	Configures logging without claiming automatic HTTP tracing

Do not retain an example named logging.py beside these scripts. It can shadow Python's standard logging module.

Result interpretation

The shared result printer distinguishes:

• Prepared, not broadcast.
• EVM invoice, not paid.
• Broadcast identifier.
• Fragment confirmation state.
• Batch item status.

It deliberately does not print seeds, cookies, or signed BOCs.

Production adaptation checklist

Before turning an example into a service:

• Move secrets into your deployment's secret manager.
• Preserve the configured payment journal across deployments and add application request/idempotency records.
• Share the journal/home for local OS locks; configure shared payment storage and distributed locks for multiple hosts.
• Implement operation-specific authorization.
• Review prepared messages before signing.
• Keep cancellation and process-restart recovery in mind.
• Do not automatically retry uncertain payments.
• Test sanitized HTML fixtures against the installed parser.
• Handle non-library transport and dependency exceptions at the application boundary.

---

Workspace configuration · Payment lifecycle · Issue tracker