",
- "username": "@username",
- "amount": 10, # or "months" for Premium
- "timestamp": 1741234567
- }
-}
-```
-
-**Return format** (on failure):
-
-```python
-{
- "success": False,
- "error": "Telegram user '@unknown' was not found on Fragment."
-}
-```
-
-### Supported Operations
-
-| Operation | Function | Parameters | Limits |
-| ------------------ | ----------------------------------------------------- | ----------------------------------- | ------------------- |
-| **TON Topup** | `topup_ton(username, amount, show_sender=True)` | Username, TON amount, show sender | 1โ1,000,000,000 TON |
-| **Premium Gift** | `buy_premium(username, months, show_sender=True)` | Username, duration, show sender | 3, 6, or 12 months |
-| **Stars Purchase** | `buy_stars(username, amount, show_sender=True)` | Username, Stars amount, show sender | 50โ1,000,000 Stars |
-
-Usernames can be passed with or without `@`.
+---
diff --git a/examples/client_init.py b/examples/client_init.py
new file mode 100644
index 0000000..e81ed8d
--- /dev/null
+++ b/examples/client_init.py
@@ -0,0 +1,36 @@
+"""
+Example: initializing FragmentClient.
+
+Cookies can be passed as a dict or as a JSON string.
+wallet_version defaults to "V5R1" โ change to "V4R2" for older wallets.
+"""
+
+import asyncio
+
+from fragmentapi import FragmentClient
+
+SEED = "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12 word13 word14 word15 word16 word17 word18 word19 word20 word21 word22 word23 word24"
+API_KEY = "YOUR_TONAPI_KEY"
+COOKIES = {
+ "stel_ssid": "YOUR_STEL_SSID",
+ "stel_dt": "YOUR_STEL_DT",
+ "stel_token": "YOUR_STEL_TOKEN",
+ "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+
+async def main() -> None:
+ client = FragmentClient(
+ seed=SEED,
+ api_key=API_KEY,
+ cookies=COOKIES,
+ wallet_version="V5R1", # or "V4R2"
+ )
+
+ print("FragmentClient initialized")
+ print(" %-16s %s" % ("Wallet version:", client.wallet_version))
+ print(" %-16s %s..." % ("API key:", client.api_key[:8]))
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/gift_premium.py b/examples/gift_premium.py
new file mode 100644
index 0000000..661843d
--- /dev/null
+++ b/examples/gift_premium.py
@@ -0,0 +1,45 @@
+"""
+Example: gift Telegram Premium to a user.
+
+Supported durations: 3, 6, or 12 months.
+Set show_sender=False to send anonymously.
+"""
+
+import asyncio
+
+from fragmentapi import ConfigurationError, FragmentClient, UserNotFoundError
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_TONAPI_KEY"
+COOKIES = {
+ "stel_ssid": "YOUR_STEL_SSID",
+ "stel_dt": "YOUR_STEL_DT",
+ "stel_token": "YOUR_STEL_TOKEN",
+ "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+USERNAME = "@username"
+MONTHS = 3 # 3, 6, or 12
+
+
+async def main() -> None:
+ client = FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES)
+
+ try:
+ result = await client.gift_premium(USERNAME, months=MONTHS, show_sender=True)
+ except UserNotFoundError:
+ print(f"User {USERNAME!r} not found on Fragment.")
+ return
+ except ConfigurationError as e:
+ print(f"Invalid parameters: {e}")
+ return
+
+ print("Premium gifted")
+ print(" %-14s %s" % ("Username:", result.username))
+ print(" %-14s %s months" % ("Duration:", result.months))
+ print(" %-14s %s" % ("Transaction:", result.transaction_id))
+ print(" %-14s %s" % ("Timestamp:", result.timestamp))
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/gift_stars.py b/examples/gift_stars.py
new file mode 100644
index 0000000..3f5ef7f
--- /dev/null
+++ b/examples/gift_stars.py
@@ -0,0 +1,45 @@
+"""
+Example: gift Telegram Stars to a user.
+
+Amount must be an integer between 50 and 1 000 000.
+Set show_sender=False to send anonymously.
+"""
+
+import asyncio
+
+from fragmentapi import ConfigurationError, FragmentClient, UserNotFoundError
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_TONAPI_KEY"
+COOKIES = {
+ "stel_ssid": "YOUR_STEL_SSID",
+ "stel_dt": "YOUR_STEL_DT",
+ "stel_token": "YOUR_STEL_TOKEN",
+ "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+USERNAME = "@username"
+AMOUNT = 500 # 50โ1 000 000
+
+
+async def main() -> None:
+ client = FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES)
+
+ try:
+ result = await client.gift_stars(USERNAME, amount=AMOUNT, show_sender=True)
+ except UserNotFoundError:
+ print(f"User {USERNAME!r} not found on Fragment.")
+ return
+ except ConfigurationError as e:
+ print(f"Invalid parameters: {e}")
+ return
+
+ print("Stars gifted")
+ print(" %-14s %s" % ("Username:", result.username))
+ print(" %-14s %s" % ("Stars:", result.stars))
+ print(" %-14s %s" % ("Transaction:", result.transaction_id))
+ print(" %-14s %s" % ("Timestamp:", result.timestamp))
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/topup_ton.py b/examples/topup_ton.py
new file mode 100644
index 0000000..abf2abf
--- /dev/null
+++ b/examples/topup_ton.py
@@ -0,0 +1,48 @@
+"""
+Example: top up a Telegram Ads account with TON.
+
+Amount must be an integer between 1 and 1 000 000 000 TON.
+Your wallet must hold at least the topup amount + ~0.056 TON for gas.
+"""
+
+import asyncio
+
+from fragmentapi import ConfigurationError, FragmentClient, UserNotFoundError, WalletError
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_TONAPI_KEY"
+COOKIES = {
+ "stel_ssid": "YOUR_STEL_SSID",
+ "stel_dt": "YOUR_STEL_DT",
+ "stel_token": "YOUR_STEL_TOKEN",
+ "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+USERNAME = "@username"
+AMOUNT = 10 # TON, integer โ 1โ1 000 000 000
+
+
+async def main() -> None:
+ client = FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES)
+
+ try:
+ result = await client.topup_ton(USERNAME, amount=AMOUNT, show_sender=True)
+ except UserNotFoundError:
+ print(f"User {USERNAME!r} not found on Fragment.")
+ return
+ except WalletError as e:
+ print(f"Wallet error: {e}")
+ return
+ except ConfigurationError as e:
+ print(f"Invalid parameters: {e}")
+ return
+
+ print("TON topped up")
+ print(" %-14s %s" % ("Username:", result.username))
+ print(" %-14s %s TON" % ("Amount:", result.amount))
+ print(" %-14s %s" % ("Transaction:", result.transaction_id))
+ print(" %-14s %s" % ("Timestamp:", result.timestamp))
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/fragmentapi/__init__.py b/fragmentapi/__init__.py
index 14d0e51..367e191 100644
--- a/fragmentapi/__init__.py
+++ b/fragmentapi/__init__.py
@@ -7,14 +7,14 @@ from fragmentapi.client import FragmentClient
from fragmentapi.types import (
AdsTopupResult,
ClientError,
- ConfigError,
- CookiesError,
+ ConfigurationError,
+ CookieError,
FragmentAPIError,
FragmentError,
- HashFetchError,
+ FragmentPageError,
OperationError,
+ ParseError,
PremiumResult,
- RequestError,
StarsResult,
TransactionError,
UnexpectedError,
@@ -29,13 +29,13 @@ __all__ = [
"PremiumResult",
"StarsResult",
"ClientError",
- "ConfigError",
- "CookiesError",
+ "ConfigurationError",
+ "CookieError",
"FragmentAPIError",
"FragmentError",
- "HashFetchError",
+ "FragmentPageError",
"OperationError",
- "RequestError",
+ "ParseError",
"TransactionError",
"UnexpectedError",
"UserNotFoundError",
diff --git a/fragmentapi/client.py b/fragmentapi/client.py
index cc93cee..d402bb4 100644
--- a/fragmentapi/client.py
+++ b/fragmentapi/client.py
@@ -7,8 +7,8 @@ from fragmentapi.types import (
REQUIRED_COOKIE_KEYS,
SUPPORTED_WALLET_VERSIONS,
AdsTopupResult,
- ConfigError,
- CookiesError,
+ ConfigurationError,
+ CookieError,
PremiumResult,
StarsResult,
WalletVersion,
@@ -26,8 +26,8 @@ class FragmentClient:
wallet_version: Wallet contract version โ ``"V4R2"`` or ``"V5R1"`` (default).
Raises:
- ConfigError: If ``seed``, ``api_key``, or ``wallet_version`` are missing or invalid.
- CookiesError: If ``cookies`` cannot be parsed or are missing required keys.
+ ConfigurationError: If ``seed``, ``api_key``, or ``wallet_version`` are missing or invalid.
+ CookieError: If ``cookies`` cannot be parsed or are missing required keys.
Example::
@@ -49,22 +49,24 @@ class FragmentClient:
) -> None:
missing = [name for name, val in (("seed", seed), ("api_key", api_key)) if not val or not str(val).strip()]
if missing:
- raise ConfigError(ConfigError.MISSING_VARS.format(keys=", ".join(missing)))
+ raise ConfigurationError(ConfigurationError.MISSING_VARS.format(keys=", ".join(missing)))
if isinstance(cookies, str):
try:
cookies = json.loads(cookies)
except Exception as exc:
- raise CookiesError(CookiesError.READ_FAILED.format(exc=exc)) from exc
+ raise CookieError(CookieError.READ_FAILED.format(exc=exc)) from exc
missing_keys = [k for k in REQUIRED_COOKIE_KEYS if not str(cookies.get(k, "")).strip()]
if missing_keys:
- raise CookiesError(CookiesError.MISSING_KEYS.format(keys=", ".join(missing_keys)))
+ raise CookieError(CookieError.MISSING_KEYS.format(keys=", ".join(missing_keys)))
version = wallet_version.strip().upper()
if version not in SUPPORTED_WALLET_VERSIONS:
- raise ConfigError(
- ConfigError.UNSUPPORTED_VERSION.format(version=version, supported=", ".join(sorted(SUPPORTED_WALLET_VERSIONS)))
+ raise ConfigurationError(
+ ConfigurationError.UNSUPPORTED_VERSION.format(
+ version=version, supported=", ".join(sorted(SUPPORTED_WALLET_VERSIONS))
+ )
)
self.seed: str = seed.strip()
diff --git a/fragmentapi/methods/premium.py b/fragmentapi/methods/premium.py
index 4f5cce6..958b6e7 100644
--- a/fragmentapi/methods/premium.py
+++ b/fragmentapi/methods/premium.py
@@ -8,7 +8,7 @@ from fragmentapi.types import (
BASE_HEADERS,
DEVICE,
PREMIUM_PAGE,
- ConfigError,
+ ConfigurationError,
FragmentAPIError,
FragmentError,
PremiumResult,
@@ -91,7 +91,7 @@ async def _init_request(
async def gift_premium(client: "FragmentClient", username: str, months: int, show_sender: bool = True) -> PremiumResult:
if months not in (3, 6, 12):
- raise ConfigError(ConfigError.INVALID_MONTHS)
+ raise ConfigurationError(ConfigurationError.INVALID_MONTHS)
try:
fragment_hash = await get_fragment_hash(client.cookies, HEADERS, PREMIUM_PAGE)
diff --git a/fragmentapi/methods/stars.py b/fragmentapi/methods/stars.py
index 9f15853..d5b4b50 100644
--- a/fragmentapi/methods/stars.py
+++ b/fragmentapi/methods/stars.py
@@ -7,7 +7,7 @@ from fragmentapi.types import (
BASE_HEADERS,
DEVICE,
STARS_PAGE,
- ConfigError,
+ ConfigurationError,
FragmentAPIError,
FragmentError,
StarsResult,
@@ -78,7 +78,7 @@ async def _init_request(
async def gift_stars(client: "FragmentClient", username: str, amount: int, show_sender: bool = True) -> StarsResult:
if not isinstance(amount, int) or not (50 <= amount <= 1_000_000):
- raise ConfigError(ConfigError.INVALID_STARS_AMOUNT)
+ raise ConfigurationError(ConfigurationError.INVALID_STARS_AMOUNT)
try:
fragment_hash = await get_fragment_hash(client.cookies, HEADERS, STARS_PAGE)
diff --git a/fragmentapi/methods/ton.py b/fragmentapi/methods/ton.py
index e4556cc..6cd7ebc 100644
--- a/fragmentapi/methods/ton.py
+++ b/fragmentapi/methods/ton.py
@@ -8,7 +8,7 @@ from fragmentapi.types import (
DEVICE,
TON_PAGE,
AdsTopupResult,
- ConfigError,
+ ConfigurationError,
FragmentAPIError,
FragmentError,
UnexpectedError,
@@ -78,7 +78,7 @@ async def _init_request(
async def topup_ton(client: "FragmentClient", username: str, amount: int, show_sender: bool = True) -> AdsTopupResult:
if not isinstance(amount, int) or not (1 <= amount <= 1_000_000_000):
- raise ConfigError(ConfigError.INVALID_TON_AMOUNT)
+ raise ConfigurationError(ConfigurationError.INVALID_TON_AMOUNT)
try:
fragment_hash = await get_fragment_hash(client.cookies, HEADERS, TON_PAGE)
diff --git a/fragmentapi/types/__init__.py b/fragmentapi/types/__init__.py
index 13b69d4..a717ccc 100644
--- a/fragmentapi/types/__init__.py
+++ b/fragmentapi/types/__init__.py
@@ -12,13 +12,13 @@ from fragmentapi.types.constants import (
)
from fragmentapi.types.exceptions import (
ClientError,
- ConfigError,
- CookiesError,
+ ConfigurationError,
+ CookieError,
FragmentAPIError,
FragmentError,
- HashFetchError,
+ FragmentPageError,
OperationError,
- RequestError,
+ ParseError,
TransactionError,
UnexpectedError,
UserNotFoundError,
@@ -41,14 +41,14 @@ __all__ = [
"WalletVersion",
# client exceptions
"ClientError",
- "ConfigError",
- "CookiesError",
+ "ConfigurationError",
+ "CookieError",
# fragment exceptions
"FragmentAPIError",
"FragmentError",
- "HashFetchError",
+ "FragmentPageError",
"OperationError",
- "RequestError",
+ "ParseError",
"TransactionError",
"UnexpectedError",
"UserNotFoundError",
diff --git a/fragmentapi/types/exceptions.py b/fragmentapi/types/exceptions.py
index b19215f..e1c800d 100644
--- a/fragmentapi/types/exceptions.py
+++ b/fragmentapi/types/exceptions.py
@@ -6,7 +6,7 @@ class ClientError(FragmentError):
"""Raised for client configuration and setup issues (bad params, invalid cookies)."""
-class ConfigError(ClientError):
+class ConfigurationError(ClientError):
"""Raised when required client parameters are missing or invalid."""
MISSING_VARS = "Missing required parameter(s): {keys}."
@@ -16,7 +16,7 @@ class ConfigError(ClientError):
INVALID_TON_AMOUNT = "Amount must be an integer between 1 and 1 000 000 000 TON."
-class CookiesError(ClientError):
+class CookieError(ClientError):
"""Raised when cookies are unreadable or missing required fields."""
READ_FAILED = "Failed to parse cookies: {exc}"
@@ -33,8 +33,8 @@ class FragmentAPIError(FragmentError):
)
-class HashFetchError(FragmentAPIError):
- """Raised when the Fragment API hash cannot be fetched from the page."""
+class FragmentPageError(FragmentAPIError):
+ """Raised when the Fragment page cannot be fetched or the API hash is not found."""
BAD_STATUS = "Fragment returned HTTP {status} for {url}. " "Check that your cookies are valid and not expired."
NOT_FOUND = (
@@ -59,8 +59,8 @@ class TransactionError(FragmentAPIError):
BROADCAST_FAILED = "Transaction broadcast failed: {exc}"
-class RequestError(FragmentAPIError):
- """Raised when a Fragment API response cannot be parsed."""
+class ParseError(FragmentAPIError):
+ """Raised when a Fragment API response or payload cannot be parsed."""
UNPARSEABLE = "Fragment API returned an unparseable response for '{context}': {exc}"
@@ -92,13 +92,13 @@ class UnexpectedError(OperationError):
__all__ = [
"FragmentError",
"ClientError",
- "ConfigError",
- "CookiesError",
+ "ConfigurationError",
+ "CookieError",
"FragmentAPIError",
- "HashFetchError",
+ "FragmentPageError",
"UserNotFoundError",
"TransactionError",
- "RequestError",
+ "ParseError",
"VerificationError",
"OperationError",
"WalletError",
diff --git a/fragmentapi/utils/decoder.py b/fragmentapi/utils/decoder.py
index 77e076a..b7130ee 100644
--- a/fragmentapi/utils/decoder.py
+++ b/fragmentapi/utils/decoder.py
@@ -2,7 +2,7 @@ import base64
from pytoniq_core import Cell
-from fragmentapi.types import RequestError
+from fragmentapi.types import ParseError
def clean_decode(payload: str) -> str:
@@ -19,7 +19,7 @@ def clean_decode(payload: str) -> str:
Decoded comment string, or ``""`` for an empty payload.
Raises:
- RequestError: If the payload cannot be decoded or parsed.
+ ParseError: If the payload cannot be decoded or parsed.
"""
s = payload.strip()
if not s:
@@ -32,4 +32,4 @@ def clean_decode(payload: str) -> str:
sl.load_uint(32) # op code โ always 0 for text comment
return sl.load_snake_string().strip()
except Exception as exc:
- raise RequestError(RequestError.UNPARSEABLE.format(context="payload decode", exc=exc)) from exc
+ raise ParseError(ParseError.UNPARSEABLE.format(context="payload decode", exc=exc)) from exc
diff --git a/fragmentapi/utils/http.py b/fragmentapi/utils/http.py
index 0874645..07087d4 100644
--- a/fragmentapi/utils/http.py
+++ b/fragmentapi/utils/http.py
@@ -3,7 +3,7 @@ from typing import Any
import httpx
-from fragmentapi.types import HashFetchError, RequestError, VerificationError
+from fragmentapi.types import FragmentPageError, ParseError, VerificationError
async def get_fragment_hash(
@@ -26,7 +26,7 @@ async def get_fragment_hash(
Lowercase hex hash string.
Raises:
- HashFetchError: If the page returns a non-200 status or the hash
+ FragmentPageError: If the page returns a non-200 status or the hash
is not found in the response HTML.
"""
page_headers = {
@@ -48,11 +48,11 @@ async def get_fragment_hash(
response = await session.get(page_url, headers=page_headers)
if response.status_code != 200:
- raise HashFetchError(HashFetchError.BAD_STATUS.format(status=response.status_code, url=page_url))
+ raise FragmentPageError(FragmentPageError.BAD_STATUS.format(status=response.status_code, url=page_url))
match = re.search(r"(?:https://fragment\.com)?/api\?hash=([a-f0-9]+)", response.text)
if not match:
- raise HashFetchError(HashFetchError.NOT_FOUND.format(url=page_url))
+ raise FragmentPageError(FragmentPageError.NOT_FOUND.format(url=page_url))
return match.group(1)
@@ -68,12 +68,12 @@ def parse_json_response(response: httpx.Response, context: str) -> dict[str, Any
Parsed response as a dict.
Raises:
- RequestError: If the response body cannot be decoded as JSON.
+ ParseError: If the response body cannot be decoded as JSON.
"""
try:
return response.json()
except Exception as exc:
- raise RequestError(RequestError.UNPARSEABLE.format(context=context, exc=exc)) from exc
+ raise ParseError(ParseError.UNPARSEABLE.format(context=context, exc=exc)) from exc
async def fragment_post(
@@ -124,7 +124,7 @@ async def execute_transaction_request(
Raises:
VerificationError: If Fragment requires KYC verification.
- RequestError: If the response cannot be parsed.
+ ParseError: If the response cannot be parsed.
"""
transaction = await fragment_post(session, fragment_hash, headers, tx_data)
diff --git a/tests/001_test_decode.py b/tests/001_test_decode.py
index d968e5d..7ccbe89 100644
--- a/tests/001_test_decode.py
+++ b/tests/001_test_decode.py
@@ -4,7 +4,7 @@ import re
import pytest
-from fragmentapi.types import RequestError
+from fragmentapi.types import ParseError
from fragmentapi.utils.decoder import clean_decode
PAYLOADS = [
@@ -35,6 +35,6 @@ def test_empty_payload_returns_empty_string() -> None:
assert clean_decode("") == ""
-def test_invalid_payload_raises_request_error() -> None:
- with pytest.raises(RequestError):
+def test_invalid_payload_raises_parse_error() -> None:
+ with pytest.raises(ParseError):
clean_decode("!!!not-valid-base64!!!")
diff --git a/tests/002_test_client.py b/tests/002_test_client.py
index 4aee0d0..ea6e42c 100644
--- a/tests/002_test_client.py
+++ b/tests/002_test_client.py
@@ -5,7 +5,7 @@ import json
import pytest
from fragmentapi import FragmentClient
-from fragmentapi.types import ConfigError, CookiesError
+from fragmentapi.types import ConfigurationError, CookieError
VALID_SEED = "abandon " * 23 + "about"
VALID_API_KEY = "test_api_key"
@@ -35,22 +35,22 @@ def test_wallet_version_is_case_insensitive() -> None:
def test_missing_seed_raises() -> None:
- with pytest.raises(ConfigError):
+ with pytest.raises(ConfigurationError):
FragmentClient(seed="", api_key=VALID_API_KEY, cookies=VALID_COOKIES)
def test_whitespace_only_seed_raises() -> None:
- with pytest.raises(ConfigError):
+ with pytest.raises(ConfigurationError):
FragmentClient(seed=" ", api_key=VALID_API_KEY, cookies=VALID_COOKIES)
def test_missing_api_key_raises() -> None:
- with pytest.raises(ConfigError):
+ with pytest.raises(ConfigurationError):
FragmentClient(seed=VALID_SEED, api_key="", cookies=VALID_COOKIES)
def test_unsupported_wallet_version_raises() -> None:
- with pytest.raises(ConfigError):
+ with pytest.raises(ConfigurationError):
FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES, wallet_version="V3R2")
@@ -60,22 +60,22 @@ def test_cookies_as_json_string() -> None:
def test_invalid_cookies_json_raises() -> None:
- with pytest.raises(CookiesError):
+ with pytest.raises(CookieError):
FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies="{not valid json}")
def test_missing_cookie_key_raises() -> None:
- with pytest.raises(CookiesError):
+ with pytest.raises(CookieError):
FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies={"stel_ssid": "x"})
def test_empty_cookie_value_raises() -> None:
bad = {**VALID_COOKIES, "stel_token": ""}
- with pytest.raises(CookiesError):
+ with pytest.raises(CookieError):
FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=bad)
def test_whitespace_cookie_value_raises() -> None:
bad = {**VALID_COOKIES, "stel_ton_token": " "}
- with pytest.raises(CookiesError):
+ with pytest.raises(CookieError):
FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=bad)
-