API_QUICK_REFERENCE.md

TTTS API 快速参考

🚀 基础信息

• Base URL: http://localhost:5000
• 认证方式: Session (Solana 钱包签名)
• 数据格式: JSON

🔐 认证接口

方法	端点	描述
POST	/get_nonce	获取签名随机数
POST	/verify_signature	验证钱包签名并登录
GET	/check_auth	检查认证状态
POST	/logout	用户登出

💰 积分系统

方法	端点	描述	认证
GET	/api/points/balance	获取积分余额	✅
GET	/api/points/history	获取积分历史	✅
GET	/api/points/leaderboard	获取积分排行榜	❌

🎲 盲盒抽奖

方法	端点	描述	认证
GET	/api/lootbox/list	获取盲盒列表	❌
POST	/api/lootbox/draw	执行抽奖	✅
GET	/api/lootbox/history	获取抽奖历史	✅
GET	/api/lootbox/rewards/{id}	获取奖励概率	❌

🎒 用户背包

方法	端点	描述	认证
GET	/api/inventory	获取用户背包	✅
GET	/api/inventory/stats	获取背包统计	✅
GET	/api/inventory/{id}	获取物品详情	✅

🎁 虚拟物品兑换

方法	端点	描述	认证
POST	/api/virtual-item/redeem	申请兑换	✅

💎 SOL 池子

方法	端点	描述	认证
GET	/api/solana/blockhash	获取区块哈希	❌
POST	/api/sol-pool/participate	参与 SOL 池子	✅
GET	/api/sol-pool/status	获取池子状态	✅
GET	/api/sol-pool/daily-stats	获取每日统计	❌

🤖 AI 功能

方法	端点	描述	认证
POST	/generate_image	文生图 (同步)	✅
POST	/generate_async	文生图 (异步)	✅
POST	/generate_video	文生视频	✅
POST	/generate_chat_audio	AI 语音对话	✅
GET	/task/{id}	检查任务状态	❌
POST	/api/product/experience/complete	完成产品体验	✅

👨‍💼 管理员接口

认证管理

方法	端点	描述
POST	/admin/login	管理员登录
POST	/admin/logout	管理员登出

虚拟物品兑换管理

方法	端点	描述
GET	/admin/virtual-items/pending-redemptions	获取待处理兑换
PUT	/admin/virtual-items/complete-redemption/{id}	完成兑换
PUT	/admin/virtual-items/cancel-redemption/{id}	取消兑换
GET	/admin/virtual-items/redemption-stats	获取兑换统计

虚拟物品管理

方法	端点	描述
GET	/admin/physical-items	获取虚拟物品列表
GET	/admin/physical-items/{id}	获取物品详情
POST	/admin/physical-items	创建虚拟物品
PUT	/admin/physical-items/{id}	更新虚拟物品
DELETE	/admin/physical-items/{id}	删除虚拟物品

用户管理

方法	端点	描述
GET	/admin/users	获取用户列表
POST	/admin/users/{id}/points	调整用户积分

盲盒管理

方法	端点	描述
GET	/admin/lootboxes	获取盲盒列表
PUT	/admin/lootboxes/{id}	更新盲盒
PUT	/admin/lootboxes/{box_id}/rewards/{reward_id}	更新奖励

统计数据

方法	端点	描述
GET	/admin/stats	获取总体统计
GET	/admin/addresses	获取转账地址
GET	/admin/charts/activity	获取活跃度图表
GET	/admin/charts/points	获取积分图表
GET	/admin/charts/lootbox	获取盲盒图表

📝 请求示例

钱包连接

// 1. 获取 nonce
const nonce = await fetch('/get_nonce', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ wallet_address: address })
});

// 2. 验证签名
const auth = await fetch('/verify_signature', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ wallet_address: address, signature, nonce })
});

盲盒抽奖

const result = await fetch('/api/lootbox/draw', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ loot_box_id: 1 })
});

虚拟物品兑换

const redeem = await fetch('/api/virtual-item/redeem', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ inventory_id: 4 })
});

🎯 当前系统配置

盲盒奖励 (100积分/次)

• 30积分: 50% (500,000次)
• 80积分: 30% (300,000次)
• 160积分: 15% (150,000次)
• 320积分: 3.9% (39,000次)
• 1000积分: 1% (10,000次)
• 0.05 SOL: 0.1% (1,000次) ← 唯一虚拟物品

SOL 池子配置

• 参与费用: 0.02 SOL
• 奖励积分: 50积分
• 目标地址: 3WL45x5sxzdHjhRksJEvRc3tNkFQxJwyfPctpTYk6Shi

AI 功能积分奖励

• 文生图: 10积分 (每日3次)
• 文生视频: 20积分 (每日2次)

虚拟物品兑换状态

• not_redeemed: 未兑换 (可申请)
• pending: 待处理 (等待管理员)
• redeemed: 已兑换 (已完成)

⚠️ 重要说明

1. 认证要求: 标记 ✅ 的接口需要用户登录
2. 管理员权限: /admin/* 接口需要管理员登录
3. 错误处理: 所有响应都包含 success 字段
4. 虚拟物品: 系统已从实物奖品迁移为虚拟物品
5. 兑换流程: 虚拟物品兑换无需填写地址信息

🔗 相关文档

• 完整 API 文档