usdtman/README.md

USDTMan

TRON USDT TRC20 收款监听服务

特性

• 扫描交易记录 + 区块确认数验证（默认 >= 6）
• 支持 big.Int 处理任意金额
• WebSocket 实时推送
• 主动查询历史交易（时间/金额/确认数过滤）
• 代理支持

使用

uman := usdtman.NewUSDTMan(usdtman.Config{
    Addresses:        []string{"TN8nJ...", "TXYZo..."},
    APIKey:           "YOUR_API_KEY",
    QueryInterval:    5 * time.Second,  // 查询间隔
    MinConfirmations: 6,                 // 最小确认数
    MaxHistoryTxns:   20,                // 监听查询数量
    ProxyURL:         "http://127.0.0.1:7890", // 可选
})

uman.OnPaymentComplete(func(payment *usdtman.USDTPayment) {
    fmt.Printf("收到 %s USDT (确认: %d)\n", 
        payment.GetAmountString(), payment.Confirmations)
})

uman.Start()
defer uman.Stop()

// 主动查询历史
payments, _ := uman.QueryTransactions(usdtman.QueryFilter{
    Address:          "TN8nJ...",
    StartTime:        startTimestamp,  // 毫秒
    EndTime:          endTimestamp,    // 毫秒
    MinAmount:        big.NewInt(10000000), // >= 10 USDT
    MinConfirmations: 6,
    Limit:            50,
})

运行 HTTP Server

cd cmd/server
PROXY_URL=http://127.0.0.1:7890 go run main.go

访问 http://localhost:8084

HTTP API

• POST /start - 启动监听
• POST /stop - 停止监听
• POST /add-address - 添加地址
• POST /remove-address - 移除地址
• GET /list-addresses - 地址列表
• GET /payments - 监听缓存记录（最多100条）
• POST /query - 主动查询历史
• WS /ws - WebSocket 推送

主动查询示例

curl -X POST http://localhost:8084/query \
  -H "Content-Type: application/json" \
  -d '{
    "address": "TN8nJ...",
    "startTime": 1770000000000,
    "endTime": 1770100000000,
    "minAmount": "10000000",
    "minConfirmations": 6,
    "limit": 50
  }'

配置项

参数	类型	默认	说明
Addresses	[]string	[]	监听地址
APIKey	string	-	TronGrid API Key
QueryInterval	time.Duration	5s	查询间隔
MinConfirmations	int64	6	最小确认数
MaxHistoryTxns	int	20	监听查询数量
ProxyURL	string	-	HTTP/SOCKS5 代理
Transport	http.RoundTripper	nil	自定义 Transport

监听 vs 查询

• 监听 (/payments): 自动轮询最近交易，达到确认数后触发回调，缓存最多 100 条
• 查询 (/query): 主动查询链上历史，支持条件过滤，不触发回调