Marketplace and Search

Marketplace and Search

14.0.0 / Discovery

Home / Marketplace and Search / Asset Management

---

Recipient resolution

Method	Defaults
get_stars_recipient(username)	—
get_premium_recipient(username, months=3)	Three-month context
get_ads_topup_recipient(username)	—
get_giveaway_stars_recipient(channel, winners=1, amount=500)	Smallest Stars package
get_giveaway_premium_recipient(channel, winners=1, months=3)	One three-month subscription

These methods return RecipientInfo or None when no matching recipient is resolved.

Authentication, verification, minimum purchase, and other application failures are not equivalent to “recipient not found” and may raise exceptions.

Search methods

Method	Parameters
search_usernames	query="", sort=None, filter=None, offset_id=None
search_numbers	Same as username search
search_gifts	query="", collection=None, sort=None, filter=None, view=None, attr=None, offset=None
get_gift_filters	collection=None

Locally accepted sort values:

price, price_desc, price_asc, listed, ending

Locally accepted filters:

"", auction, sale, sold

A locally accepted value may still be unavailable for a particular server-side listing.

Pagination

Search	Result cursor	Next request argument
Usernames	next_offset_id	offset_id
Numbers	next_offset_id	offset_id
Gifts	next_offset	offset

Treat cursors as server-provided state.

• Stop when the cursor is None.
• Guard against repeated cursors.
• Bound your page count.
• Do not infer that a falsey numeric cursor is necessarily absent.
• Listing data can change between requests.

Search results contain item dictionaries with slug, name, status, price, and date.

Gift attributes

Accepted categories are Model, Backdrop, and Symbol.

The client accepts category names such as Model and wrapped field names such as attr[Model]. Values should be lists of exact strings returned by get_gift_filters.

The client JSON-encodes each value list. It does not flatten several values into an ambiguous comma-separated string.

Background is not an accepted replacement for Backdrop.

Use collection-specific filter values instead of assuming the same trait names exist in every collection.

Filter results

Model	Content
GiftCollection	Collection slug, display name, count, preview
GiftAttributeCategory	Original field name, display label, displayed total, values
GiftAttributeValue	Exact filter value, display label, count, preview

Responsive desktop and popup duplicates are merged by the parser.

Asset details

Method	Result
get_username_info(username)	UsernameInfo
get_number_info(number)	NumberInfo
get_gift_info(slug)	GiftInfo

Common information includes:

• Status and native exchange rate.
• Auction prices.
• End time and purchased date when present.
• Displayed owner wallet.
• Bid, ownership, and offer history.
• Independent history cursors.

Gift details additionally include images, sticker URL, attributes, rarity, and issuance text.

Number inputs may include a leading plus, spaces, and dashes.

Price queries

Method	Result
get_stars_price(quantity)	StarsPrice
get_stars_prices()	StarsPrices
get_premium_prices()	PremiumPrices

Prices remain decimal strings in these models.

Historical gram_price and gram_rate field names refer to native TON. Compatibility properties include ton_price and ton_rate.

Missing package price markup is not a reliable zero-cost quote.

Public history pagination

• get_orders_history(item_type, username, offset_id)
• get_owners_history(item_type, username, offset_id)
• get_offers_history(item_type, username, offset_id)

These methods return raw API dictionaries, not automatically appended typed history entries.

Item types are 1 for usernames, 3 for numbers, and 5 for gifts.

Private purchase history

These methods require a user-owned cookie session and are blocked in restricted wallet-auth mode:

Method	Default sort	Result
get_stars_history	desc	list[StarsTransaction]
get_premium_history	desc	list[PremiumTransaction]
get_topup_history	asc	list[TopupTransaction]

Public item history and private account purchase history are different capabilities.

Parser behavior

The parser supports full documents and partial table fragments.

It preserves:

• Native price precision.
• Desktop status labels instead of concatenated responsive duplicates.
• Ownership transfer labels.
• Section-specific history cursors.
• Requested account-tab counts.
• Gift rarity separately from trait values.

Parsing is not a substitute for validating the source response. Empty results can indicate changed markup, expired sessions, or legitimately empty pages.

When reporting a parsing issue, include a sanitized HTML fragment and the expected fields. Remove cookies, login codes, OAuth tokens, and private account data.

---

Examples: Marketplace search · Item details · Prices