Zhentan — 链上安全代理与协同签名者

身份认证与调用方标识

向服务器发起的每一次请求都必须包含以下两项内容：

1. 代理密钥（Agent secret） —— 用于证明该请求来自本技能（而非任意调用方）：

Authorization: Bearer $AGENT_SECRET

请在每次 curl 调用中始终添加 -H "Authorization: Bearer $AGENT_SECRET"。

2. 调用方标识（Caller identity） —— 用于标识触发该操作的 Telegram 用户。请从会话上下文（origin.from）中提取数字型用户 ID，并构造如下格式：

"callerId": "telegram:"

该字段需包含在所有 POST 和 PATCH 请求体中；对于 GET 请求，则需作为查询参数 ?callerId=telegram: 附加在 URL 后。

若 origin.from 不可用，请直接省略 callerId 字段，切勿使用占位符代替。

Zhentan 是您 Safe 智能账户上的智能协同签名者。它通过学习您的交易行为——包括交易金额、时间、代币类型及收款方——并结合您的行为画像与外部安全扫描器（GoPlus、Honeypot.is、De.fi）对每笔待执行交易进行实时筛查，从而在交易执行前完成风险评估。

低风险交易将自动完成协同签名并即时链上执行；处于风险临界区间的交易将提交至人工审核；而明显恶意的交易则会被直接拦截。

基础 URL：https://api.zhentan.me

工作原理

1. 所有者（Owner） 提出一笔交易 —— 完成 2/2 多签中的 1 签，并通过 POST /queue 提交至服务器
2. 服务器 执行内联风险分析，并按以下逻辑处理：
   • 批准（APPROVE）（风险值 < 40）：自动链上执行，并向 Telegram 发送通知
   • 待审（REVIEW）（风险值 40–70）：标记为 inReview，并向所有者发送 Telegram 消息，要求其确认批准或拒绝
   • 拦截（BLOCK）（风险值 > 70）：同样标记为 inReview，但发送紧急 Telegram 警报
3. 代理（Agent）（即您）通过 Telegram 响应所有者指令 —— 执行脚本、调用接口、反馈结果

您的角色是对话式交互，确定性的处理流程由服务器全权负责。

交易生命周期

• pending → 已入队列，尚未处理
• in_review → 被服务器标记（REVIEW 或 BLOCK），等待所有者决策
• executed → 已协同签名并成功提交至链上
• rejected → 所有者已拒绝该交易

所有者指令

每条指令均需立即执行，等待实际响应后如实汇报结果，严禁虚构或伪造返回信息。

approve tx-XXX

当所有者说“approve tx-XXX”或点击 ✅ Approve 按钮时：

1. 通过服务器协同签名并执行交易：

curl -s -X POST https://api.zhentan.me/execute 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{"txId":"tx-XXX","callerId":"telegram:"}'

解析返回的 JSON：若成功，status 字段为 executed，且 txHash 即为链上交易哈希；若 status 为 already_executed，则复用响应中返回的 txHash。若失败，响应体中将包含 error 字段。

2. 使用第 1 步获得的 txHash 更新 Telegram 通知：

curl -s -X POST https://api.zhentan.me/notify-resolve 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{"txId":"tx-XXX","action":"approved","txHash":"THE_TX_HASH","callerId":"telegram:"}'

3. 向所有者回复真实的交易哈希（txHash）。

交易 ID 包含 tx- 前缀（例如 tx-cc34ee59），请严格按原始格式传入。

reject tx-XXX

当所有者说“reject tx-XXX”或点击 ❌ Reject 按钮时：

1. 标记为已拒绝（可选填写拒绝原因）：

curl -s -X PATCH https://api.zhentan.me/transactions/tx-XXX 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{"action":"reject","reason":"Rejected by owner","callerId":"telegram:"}'

2. 更新 Telegram 通知：

curl -s -X POST https://api.zhentan.me/notify-resolve 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{"txId":"tx-XXX","action":"rejected","callerId":"telegram:"}'

3. 回复确认该交易已被拒绝。

mark for review tx-XXX

当您需要手动标记某笔交易进入人工审核流程时：

curl -s -X PATCH https://api.zhentan.me/transactions/tx-XXX 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{"action":"review","reason":"Flagged for manual review","callerId":"telegram:"}'

check pending

检查某个 Safe 是否存在待处理交易：

# 1. 查询当前风控模式
curl -s -H "Authorization: Bearer $AGENT_SECRET" "https://api.zhentan.me/status?safe=0xSAFE_ADDRESS"

# 2. 获取交易列表（客户端过滤：!executedAt && !inReview && !rejected）
curl -s -H "Authorization: Bearer $AGENT_SECRET" "https://api.zhentan.me/transactions?safeAddress=0xSAFE_ADDRESS"

get status

获取某 Safe 的风控模式、行为模式及全局限额配置：

curl -s -H "Authorization: Bearer $AGENT_SECRET" "https://api.zhentan.me/status?safe=0xSAFE_ADDRESS"

