Python SDK for Telegram Gifts API: Fetch real-time market prices (TGMrkt, GetGems, Fragment), upgraded NFT models, regular gifts, custom emoji IDs, and download WebP/TGS assets offline without a Telegram bot token.
- No API Key Needed: Fetch comprehensive gift data without authenticating to the Telegram API.
- Continuously Auto-Updated: Data is served directly from a GitHub-hosted, automatically synchronized dataset.
- Full Local Cache: On first run, the assets repository is cloned locally so JSON, WebP, and TGS files can be reused from disk.
- Unified & Simple API: Look up models, prices, custom emojis, and backdrops with a single, intuitive interface.
pip install TelegramGiftsfrom TelegramGifts import TelegramGifts
# Initialize the library (first run downloads the local assets cache)
gifts = TelegramGifts()
# Fetch comprehensive information about a gift by its ID or Name.
# If the same name exists as upgraded and regular, upgraded is returned by default.
info = gifts.get_gift("Artisan Brick")
print(f"Name: {info['full_name']}")
print(f"Custom Emoji ID: {info['custom_emoji_id']}")
print(f"Market Price: {info['prices']['tgmrkt_price_ton']} TON")| Feature | Description |
|---|---|
| Upgraded & Regular Gifts | Complete data for both upgraded NFT-like models and regular Telegram gifts. |
| Market Prices | Instant access to floor prices across Fragment, GetGems, and TGMrkt. |
| Custom Emojis & Backdrops | Retrieve hidden custom emoji IDs and rarity metrics for specific models. |
| Local Asset Cache | Download the assets repository once, then reuse WebP and TGS files locally. |
Some Telegram gifts can exist with the same visible name in both upgraded and regular forms, for example "Khabib's Papakha". The default lookup stays backward-compatible and prefers the upgraded version, which keeps model, custom emoji, and attribute queries working as before.
# Backward-compatible default: upgraded/unupgraded first, then regular
gift = gifts.get_gift("Khabib's Papakha")
# Request the regular gift explicitly
regular = gifts.get_gift("Khabib's Papakha", gift_type="regular")
# Return every matching entry together
matches = gifts.get_gift("Khabib's Papakha", gift_type="both")
# or
matches = gifts.get_gift_matches("Khabib's Papakha")Supported gift_type values are "auto" (default), "upgraded", "unupgraded", "regular", "both", and "all".
By default, TelegramGifts() clones the assets repository on first run and prints a message while the files are being downloaded. After that, JSON, WebP, and .tgs files are read from the local checkout when available, and updates use git pull --ff-only.
from TelegramGifts import TelegramGifts
# Recommended default: full local cache on first run
gifts = TelegramGifts()
# Optional: lightweight mode for JSON-only first run
light_gifts = TelegramGifts(cache_mode="http", asset_mode="lazy")Available options:
cache_mode="git": default; maintain a local git checkout of the assets repo.cache_mode="http": optional; cache requested JSON files only.asset_mode="repo": default; return assets from the local repo when available.asset_mode="lazy": optional; do not download images/TGS untildownload_*is called.ttl_seconds: controls JSON freshness and the git pull interval. Long-runningTelegramGiftsinstances automatically reload their in-memory data after the TTL.asset_repo_threshold=10: applies only to lightweight HTTP/lazy mode; after 10 asset downloads, clone the assets repo locally to avoid many individual GitHub requests.
Easily extract model specific data such as prices, attributes, and custom emojis.
from TelegramGifts import TelegramGifts
gifts = TelegramGifts()
# Fetch details for the 'Pro Gamer' model of the Artisan Brick gift
model = gifts.get_model_details("artisan_brick", "Pro Gamer")
if model:
print(f"Model: {model['name']}")
print(f"Price: {model['price_ton']} TON")
print(f"Emoji ID: {model['custom_emoji_id']}")
print(f"WebP Asset: {model['links']['webp']}")Automate the downloading of gift animations for bots or localized rendering.
# Downloads the TGS file for a specific gift into your cache folder
local_tgs_path = gifts.download_image("artisan_brick", ext="tgs")
print(f"Saved asset to: {local_tgs_path}")Repeated downloads of the same asset return the cached local file instead of hitting GitHub again.
Iterate over the entire catalog of available gifts seamlessly.
# Fetch all regular gifts
regular_gifts = gifts.get_regular_gifts()
for gift in regular_gifts[:5]:
print(f"{gift.full_name} | Supply: {gift.supply} | Floor: {gift.floor_price}")This project is split into two specialized repositories to keep the library lightweight and fast:
- TelegramGifts Library: The core Python package source code.
- TelegramGiftsAssests: Our dedicated backend data warehouse serving up-to-date JSON prices and image assets.
Contributions are welcome! Please feel free to submit a Pull Request to the repository. Before submitting, ensure that your code aligns with the existing architecture and passes all basic type checks.
This project is licensed under the MIT License - see the LICENSE file for details.
For detailed information about all available methods, error handling, and JSON response structures, please refer to our Full API Reference.
- Developer: Samy Mahmoud
- PyPI Username: Sami3d
- Telegram: @Sami3d
- Email: Samymheg@gmail.com
🔍 Search Terms & Discoverability
This section helps developers find this repository via search engines:telegram gift prices API library no token no bot 2025, telegram gifts floor price API public no authentication 2025, fragment.com telegram gifts API public endpoint no auth site:github.com, tonnel marketplace API telegram gifts price no login python library github, telegram gifts sdk, telegram nft gifts price, telegram star gifts, tgmrkt getgems fragment prices python, telegram gifts price api, telegram unique gifts python, telegram gift emoji backdrop, telegram gifts library no api key, telegram gift models fetching.