Fragment API 为商店、Telegram 机器人和后端服务提供了一种简单方式，可为任何受支持的 Telegram 用户名购买 Telegram Stars 或 Telegram Premium。可以使用 Python SDK，也可以直接调用 REST API。

API 访问免费。你只需支付 Fragment 购买金额和 TON 网络费用。

快速开始

pip install fragment-api-dev==1.2.1

import os
from fragment_api import FragmentAPI

api = FragmentAPI()

purchase = api.buy_stars(
    username="@telegram_user",
    amount=50,
    payment_method="gram",
    seed=os.environ["TON_WALLET_SEED"],
)

result = api.wait(purchase.purchase_id)
print(result.status, result.transaction_hash or result.error)

这个最小示例使用 24 个单词的 TON 助记词或 Base64 编码的 32 字节私钥。凭据仅由你的后端发送；切勿将助记词放在前端代码中。

选择你的钱包配置

仅有 12 词助记词是不够的。如果你知道地址但不知道其索引，请使用钱包解析示例。

开箱即用的示例

examples/ 目录包含带讲解的示例，涵盖：

• 使用 GRAM 购买 Stars
• 使用 TON 上的 USDT 购买 Stars
• 使用 GRAM 购买 Premium
• 使用 TON 上的 USDT 购买 Premium
• 无选择器的 24 词钱包
• 带地址或账户索引的 12 词钱包
• Python SDK、Node.js 和 curl

USDT 购买需要少量 GRAM 余额用于支付 TON 网络费用。

AI 辅助集成

为 Codex 或 Claude 安装同一个便携技能：

# Codex
cp -R skills/fragment-api-integration "${CODEX_HOME:-$HOME/.codex}/skills/"

# Claude
cp -R skills/fragment-api-integration "$HOME/.claude/skills/"

然后向你的编码代理提问：

使用 $fragment-api-integration 为本项目添加 Telegram Stars 购买功能。

该技能涵盖 Python SDK 与 REST 集成、Stars 与 Premium、GRAM 与 USDT、钱包选择、幂等性、轮询以及安全的错误处理。

价格

在不创建购买的情况下获取参考报价：

quote = api.get_stars_price(100)
print(quote.prices.gram, quote.prices.usdt)

curl 'https://api-stars.duckdns.org/api/v1/prices/quote?product=stars&amount=100'

价格值为精确的十进制字符串。Fragment 会在购买开始时创建新的报价。

重要提示

• 每个逻辑订单使用一个 idempotency_key。
• 使用相同的密钥重试同一订单。
• 等待最终状态；创建购买并不意味着购买已完成。
• 切勿自动替换处于 reconciliation_required 状态的订单。

资源

支持

提交 issue 或联系 @tondotdev。

切勿在 issue 中发布钱包凭据。安全问题请通过 SECURITY.md 报告。