TelegramGifts

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.

Why this library?

• 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.

Installation

pip install TelegramGifts

Quick Start

from 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")

Features

Shared Gift Names

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".

Cache Modes

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 until download_* is called.
• ttl_seconds: controls JSON freshness and the git pull interval. Long-running TelegramGifts instances 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.

Usage Examples

1. Retrieve Upgraded Models and Prices

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']}")

2. Download Gift Assets Locally

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.

3. Retrieve All Gifts and Floor Prices

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}")

Open Source Ecosystem

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.

Contributing

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.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation 📚

For detailed information about all available methods, error handling, and JSON response structures, please refer to our Full API Reference.

Author & Contact

• Developer: Samy Mahmoud
• PyPI Username: Sami3d
• Telegram: @Sami3d
• Email: Samymheg@gmail.com