TelRump API

텔레그램 가입자 추출과 계정 구매를 내 프로그램·서버에서 자동으로 처리하는 API 입니다.

通过 API 在您自己的程序或服务器中自动完成 Telegram 注册用户筛选 与 账号购买。

개요概述

인증 · API 키认证 · API 密钥

1. telrump.com 로그인 → 상단 API 메뉴 → 새 키 만들기. 키는 그때 한 번만 보여요.
2. 登录 telrump.com → 顶部 API 菜单 → 新建密钥。密钥只显示一次，请妥善保存。
3. 모든 요청에 X-API-Key 헤더를 넣으세요. (Authorization: Bearer tlr_... 도 가능)
4. 所有请求都需携带 X-API-Key 请求头（也可使用 Authorization: Bearer tlr_...）。

오류 형식错误格式

실패하면 HTTP 상태 코드와 함께 아래 형식으로 응답합니다.

请求失败时返回 HTTP 状态码及以下格式：

{ "error": { "code": "insufficient_balance", "message": "잔액 부족 (필요: 0.7182 USDT, 보유: 0.1000 USDT)" } }

잔액 조회余额查询

GET/api/v1/me

curl https://telrump.com/api/v1/me -H "X-API-Key: tlr_..."

{ "username": "myid", "balance": 120.5, "currency": "USDT" }

가입자 추출 — 가격·조건注册用户筛选 — 价格与条件

번호 목록 중 텔레그램에 가입된 번호와 마지막 접속 시간을 찾아줍니다.

从号码列表中找出已注册 Telegram 的号码及其最后上线时间。

GET/api/v1/extract/price

{
  "service": "telegram_active",
  "price_per_number": 0.0006,
  "currency": "USDT",
  "min_numbers": 500,
  "max_numbers": 1000000,
  "countries": ["KR"],
  "download_days": [1, 3, 5, 7]
}

요금 = price_per_number × 제출한 번호 수 (중복 제거 후). 가격은 바뀔 수 있으니 주문 전에 확인하세요.

费用 = price_per_number × 提交号码数（去重后）。价格可能调整，请在下单前确认。

추출 주문创建筛选任务

POST/api/v1/extract

JSON 또는 multipart/form-data(파일 업로드)로 보낼 수 있어요.

支持 JSON 或 multipart/form-data（上传文件）。

curl -X POST https://telrump.com/api/v1/extract \
  -H "X-API-Key: tlr_..." -H "Content-Type: application/json" \
  -d '{"numbers":["821012345678","821087654321"],"title":"11월 DB","webhook_url":"https://example.com/hook"}'

# 파일로 보내기上传文件
curl -X POST https://telrump.com/api/v1/extract \
  -H "X-API-Key: tlr_..." -F "file=@numbers.txt" -F "title=11월 DB"

응답 201 — 잔액에서 바로 차감되고 작업이 대기열에 들어갑니다.

返回 201 — 立即从余额扣款，任务进入队列。

{
  "job": {
    "id": 45, "title": "11월 DB", "status": "queued", "progress": 0, "country": "KR",
    "input_count": 20000, "registered_count": 0, "premium_count": 0,
    "cost": 12.0, "currency": "USDT", "refunded": false, "error": null,
    "created_at": "2026-11-02T05:20:58Z", "completed_at": null, "download_ready": false
  },
  "balance": 108.5
}

작업 조회查询任务

GET/api/v1/extract/{id}

GET/api/v1/extract?limit=50최근 작업 목록 (최대 200)最近任务列表（最多 200）

대략 2만 개 기준 몇 분 걸려요. 상태 조회는 10~30초 간격이면 충분하고, 웹훅을 쓰면 조회하지 않아도 됩니다.

约 2 万个号码需要几分钟。建议每 10~30 秒查询一次；使用 Webhook 则无需轮询。

결과 다운로드下载结果

GET/api/v1/extract/{id}/download?days=1&premium=all&format=txt

xlsx 열: 전화번호 · 유저ID · 아이디(@) · 성 · 이름 · 프리미엄 · 동결 여부 · 마지막 접속 · 접속 경과일 (한글). 완료 전에 요청하면 409 not_ready.

xlsx 列：电话号码 · 用户ID · 用户名 · 姓 · 名 · 会员 · 是否冻结 · 最后上线 · 距今天数（韩文表头）。任务未完成时返回 409 not_ready。

curl -o kr_1d.txt "https://telrump.com/api/v1/extract/45/download?days=1" -H "X-API-Key: tlr_..."
curl -o all.xlsx "https://telrump.com/api/v1/extract/45/download?format=xlsx" -H "X-API-Key: tlr_..."

완료 알림 (웹훅)完成通知 (Webhook)

주문할 때 webhook_url 을 넣으면, 작업이 끝나거나 실패했을 때 그 주소로 POST 를 보냅니다.

下单时填写 webhook_url，任务完成或失败时会向该地址发送 POST。

POST https://example.com/hook
Content-Type: application/json
X-Telrump-Event: extract.completed

{
  "event": "extract.completed",          // 또는或 "extract.failed"
  "sent_at": "2026-11-02T05:25:01Z",
  "job": { "id": 45, "status": "completed", "registered_count": 18388, "premium_count": 83, ... }
}