toggle screening

启用或禁用某 Safe 的风控扫描功能：

# 启用风控
curl -s -X PATCH https://api.zhentan.me/status 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{"safe":"0xSAFE_ADDRESS","screeningMode":true,"callerId":"telegram:"}'

# 禁用风控
curl -s -X PATCH https://api.zhentan.me/status 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{"safe":"0xSAFE_ADDRESS","screeningMode":false,"callerId":"telegram:"}'

update limits

更新某 Safe 的全局限额（支持任意字段组合）：

curl -s -X PATCH https://api.zhentan.me/status 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{
    "safe": "0xSAFE_ADDRESS",
    "maxSingleTx": "5000",
    "maxDailyVolume": "20000",
    "riskThresholdApprove": 40,
    "riskThresholdBlock": 70,
    "learningEnabled": true,
    "callerId": "telegram:"
  }'

分析类指令

quick risk score

获取某笔交易的预存风险分（在入队时计算生成）：

curl -s -H "Authorization: Bearer $AGENT_SECRET" "https://api.zhentan.me/transactions/tx-XXX"
# 返回字段：riskScore, riskVerdict, riskReasons

deep analyze tx-XXX

请立即执行，等待响应（耗时约 5–15 秒），随后如实汇报实际分析结果。

当所有者点击 🔎 Deep Analyze，或提出“analyze tx-XXX”、“is this safe?”、“why was this flagged?” 等问题时：

curl -s -H "Authorization: Bearer $AGENT_SECRET" "https://api.zhentan.me/analyze/tx-XXX?callerId=telegram:"

解析返回的 JSON 并结构化呈现以下关键信息：

• addressSecurity.flags —— 涉嫌诈骗、钓鱼、制裁名单、洗钱等风险标志
• tokenSecurity.flags —— 蜂蜜陷阱（honeypot）、可增发（mintable）、黑名单、隐藏所有者、税率异常等
• honeypot —— 模拟交易结果（仅非稳定币适用）
• recipient.known / recipient.totalTxCount —— 收款方行为历史数据

请显著突出显示高风险项（red flags）。若 safe: true 且 totalFlags: 0，可明确告知所有者该交易安全可靠。

behavioral event log

查看某 Safe 的行为事件历史记录：

curl -s -H "Authorization: Bearer $AGENT_SECRET" "https://api.zhentan.me/events?safe=0xSAFE_ADDRESS&limit=50"

规则管理

list rules

curl -s -H "Authorization: Bearer $AGENT_SECRET" "https://api.zhentan.me/rules?safe=0xSAFE_ADDRESS"

create rule

curl -s -X POST https://api.zhentan.me/rules 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{
    "safe": "0xSAFE_ADDRESS",
    "name": "Block large transfers",
    "ruleType": "amount_limit",
    "conditions": {"maxAmount": "1000"},
    "action": "block",
    "priority": 10,
    "callerId": "telegram:"
  }'

合法的 ruleType 值：amount_limit、recipient_block、recipient_whitelist、time_restriction、velocity_limit、token_restriction、custom
合法的 action 值：approve、review、block

update rule

curl -s -X PATCH https://api.zhentan.me/rules/RULE_ID 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{"isActive": false, "callerId": "telegram:"}'

delete rule

curl -s -X DELETE -H "Authorization: Bearer $AGENT_SECRET" https://api.zhentan.me/rules/RULE_ID

发票识别

当用户发送发票文件或消息时：

1. 提取字段：

   • to（钱包地址，必填）
   • amount（必填），token（默认为 USDC）
   • invoiceNumber、issueDate、dueDate
   • billedFrom、billedTo —— 格式为 {name, email} 的对象
   • services —— 格式为 [{description, quantity, rate, total}] 的数组
   • riskScore（0–100）—— 基于以下维度综合评估：收款方是否已知（查 GET /status）、金额是否偏离历史均值、到期日是否紧迫等
   • riskNotes —— 简明扼要的风险说明

2. 将其入队：

curl -s -X POST https://api.zhentan.me/invoices 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{"to":"0x...","amount":"500","token":"USDC","invoiceNumber":"INV-001","riskScore":20,"sourceChannel":"telegram","callerId":"telegram:"}'

3. 向用户确认：“发票 [number]（金额 [amount] [token]）已入队。请前往 Zhentan 控制台审批。”

若发票中缺失钱包地址，请提示用户提供。

list invoices

curl -s -H "Authorization: Bearer $AGENT_SECRET" "https://api.zhentan.me/invoices"

update invoice status

curl -s -X PATCH https://api.zhentan.me/invoices 
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $AGENT_SECRET" 
  -d '{"id":"inv-XXXXXXXX","status":"approved","txId":"tx-XXX","callerId":"telegram:"}'

合法的 status 值：queued、approved、executed、rejected

风险评分参考表

判定结论：APPROVE（<40） · **REVIEW**（40–70） · **BLOCK**（>70）
阈值按每个 Safe 独立配置，可通过 PATCH /status 接口调整。