FragmentAPI/CHANGELOG.md

Changelog

All notable changes to pyfragment are documented in this file.

The format is based on Keep a Changelog, and this project uses Calendar Versioning (YYYY.MINOR.MICRO).

---

[Unreleased]

Added

• payment_method option ("ton" / "usdt_ton") for:
  • purchase_stars()
  • purchase_premium()
  • giveaway_stars()
  • giveaway_premium()

Changed

• Added runtime validation for payment_method via SUPPORTED_PAYMENT_METHODS and ConfigurationError.INVALID_PAYMENT_METHOD
• Updated method docstrings to explicitly document recipient/channel formats:
  • @username / username / https://t.me/username
• get_wallet() now returns balances as separate fields: ton_balance and usdt_balance
• Wallet/system test output now prints TON and USDT balances on separate lines

Tests

• Extended stars and premium test suites to cover:
  • invalid payment method
  • payment method propagation to init*Request payloads
  • accepted query formats (@, plain username, t.me link)
• Extended wallet tests to verify separate TON/USDT balance values in WalletInfo

Documentation

• Simplified README usage example

2026.2.1 — 2026-05-03

Fixed

• Fragment API 429 responses are now retried automatically (up to 3 attempts) with exponential backoff and jitter in fragment_request
• Retry delays in TON transaction broadcasting now include jitter to reduce contention under concurrent calls
• Improved handling of non-200 HTTP responses in get_fragment_hash
• Removed unnecessary method key leaking into certain API request payloads

Changed

• Type hints refined across the codebase for better clarity and mypy strict compliance

---

2026.2.0 — 2026-04-14

Added

• get_cookies_from_browser(browser) — extract Fragment session cookies directly from an installed browser (Chrome, Firefox, Edge, Brave, Arc, Opera, Safari, and more); no browser extension or manual copy-paste required

  from pyfragment.utils import get_cookies_from_browser
  result = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
  client = FragmentClient(seed="...", api_key="...", cookies=result.cookies)
  print(result.expires)  # ISO 8601 expiry of stel_ssid, or None for session cookies
  

• CookieResult — return type of get_cookies_from_browser(); exposes .cookies (dict[str, str]) and .expires (ISO 8601 string or None)

Changed

• DEVICE Tonkeeper fingerprint updated: appVersion → 26.04.0
• tonutils upgraded to 2.1.0
• Minimum Python version lowered to 3.10 (previously 3.12)

---

2026.1.0 — 2026-03-25

Added

Giveaways

• giveaway_stars(channel, winners, amount) — Stars giveaway; 1–5 winners, 500–1 000 000 stars each
• giveaway_premium(channel, winners, months) — Premium giveaway; 1–24 000 winners, 3/6/12 months each
• StarsGiveawayResult, PremiumGiveawayResult result types

Telegram Ads

• recharge_ads(account, amount) — top up a Telegram Ads account; 1–1 000 000 000 TON
• AdsRechargeResult result type

Marketplace

• search_usernames(query?, sort?, filter?, offset_id?) — search Fragment usernames; sort: price_desc / price_asc / listed / ending, filter: auction / sale / sold
• search_numbers(query?, sort?, filter?, offset_id?) — search Fragment anonymous numbers; same sort / filter / pagination semantics
• search_gifts(query?, collection?, sort?, filter?, view?, attr?, offset?) — search Fragment gifts; attr accepts {"Model": ["Foosball"], "Backdrop": ["Celtic Blue"]}
• UsernamesResult, NumbersResult, GiftsResult result types

Anonymous numbers

• get_login_code(number) — fetch the current pending login code
• toggle_login_codes(number, can_receive) — enable or disable login code delivery
• terminate_sessions(number) — terminate all active Telegram sessions (two-step flow handled internally)
• LoginCodeResult, TerminateSessionsResult result types; AnonymousNumberError exception

Raw API

• FragmentClient.call(method, data, *, page_url) — raw request to any Fragment API method
• FRAGMENT_BASE_URL constant — base URL shared across all page constants and headers

Examples

• examples/client/ — wallet_info.py (wallet info), raw_api_call.py (raw API call)
• examples/numbers/ — manage_number.py (login code fetch, session termination)
• examples/auctions/ — search_usernames.py, search_numbers.py, search_gifts.py (marketplace search with pagination)
• examples/purchase/ — send_stars.py, send_premium.py, topup_ton_balance.py, run_stars_giveaway.py, run_premium_giveaway.py, recharge_ads_balance.py

Changed

• All result types now expose a unified amount field (months and stars removed)
• __repr__ includes the unit — 3 months, 500 stars, etc.
• timestamp removed from all result dataclasses
• All page URL constants built from FRAGMENT_BASE_URL;
• TransactionError includes an SSL hint; DUPLICATE_SEQNO variant auto-retried up to 2 times (2 s apart)
• Error messages rewritten: "what happened → why → what to do"

---

2026.0.2 — 2026-03-20

Added

• timeout parameter on FragmentClient (default 30.0 s) — passed through to every HTTP request

Changed

• Cookie validation: narrowed type internally so no # type: ignore is needed in FragmentClient.__init__
• WALLET_CLASSES typed as dict[str, Any] so mypy resolves from_mnemonic correctly
• All four examples/ files updated to async with FragmentClient, f-strings, and aligned error messages
• README usage section rewritten with a single comprehensive async with example

Fixed

• mypy: missing return path in process_transaction after retry loop
• mypy: cookies union-attr error in FragmentClient.__init__

---

2026.0.1 — 2026-03-16

Added

• Initial stable release of pyfragment
• FragmentClient — async client for the Fragment.com API with context manager support (async with)
• purchase_premium(username, months) — purchase Telegram Premium for any user (3, 6, or 12 months)
• purchase_stars(username, amount) — send Telegram Stars to any user (50–1,000,000)
• topup_ton(username, amount) — top up TON Ads balance (1–1,000,000,000 TON)
• get_wallet() — fetch wallet address and balance
• Support for TON wallet versions V4R2 and V5R1
• Structured exception hierarchy (FragmentError, ConfigurationError, CookieError, etc.)
• py.typed marker — full PEP 561 typing support for type-checkers
• __repr__ on all result types for readable debug output