Data Models

Data Models

14.0.0 / Typed results

Home / Data Models / Exceptions and Limits

---

Imports and serialization

Public models are available from:

• FragmentAPI
• FragmentAPI.types.models
• FragmentAPI.types.results

Models use Pydantic V2. Standard tools include model_dump, model_dump_json, and model_json_schema.

Compatibility properties are accessors and are not necessarily separate serialized fields.

Transaction lifecycle

TransactionResult

Field	Meaning
tx_hash	External-message identifier returned by the wallet integration
boc	Optional signed BOC
status	broadcast, confirmed, or unknown
confirmed	Whether Fragment fulfillment was established by the implemented flow
seqno_before, seqno_after	Optional ordinary-wallet sequence observations used to coordinate the next send, never fulfillment proof
balance_before, balance_after	Optional display balances
payment_nanoton	Exact native principal
fee_nanoton	Separate native library fee
confirmation_error	Confirmation failure or timeout description
operation_id	Durable payment journal identifier

Optional sequence and balance fields are not a guarantee that the SDK measured both before and after values.

A sequence-number change is not used as proof of this invoice's fulfillment.

PurchaseResult

Fields:

transaction_id, type, username, amount, payment_method, confirmed, fee_nanoton, req_id, confirmation_error, operation_id.

amount means Stars, Premium months, or whole TON top-up quantity according to the operation.

PremiumResult, StarsResult, and AdsTopupResult remain public compatibility subclasses. The current single-purchase dispatcher returns PurchaseResult.

Giveaway results

GiveawayStarsResult contains:

transaction_id, channel, winners, amount, payment_method, confirmed, fee_nanoton, req_id, confirmation_error, operation_id.

GiveawayPremiumResult has the same structure. Its amount is the duration in months.

Prepared transactions

PreparedTransaction

Field	Meaning
req_id	Fragment request identifier
item_kind	Operation category
target	Recipient or account
amount	Operation quantity
valid_until	Expiration timestamp
messages	Final unsigned message list
raw	Original response data
sender_address	Requested sender identity
confirm_referer	Original invoice page path
payment_method	Normalized payment method
payment_nanoton	Exact native principal
fee_nanoton	Appended native fee amount
gas_reserve_nanoton	Preflight reserve
required_nanoton	Outgoing native value plus reserve
required_usdt_units	Exact required USDT units, when applicable

Preparation is not payment.

PreparedTransactionMessage

Field	Meaning
address	Destination
amount	Integer nanotons encoded as a string
payload	Optional base64 BOC
state_init	Optional state initialization

The serialization alias for state_init is stateInit. Use alias-aware serialization when constructing a TON Connect transaction.

Do not reconstruct payment messages from the diagnostic raw field and accidentally omit appended messages.

EVM invoices

EvmPaymentResult

item_kind, target, amount, payment_method, invoice.

EvmInvoice

Group	Fields
Identity	req_id, payment_method
Network	invoice_chain_id, invoice_chain_name
Contracts	invoice_address, invoice_token
Amount	invoice_amount_hex, invoice_amount_raw, invoice_amount
Token	token_symbol, token_decimals
Lifetime	expires_at
Fragment context	api_hash, page_url

Use the integer raw amount for payment execution. The floating-point amount is for display.

Batch results

PurchaseItem

Input fields:

type, username, amount, months, show_sender.

amount and months use strict integers.

BatchItemResult

Field	Meaning
type, username, amount	Input summary
ok	Item was prepared or its broadcast call returned
result	Actual typed operation result
error	Failure description
chunk_index	0: every invoice belongs to the same wallet submission
status	prepared, broadcast, confirmed, failed, or unknown

BatchResult

total, succeeded, failed, chunks_sent, items, prepared_transactions, transaction, receipt, operation_id.

transaction is the combined unsigned payload; prepared_transactions are component invoices for inspection in preparation mode. Do not send both. chunks_sent is 0 or 1 known accepted broadcasts. An attempted uncertain send has 0, with item status unknown. All broadcast items share the wallet message identifier and operation id. BatchItemResult.result is PurchaseResult | PreparedTransaction | None.

succeeded includes prepared results. It is not a fulfillment counter.

NoKycBatchResult is a compatibility subclass returned in restricted wallet-auth mode.

Payment recovery models

PaymentConfirmation stores transaction, account, req_id, page_url, optional state_method, and optional per-invoice receipt for reporting the original BOC with the original Fragment session.

PaymentRecord contains:

