---
name: telegram-gift-data
description: Public read-only JSON API for Telegram gift collections (models, backdrops, symbols, stickers, release dates, auctions) served by gear.tg.
---
# Telegram Gift Data API (gear.tg)

Base URL: https://gear.tg/api  (also https://api.gear.tg at root once DNS is live)
All responses are JSON (CORS *), except asset endpoints. Data comes from Telegram MTProto and is cached (stale-while-revalidate).

## :gift parameter
Official name ("Plush Pepe"), lowercase, spaceless ("plushpepe"), dashed/underscored ("plush-pepe", "plush_pepe") or numeric gift id ("5936013938331222567").
Attribute names (:model, :backdrop, :symbol) are matched the same way (case/space/punctuation-insensitive).

## Endpoints
- [COMMON] GET /ids — Map of gift collection id -> name
- [COMMON] GET /names — List of collection names
- [COMMON] GET /total — Counts (collections, all star gifts, total supply)
- [COMMON] GET /llm — SKILL.md describing this API (text/markdown)
- [COMMON] GET /health — Health + MTProto status
- [EMOJI] GET /emoji — Map of collection name -> emoji of its base sticker
- [EMOJI] GET /emoji/:gift — Emoji of one collection
- [GIFTS] GET /gifts — All collections with price/supply/release info
- [GIFTS] GET /gift/:gift — One collection: price, supply, upgrade price, attribute counts
- [GIFTS] GET /dates — Release (first sale) dates
- [MODELS] GET /models/:gift — Models (?sorted = rarest first)
- [MODELS] GET /model/:gift/:model[.tgs|.json|.png|.svg] — Model animation; .png/.svg ?size=64|128|256|512|1024
- [MODELS] GET /model/:gift/:model/info — Model rarity info
- [BACKDROPS] GET /backdrops — All backdrops (union, with colors)
- [BACKDROPS] GET /backdrops/:gift — Backdrops of a collection (?sorted)
- [BACKDROPS] GET /backdrop/:gift/:backdrop/info — Backdrop colors + rarity
- [SYMBOLS] GET /symbols/:gift — Symbols (alias /patterns/:gift, ?sorted)
- [SYMBOLS] GET /symbol/:gift/:symbol[.tgs|.json|.png] — Symbol animation (alias /pattern/...)
- [SYMBOLS] GET /symbol/:gift/:symbol/info — Symbol rarity info
- [ORIGINALS] GET /original/:id[.tgs|.json|.png] — Base (unupgraded) gift sticker; :id = gift id or collection name
- [CRAFTS] GET /crafts — Crafted models per collection
- [AUCTIONS] GET /auctions — Active + past gift auctions
- [AUCTIONS] GET /auction/:gift/rounds — Rounds/state of a gift auction

## Assets
Extensions: .tgs (gzipped Lottie, default), .json (Lottie JSON), .png (?size=64|128|256|512|1024, default 512, first frame), .svg (first frame as an SVG document wrapping a PNG render; Lottie has no vector export).

## Rarity
rarityPermille = per-mille chance (e.g. 5 = 0.5%). Some attributes carry a tier instead (rarity: uncommon|rare|epic|legendary; rarityPermille null).
?sorted orders rarest first.

## Examples
curl https://gear.tg/api/models/plush-pepe?sorted
curl -o pepe.png "https://gear.tg/api/model/plushpepe/Barcelona.png?size=256"
curl https://gear.tg/api/backdrop/plushpepe/Black/info