TelegramGifts 1.0.0

A powerful, offline-first Python library for fetching Telegram Gifts metadata, models, prices, and custom emojis.

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.
• Smart Local Caching: Powered by ETag-based caching to ensure lightning-fast responses and zero rate limits.
• 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 (auto-creates a smart cache)
gifts = TelegramGifts()

# Fetch comprehensive information about a gift by its ID or Name
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

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.
Asset Downloading	Download high-quality WebP and TGS sticker animations locally with ease.

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

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.

Author & Contact

• Developer: Samy Mahmoud
• PyPI Username: Sami3d
• Telegram: @Sami3d
• Email: [e-mail]

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