Recipient lookup and cache

GET /v1/recipients/lookup?username=durov&product=PREMIUM&months=3

{ "username": "durov", "found": true, "name": "Pavel Durov", "photoUrl": "https://…", "eligible": true }

• username is accepted as durov, @Durov or https://t.me/durov: we lowercase it and strip the @ and the link.
• product is STARS (default) or PREMIUM; Premium requires months (3, 6 or 12), which is how we check whether it can be gifted (active Premium cannot be gifted, so you get eligible: false). For Stars, eligible equals found.
• found: false is a normal 200 response, not an error. An invalid username returns 400 (-9202), Premium without months returns 400 (-9203).
• If the supplier is currently unavailable (no working account, or all accounts hit their limit), the response is 502 (-9006): retry in a few seconds.
• Show the buyer the name and avatar before payment: this prevents most "wrong username" mistakes.

CacheCopy Anchor Link

Results are cached: found recipients for 15 minutes, not found ones for 2 minutes. Identical concurrent requests are merged into a single supplier request. So a repeated lookup is cheap, and POST /v1/orders right after a lookup does not call the supplier again.

If a user has just created or changed their username, wait a couple of minutes: a negative result may still be cached.

LimitCopy Anchor Link

120 lookups per minute per Project (instead of the general key limit: lookups do not count towards the key's 600 requests). Do not check the username on every keystroke, debounce it by 300 to 500 ms.

curl -X GET "https://example.com/v1/recipients/lookup?username=string"

{  "success": true,  "data": {    "username": "durov",    "found": true,    "name": "Pavel Durov",    "photoUrl": "https://cdn4.telesco.pe/file/durov.jpg",    "eligible": true  },  "meta": {    "requestId": "9f1c2b7e-3a4d-4e5f-8a6b-7c8d9e0f1a2b",    "timestamp": "2026-10-06T09:15:22.481Z",    "processingTimeMs": 38  }}