• 2xx 로 응답하면 성공. 실패하면 10초, 60초 뒤 두 번 더 보냅니다 (총 3번).
• 返回 2xx 即为成功。失败时会在 10 秒、60 秒后重试两次（共 3 次）。
• 공개 인터넷 주소(http/https)만 가능해요. 내부망·localhost 주소는 거부됩니다. 리다이렉트는 따라가지 않아요.
• 仅支持公网地址（http/https），内网和 localhost 地址会被拒绝，不跟随重定向。
• 알림 내용을 그대로 믿지 말고 GET /api/v1/extract/{id} 로 다시 확인한 뒤 처리하세요.
• 请勿直接信任通知内容，处理前请用 GET /api/v1/extract/{id} 再次确认。

계정 구매 — 재고·가격账号购买 — 库存与价格

GET/api/v1/shop/stock

{
  "items": [
    { "category": "kr",   "name": "한국 번호", "count": 34, "price": 6, "currency": "USDT" },
    { "category": "intl", "name": "해외 번호", "count": 0,  "price": 4, "currency": "USDT" }
  ]
}

구매购买

POST/api/v1/shop/buy

curl -X POST https://telrump.com/api/v1/shop/buy \
  -H "X-API-Key: tlr_..." -H "Content-Type: application/json" \
  -d '{"category":"kr","quantity":2}'

201
{
  "accounts": [
    { "account_id": 1650, "phone": "821012345678", "category": "kr" },
    { "account_id": 1651, "phone": "821087654321", "category": "kr" }
  ],
  "cost": 12, "currency": "USDT", "balance": 96.5, "failed": 0
}

category: kr 또는 intl · quantity: 1~100. 재고가 요청 수량보다 적으면 409 out_of_stock (아무것도 구매되지 않음).

category：kr 或 intl · quantity：1~100。库存不足时返回 409 out_of_stock（不会购买任何账号）。

구매한 계정已购账号

GET/api/v1/shop/accounts?limit=100

{
  "accounts": [
    { "account_id": 1650, "phone": "821012345678", "category": "kr", "purchased_at": "2026-11-02T06:01:00Z", "status": "ready" },
    { "account_id": null, "phone": "821055556666", "category": "kr", "purchased_at": "2026-10-30T02:11:00Z", "status": "delivered" }
  ]
}

인증코드 받기获取验证码

GET/api/v1/shop/accounts/{account_id}/code?wait=30

{
  "account_id": 1650, "phone": "821012345678",
  "code": "52819", "received_at": "2026-11-02T06:02:11Z", "age_sec": 2,
  "fresh": true,            // since 이후 새로 온 코드since 之后新收到的验证码
  "codes_last_10min": 1     // 여러 개면 마지막 코드만 유효多个时仅最后一个有效
}

로그인 자동화 예제自动登录示例

1. POST /shop/buy 로 구매 → account_id, phone 받기
2. 调用 POST /shop/buy 购买 → 获得 account_id、phone
3. GET /shop/accounts 에서 status 가 ready 가 될 때까지 대기
4. 轮询 GET /shop/accounts，直到 status 变为 ready
5. 내 텔레그램 클라이언트로 그 번호의 로그인 코드를 요청
6. 用您的 Telegram 客户端为该号码请求登录验证码
7. GET /shop/accounts/{account_id}/code?wait=30 으로 코드 받아서 로그인
8. 调用 GET /shop/accounts/{account_id}/code?wait=30 获取验证码并登录

# Python (requests + Telethon)
import asyncio, requests
from telethon import TelegramClient

API = "https://telrump.com/api/v1"
H = {"X-API-Key": "tlr_..."}

async def main():
    acc = requests.post(f"{API}/shop/buy", json={"category": "kr", "quantity": 1}, headers=H).json()["accounts"][0]

    for _ in range(30):   # ready 대기 / 等待 ready
        lst = requests.get(f"{API}/shop/accounts", headers=H).json()["accounts"]
        if any(a["account_id"] == acc["account_id"] and a["status"] == "ready" for a in lst): break
        await asyncio.sleep(3)

    client = TelegramClient(f"acc_{acc['phone']}", API_ID, API_HASH)   # 내 api_id / api_hash
    await client.connect()
    await client.send_code_request("+" + acc["phone"])

    c = requests.get(f"{API}/shop/accounts/{acc['account_id']}/code", params={"wait": 30}, headers=H).json()
    if not c.get("fresh"):
        raise RuntimeError("새 코드를 받지 못했어요 / 未收到新验证码")
    await client.sign_in("+" + acc["phone"], c["code"])
    print("logged in:", await client.get_me())

asyncio.run(main())

가입자 추출 전체 예제

筛选完整示例

# Python (requests)
import time, requests
API = "https://telrump.com/api/v1"
H = {"X-API-Key": "tlr_..."}

numbers = [line.strip() for line in open("numbers.txt") if line.strip()]
job = requests.post(f"{API}/extract", json={"numbers": numbers, "title": "batch-1"}, headers=H).json()["job"]

while job["status"] in ("queued", "running"):
    time.sleep(15)
    job = requests.get(f"{API}/extract/{job['id']}", headers=H).json()["job"]

if job["status"] == "completed":
    for d in (1, 3, 7):
        r = requests.get(f"{API}/extract/{job['id']}/download", params={"days": d}, headers=H)
        open(f"active_{d}d.txt", "wb").write(r.content)
    r = requests.get(f"{API}/extract/{job['id']}/download", params={"format": "xlsx"}, headers=H)
    open("all.xlsx", "wb").write(r.content)
else:
    print("failed (refunded):", job["error"])

© TelRump · telrump.com