Field	Meaning
operation_id, sender_address	Journal identity and canonical payer
state	sending, broadcast, confirmed, unknown, settled, or not_broadcast
prepared	Full unsigned intent
receipt	Signed message hash/BOC and latest known combined receipt
confirmations	Per-invoice confirmation contexts and receipts
error	Recorded broadcast problem
resolution_evidence	Operator-supplied reference after independent chain verification

sending after a process exit is uncertain. settled records wallet processing, not Fragment fulfillment. not_broadcast is an operator assertion requiring verified absence and expiration. Records and signed BOCs are sensitive; avoid public logging. See Payment Batches and Recovery.

Wallet and account models

Model	Important fields
WalletInfo	address, state, gram_balance, usdt_balance, balance_nanoton
ProfileInfo	name, username, photo_url, identity_verified, wallet_address, wallet_label, wallet_verified
RecipientInfo	recipient, name, photo_url, myself
SessionInfo	session_id, device, location, date, is_current
LoginCodeResult	number, code, active_sessions
TerminateSessionsResult	number, message

WalletInfo.usdt_balance may be None.

Aliases include balance_ton and balance_usdt.

Do not serialize login-code or session data into public logs.

Marketplace results

Model	Contents
UsernamesResult	Item dictionaries and next_offset_id
NumbersResult	Same structure
GiftsResult	Item dictionaries and numeric next_offset
GiftFiltersInfo	Collections and attribute categories
GiftCollection	slug, name, count, image_url
GiftAttributeCategory	field, name, total_count, items
GiftAttributeValue	name, value, count, image_url

Listing item dictionaries use slug, name, status, price, and date.

Asset details

ItemInfo provides:

• item_type, status, gram_rate.
• auction, auction_end.
• owner_wallet, purchased_date.
• Bid, ownership, and offer lists.
• A separate next-offset field for each history list.

Specializations:

Model	Additional fields
UsernameInfo	username
NumberInfo	number, display_number, restricted
GiftInfo	slug, name, image_url, sticker_url, attributes, issued

GiftAttribute contains name, value, and optional rarity.

AuctionInfo contains highest_bid, bid_step, minimum_bid, sell_price, and buy_now_price.

History entry models contain price, date, and wallet. Ownership history may use Transferred as a price label.

Prices and account history

Model	Fields
StarsPrice	stars, gram_price, usd_price
StarsPrices	packages, gram_rate
PremiumPriceOption	months, label, gram_price, usd_price, discount
PremiumPrices	options, gram_rate
StarsTransaction	recipient, stars, price_gram, date
PremiumTransaction	recipient, duration, price_gram, date
TopupTransaction	recipient, amount, date

Historical gram field names refer to native TON. Compatibility properties include ton_price, ton_rate, and price_ton.

Inventory and management

Model	Contents
MyAsset	Category, slug, name, description, image, assignment identifier and label
MyAssetsResult	items, total_count, gram_rate
MyBid	Category, slug, name, bid, status, date, image, description
MyBidsResult	items, total_count, gram_rate
TelegramAccount	id, name, type, photo_url
AssignAccountsResult	accounts, can_disable
AssignResult	ok, message, need_pay, req_id, amount, assign_name
SubscriptionResult	ok, subscribed, item_type, slug

Marketplace transaction receipts

Model	Fields
BidResult	transaction_id, item_type, slug, bid, confirm_method, confirm_id, confirmed, fee_nanoton, operation_id
OfferResult	transaction_id, item_type, slug, amount, req_id, confirmed, fee_nanoton, operation_id
StartAuctionResult	ok, req_id, transaction_id, confirmed, operation_id

These models do not all expose a confirmation_error field. Do not assume their confirmed behavior is identical to the purchase poller.

Transfers and withdrawals

NftTransferRecipient extends recipient information.

NftTransferRequest contains req_id, myself, item_title, content, and button.

Withdrawal initialization models share:

ok, confirm_message, confirm_button, confirm_hash, error.

Withdrawal confirmation models share:

ok, need_update, mode, html, error.

This structure is used by NFT, Stars, and Ads withdrawal subclasses.

StarsWithdrawalState contains transaction and withdrawal_data.

Ads and Gateway

Model	Fields
GatewayPriceInfo	credits, gram_price, usd_price
GatewayRechargeResult	transaction_id, account_id, credits, req_id, confirmed, fee_nanoton, confirmation_error, operation_id
AdsRechargeResult	transaction_id, account_id, amount, req_id, confirmed, fee_nanoton, confirmation_error, operation_id

---

Purchases and Giveaways · Exceptions and Limits · Examples