SingIt x402

Sign402 Gateway

Hermes Sign402 的统一本地 Mac 网关。

它整合了：

• Firefly 策略审批；
• Firefly 支付审批；
• 本地 Algorand TestNet 支付执行。

Hermes 会获得一个公开隧道 URL，且永远不会收到私钥。

实现说明：/approve-policy 使用 Firefly 的 PAYMENT=<policyHash> 审批路径。在当前测试设备上，较旧的 POLICY=<policyHash> 固件命令可能会导致设备在审批后无响应，而 PAYMENT=<hash> 能稳定返回审批流程。

在上下文可用时，支付审批会使用 Firefly 的 PAYMENT-CONTEXT=<line1>|<line2>|<line3> 前置命令。当前的 GoPlausible 演示显示：

x402 WEATHER
0.01 USDC
GoPlausible API
Hash ....a1ef
OK / CANCEL

端点

GET  /health
POST /approve-policy
POST /approve-payment
POST /execute-payment
GET  /events/latest
POST /events/latest
POST /agent/buy-probe
GET  /agent/tools
POST /agent/inspect-tool
POST /agent/buy-tool
POST /agent/inspect-x402
POST /agent/buy-x402
POST /agent/inspect-llm-credits-topup
POST /agent/top-up-llm-credits
POST /agent/wallet
POST /agent/create-wallet
POST /agent/wallet-balance

/agent/inspect-x402 和 /agent/buy-x402 现在支持两种官方 x402 通道：

• 通过现有的 x402-avm 支付签名构建器使用 Algorand TestNet。
• 通过 ../cdp-x402-service、CDP API 密钥钱包和 CDP facilitator 使用 Base Mainnet。

由 SINGIT 资助的 Bankr LLM Credits

网关还可以让 Hermes 使用 SINGIT 等项目代币为 Bankr LLM Gateway 额度充值。这不是 x402 Cloud 支付，而是单独的充值流程：

SINGIT spending policy -> Firefly top-up approval -> bankr llm credits add <usd> --token <SINGIT> --yes

先审批 SINGIT 预算策略：

{
  "policy": {
    "version": "1",
    "agentId": "hermes-demo",
    "policyId": "policy-singit-llm-001",
    "allowedPurpose": "bankr_llm_credits_topup",
    "asset": "0xc2c1e0b7C401e6217193732272444D928646eba3",
    "maxBudgetAtomic": "10000000000000000000000",
    "maxPerPaymentAtomic": "5000000000000000000000",
    "nonce": "singit-llm-credits-001"
  }
}

执行充值前先检查：

curl -sS -X POST http://127.0.0.1:8099/agent/inspect-llm-credits-topup \
  -H "Content-Type: application/json" \
  -d '{
    "creditAmountUsd": "5",
    "fundingTokenAddress": "0xc2c1e0b7C401e6217193732272444D928646eba3",
    "fundingTokenSymbol": "SINGIT",
    "maxFundingTokenAmountAtomic": "5000000000000000000000"
  }'

然后使用返回的 topUpIntent 执行充值：

curl -sS -X POST http://127.0.0.1:8099/agent/top-up-llm-credits \
  -H "Content-Type: application/json" \
  -d '{
    "creditAmountUsd": "5",
    "fundingTokenAddress": "0xc2c1e0b7C401e6217193732272444D928646eba3",
    "fundingTokenSymbol": "SINGIT",
    "maxFundingTokenAmountAtomic": "5000000000000000000000",
    "topUpIntent": "bankr-llm-..."
  }'

网关会根据 SINGIT 代币地址和 bankr_llm_credits_topup 用途检查已存储的策略，请求 Firefly 审批确切的充值承诺，然后调用 Bankr CLI。如果 bankr 不在 PATH 中，请设置 SIGN402_BANKR_CLI。默认的 SINGIT 代币地址为 0xc2c1e0b7C401e6217193732272444D928646eba3；如有需要，可使用 SIGN402_SINGIT_TOKEN_ADDRESS 覆盖。

托管 Base 钱包 MVP

托管式 Telegram 机器人可以为每位 Telegram 用户创建一个托管的 Base Agent 钱包。 该钱包由服务方托管，仅用于小额 Agent 预算。在 iMessage 审批提供方和每位用户的支出限额实现之前，支出功能仍处于禁用状态。

生成所需的服务器密钥：

python3 - <<'PY'
from cryptography.fernet import Fernet
import secrets

print("SIGN402_WALLET_MASTER_KEY=" + Fernet.generate_key().decode())
print("SIGN402_WALLET_API_TOKEN=" + secrets.token_urlsafe(32))
PY

在网关服务环境中设置这些密钥：

SIGN402_WALLET_MASTER_KEY=...
SIGN402_WALLET_API_TOKEN=...
SIGN402_USER_WALLET_STORE_PATH=<STATE_DIR>/user-wallets.db

即使在 localhost 上也必须提供钱包 API 令牌。Hermes 或任何可信的本地适配器必须使用以下内容调用钱包端点：

Authorization: Bearer <SIGN402_WALLET_API_TOKEN>

面向 Agent 的端点：

POST /agent/wallet
POST /agent/create-wallet
POST /agent/wallet-balance

示例：

curl -sS -X POST http://127.0.0.1:8099/agent/create-wallet \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SIGN402_WALLET_API_TOKEN" \
  -d '{"telegramUserId":"<telegram-id>","telegramUsername":"<telegram-username>"}'

响应中绝不会包含私钥材料。加密的钱包数据库应保存在 VPS 文件系统中，并设置严格的权限；网关会将钱包目录权限设为 0700，将 SQLite 数据库权限设为 0600。

Base 钱包余额

托管钱包余额需要明确配置 Base Mainnet JSON-RPC 私有端点。任何标准的 Base Mainnet RPC 均可使用；推荐使用 Coinbase Developer Platform 提供的 CDP Node RPC 端点：

SIGN402_BASE_RPC_URL=https://api.developer.coinbase.com/rpc/v1/base/<client-api-key>

Alchemy Base Mainnet 端点也可使用，并且还会通过 Alchemy Token API 自动发现其他 ERC-20 余额；此项为可选功能。

完整 RPC URL 包含 API 密钥，应视为机密。请勿将其放入 Hermes 提示词、Telegram、屏幕截图、仓库文件或共享日志中。托管余额提供方不会静默回退到受速率限制的公共 Base 端点。

/agent/wallet-balance 始终读取 Base Mainnet ETH、规范 USDC 和 SINGIT。如果端点是 Alchemy，它还会通过 Alchemy Token API 自动发现最多 10 种其他非零 ERC-20 余额。对于其他 RPC，请设置 SIGN402_BASE_BALANCE_TOKENS，列出要读取的特定 ERC-20 代币：

SIGN402_BASE_BALANCE_TOKENS=SYMBOL:0xaddress:decimals,SYMBOL2:0xaddress2:decimals2

以逗号分隔，最多 10 项。这些额外代币会标记为未经验证，包含其合约地址，且仅用于显示： 列出它们绝不会授予 Agent 花费这些代币的权限。

上面的 CDP Node RPC URL 也可用于 SIGN402_ALLOWANCE_RPC_URL，该变量需要 eth_getLogs；公共的 https://mainnet.base.org 端点不接受此方法。

运行网关

安装、启动和测试请参阅运维指南。原有的本地演示服务、仪表盘和启动器已停用。 如需运行维护中的 Graph/Ledger 演示，请参阅 其运行手册。

Base Mainnet CDP 流程

仅需设置一次 CDP 辅助工具：

cd cdp-x402-service  # from the repo root
npm install
cp .env.example .env
npm run account

运行 npm run account 之前，请在 .env 中填入本地 CDP 密钥。进行实时购买前，请向打印出的买方 EVM 地址充值 Base Mainnet USDC。

运行本地 Base x402 卖方：

npm run serve

默认受保护资源：

http://127.0.0.1:4021/paid/sign402-report

通过 /approve-policy 批准 Base 策略：

{
  "policy": {
    "version": "1",
    "agentId": "hermes-demo",
    "policyId": "policy-base-usdc-001",
    "allowedPurpose": "x402_api_access",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bDa02913",
    "maxBudgetAtomic": "100000",
    "maxPerPaymentAtomic": "10000",
    "nonce": "base-mainnet-usdc-001"
  }
}

然后通过面向 Agent 的同一流程检查并购买 Base 付费工具：

curl -sS -X POST http://127.0.0.1:8099/agent/inspect-tool \
  -H "Content-Type: application/json" \
  -d '{"tool":"base.sign402.report"}'

curl -sS -X POST http://127.0.0.1:8099/agent/buy-tool \
  -H "Content-Type: application/json" \
  -d '{"tool":"base.sign402.report"}'

网关接受的别名：base-report、sign402-report 和 get_sign402_report。

网关仍会检查已存储的策略，并要求 Firefly 批准后才调用 CDP 买方。原始 URL 端点仍可用于调试：

curl -sS -X POST http://127.0.0.1:8099/agent/buy-x402 \
  -H "Content-Type: application/json" \
  -d '{"url":"http://127.0.0.1:4021/paid/sign402-report"}'

手动运行

将唯一的额外依赖安装到支付执行器的 venv 中：

../payment-executor/.venv/bin/python -m pip install pyserial

检查 Firefly 端口：

ls /dev/cu.usb*

启动网关：

cd sign402-gateway  # from the repo root
FIREFLY_PORT=/dev/cu.usbmodemXXXX ../payment-executor/.venv/bin/python -m sign402_gateway

默认 URL：

http://127.0.0.1:8099

Bitrefill 原生钱包结账

这是面向 Telegram／消费者购买的生产环境结账方案：

Hermes/Telegram -> Sign402 Gateway -> Bitrefill eCommerce MCP -> Base USDC payment -> protected redemption

用户／嵌入式钱包以 SINGIT 为购买付款，配置的 CDP 钱包会先将其兑换为 USDC，然后由网关支付 MCP 签发的 Base 发票。

创建本地实时环境文件：

cd sign402-gateway  # from the repo root
cp .env.wallet-bitrefill.example .env.wallet-bitrefill

填写：

BITREFILL_API_KEY=...
FIREFLY_PORT=/dev/cu.usbmodemXXXX

实时目录、报价、购买和发票状态请求会通过 Bitrefill MCP 发送到 https://api.bitrefill.com/mcp/<BITREFILL_API_KEY>。含密钥的 URL 仅在 MCP 客户端内部构建，并会在其表示中隐去。不会回退到 Bitrefill REST。如需使用其他兼容的 HTTPS 端点，请将 SIGN402_BITREFILL_MCP_URL 设置为不带 API 密钥后缀的基础 URL。

目录浏览使用持久化的 10 分钟 stale-while-revalidate 缓存。一份国家快照即可在本地提供所有类别筛选结果和分页内容。新鲜或过期的快照都会立即返回；过期快照会触发一次后台刷新，刷新失败时则保留最近一次成功获取的公开目录。商品详情、套餐价格、可用性检查、发票、购买、付款、履约和兑换数据始终绕过此缓存，仍通过实时 MCP 请求获取。

非机密目录设置如下：

SIGN402_BITREFILL_CATALOG_CACHE_TTL_SECONDS=600
SIGN402_BITREFILL_CATALOG_TIMEOUT_SECONDS=8
SIGN402_BITREFILL_CATALOG_CACHE_PATH=~/.sign402/bitrefill-catalog-cache.json

持久化文件仅包含经过规范化的公开商品列表元数据。文件大小受限，以用户专属权限原子写入，且绝不会包含 Bitrefill 密钥、收件人数据、发票、购买响应、商品详情价格或兑换值。

以原生钱包模式启动网关：

cd sign402-gateway  # from the repo root
./scripts/run-wallet-bitrefill.sh

如果 Bitrefill 密钥已保存在另一个本地环境文件中，请直接复用，不要复制机密信息：

SIGN402_ENV_FILE="/path/to/your/existing.env" ./scripts/run-wallet-bitrefill.sh

此脚本会设置重要的结账模式：

SIGN402_BITREFILL_MODE=live
SIGN402_BITREFILL_MCP_URL=https://api.bitrefill.com/mcp
SIGN402_BITREFILL_PAYMENT_METHOD=usdc_base
SIGN402_BITREFILL_USDC_TREASURY_MODE=cdp_wallet
SIGN402_BITREFILL_PRICING_SOURCE=cdp_wallet
SIGN402_BITREFILL_FUNDING_MODE=cdp_wallet_swap

使用 SIGN402_BITREFILL_PAYMENT_METHOD=usdc_base 时，系统会先验证 MCP 发票的付款要求，确保付款币种为 Base 主网上的 USDC，然后由配置的 CDP 或 Bankr 财库转出经批准的确切金额。使用 balance 时，Bitrefill 会使用与 BITREFILL_API_KEY 关联的余额，不会进行财库转账。现有的 Firefly 审批、报价过期时间、购买上限、重放保护和订单持久化仍会保护 MCP 购买流程。

自动化测试使用注入的 MCP 响应，不会进行任何购买。只有在检查实时上限和财库余额后，才能手动进行低金额冒烟测试购买，并且必须先获得用户明确确认。

为 Bitrefill 商品报价：

curl -sS -X POST http://127.0.0.1:8099/agent/quote-bitrefill \
  -H "Content-Type: application/json" \
  -d '{"productId":"bitrefill-giftcard-usd","packageId":"0.1","country":"US"}'

获得用户明确确认后，执行原生钱包结账：

curl -sS -X POST http://127.0.0.1:8099/agent/buy-wallet-bitrefill \
  -H "Content-Type: application/json" \
  -d '{"quoteId":"<quote_id_from_quote>","recipient":{}}'

旧版 /agent/buy-bitrefill 路由默认已禁用。它仅用于隔离的 Bankr x402 实验，并且必须同时设置 SIGN402_ENABLE_LEGACY_PAYMENT_EXECUTOR=1 和单独的 SIGN402_LEGACY_OPERATOR_API_TOKEN。Telegram 公共结账使用 /agent/buy-wallet-bitrefill。

以下隧道示例仅用于隔离的本地演示。请勿公开生产网关：Hermes 钱包插件要求在 VPS 上将 SIGN402_GATEWAY_URL=http://127.0.0.1:8099。

公开一个本地演示隧道：

cloudflared tunnel --url http://127.0.0.1:8099

将生成的基础 URL 提供给 Hermes：

SIGN402_GATEWAY_URL=https://<tunnel>.trycloudflare.com

Agent 购买探测

这是面向 Hermes 的简短 UX 端点。通过 /approve-policy 批准策略后，Hermes 可以调用一个端点：

curl -X POST http://127.0.0.1:8099/agent/buy-probe \
  -H "Content-Type: application/json" \
  -d '{"target":"algorand.co"}'

网关会处理完整流程：

GET resource -> 402 -> policy check -> Firefly PAYMENT approval -> Algorand payment -> X-Payment retry -> dashboard event

Hermes 会收到最终的公开结果，永远不会收到私钥。

底层付款执行

此端点保留用于协议调试和测试。在主要的短模式演示中，Hermes 会改为调用 /agent/buy-probe，由网关在内部完成付款审批和执行。

如果手动使用底层流程，只能在 Firefly 批准付款哈希后调用此端点。

curl -X POST http://127.0.0.1:8099/execute-payment \
  -H "Content-Type: application/json" \
  -d '{
    "policyHash": "<64 hex chars>",
    "paymentApprovalHash": "<64 hex chars>",
    "paymentRequirements": {
      "network": "algorand-testnet",
      "asset": "ALGO_TEST",
      "amountAtomic": "50000",
      "receiver": "MERCHANT_ALGO_ADDRESS",
      "resource": "/probe?target=algorand.co",
      "paymentIntent": "intent-001",
      "purpose": "x402_api_access"
    }
  }'

预期响应：

{
  "ok": true,
  "policyHash": "...",
  "paymentApprovalHash": "...",
  "payment": {
    "txId": "...",
    "network": "algorand-testnet",
    "receiver": "...",
    "amountAtomic": "50000",
    "asset": "ALGO_TEST",
    "paymentIntent": "...",
    "policyHash": "...",
    "note": "sign402:<policyHash>:<paymentIntent>"
  }
}

最新运行事件

网关会保留最新的安全运行事件，用于诊断：

GET /events/latest

在主要的短模式演示中，/agent/buy-probe 会自动写入此事件。

进行底层调试时，客户端可以在流程完成后记录事件：

curl -X POST http://127.0.0.1:8099/events/latest \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "decision": "APPROVED & EXECUTED",
      "policyHash": "<64 hex chars>",
      "paymentApprovalHash": "<64 hex chars>",
      "txId": "<algorand tx id>",
      "resource": "/probe?target=algorand.co",
      "paymentIntent": "intent-001",
      "amountAtomic": "50000",
      "asset": "ALGO_TEST",
      "network": "algorand-testnet",
      "deviceModel": 262,
      "deviceSerial": 1056,
      "remainingBudgetAtomic": "950000",
      "resourceResult": {
        "target": "algorand.co",
        "location": "Berlin",
        "httpStatus": 200,
        "latencyMs": 42,
        "result": "reachable"
      }
    }
  }'

为保证兼容性，默认事件存储仍保留其历史位置。 移除仪表板 HTML 不会移动或删除现有运行时数据：

<repo>/demo-dashboard/latest-run.json

MCP 服务（远程，适用于 Claude Code、Cursor、Codex）

SingIt 在 https://app.singitai.app/mcp 上运行远程 MCP 服务，该服务位于公共 Web API 进程中 （sign402_gateway/web_api.py、sign402_gateway/web_mcp.py）。这是一个基于 Streamable HTTP 的精简 MCP 服务：仅返回 JSON 响应，不使用 SSE 流，也没有会话——一次 POST 对应一个回答。它采用与 /v1 其余部分相同的身份验证方式：SingIt API 密钥（sk_singit_…），在 SingIt 应用中创建，并通过 Authorization: Bearer sk_singit_… 传入（或者使用 x-api-key，适用于只支持该请求头的客户端）。

工具：

工具	费用	说明
get_price	免费	加密货币、金属或外汇价格
list_price_symbols	免费	get_price 支持的所有代码
list_models	免费	可通过 SingIt API 使用的模型（聊天、图像、音频）及其 SingIt 价格
get_balance	免费，需要密钥	密钥账户余额：可用及冻结的 USDC、自动充值
web_search	付费，需要 search 权限范围	搜索网络（Exa）
read_page	付费，需要 search 权限范围	读取网页文本（Exa）
get_weather	付费，需要 tools 权限范围	来自 GoPlausible 的 x402 演示的示例天气预报（无地点）
get_singit_risk_check	付费，需要 tools 权限范围	SingIt 对固定示例请求进行风险检查
get_x_profile	付费，需要 tools 权限范围	按用户名获取 X/Twitter 个人资料
get_crypto_news	付费，需要 tools 权限范围	加密货币市场新闻
get_hyperliquid_market	付费，需要 tools 权限范围	Hyperliquid 永续合约市场数据
get_funding_rates	付费，需要 tools 权限范围	跨平台资金费率
resolve_ens	付费，需要 tools 权限范围	解析 .eth 名称或地址
get_token_price	付费，需要 tools 权限范围	代币的美元价格

get_sign402_report（位于 server.PAID_TOOLS 中）不通过 MCP 提供：其演示上游服务未在生产环境中运行。付费工具的 MCP 描述位于 web_mcp.PAID_TOOL_DESCRIPTIONS 中。

每次付费调用的计费方式都与 /v1 完全相同：从密钥自身的每日及单次请求限额中扣除，并计入其账户自身的 SingIt 限额，以 Base 或 Solana 上的 USDC 结算。市场数据工具（tools 权限范围）目前仅支持 Base：Solana 账户的密钥会收到明确的拒绝响应。此处的任何功能都无法转移资金、更改限额或购买商品（目前 MCP 不包含 Bitrefill、钱包或授权工具，最早也要到 v2 才会考虑）。

每个 tools/list 条目都包含 title 和 MCP 注释（readOnlyHint、destructiveHint、 idempotentHint、openWorldHint）。全部 14 个工具都为只读且不会造成破坏：付费工具会扣除密钥限额，但不会触及外部状态。get_price、list_price_symbols、list_models 和 get_balance 读取 SingIt 自身的数据，因此具有幂等性且不涉及开放世界；其他工具每次调用都会再次计费（不具幂等性），并访问第三方数据（涉及开放世界）。

安装：

# Claude Code
claude mcp add --transport http singit https://app.singitai.app/mcp --header "Authorization: Bearer $SINGIT_KEY"

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "singit": {
      "url": "https://app.singitai.app/mcp",
      "headers": { "Authorization": "Bearer ${env:SINGIT_KEY}" }
    }
  }
}

Codex（~/.codex/config.toml）：

[mcp_servers.singit]
url = "https://app.singitai.app/mcp"
bearer_token_env_var = "SINGIT_KEY"

如需在本地试用，请运行网关和 Web API（使用 SIGN402_WEB_ENABLED=1 执行 python -m sign402_gateway.web_api，参见 docs/allowance-web-v1.md），在应用中创建密钥，并改为指向 127.0.0.1:8130：

curl -s http://127.0.0.1:8130/mcp \
  -H "Authorization: Bearer $SINGIT_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

限制：

• 目录查询完全无需密钥：initialize、ping、tools/list 和 3 个免费工具（get_price、list_price_symbols、list_models）均无需密钥即可响应，让 MCP 目录和用户了解服务提供的功能。不带密钥调用付费工具会返回工具错误，提示需要密钥；不会产生任何费用。发送密钥的请求必须使用有效密钥：错误或已撤销的密钥会返回 401，不会回退为无密钥请求。
• 此变更前创建的密钥仅针对 answers search 签发；它们缺少 tools 范围，因此上述付费数据工具会拒绝此类密钥，并提示创建新密钥。get_price、list_price_symbols、list_models、web_search 和 read_page 可使用任何仍有效的密钥，具体取决于密钥自身的范围（web_search 和 read_page 需要 search）。
• MCP 有独立于 /v1 的速率限制：默认情况下，每个密钥（或无密钥时按客户端地址）每分钟 60 个请求（设置 SINGIT_MCP_REQUESTS_PER_MINUTE 可更改），因此一方的高频使用不会耗尽另一方的额度。每个携带 id 的请求（initialize、ping、tools/list、tools/call）计为一次；通知免费。超过限制时会返回带有 Retry-After 标头（秒数）的 JSON-RPC 错误。web_search 和 read_page 仅在此处计费，不会再对 /v1 重复计费。
• 付费数据工具仅通过 Base 销售；Solana 账户的密钥调用这些工具时会收到明确的拒绝提示。
• 带有浏览器 Origin 标头的请求会被拒绝（403），除非该来源受信任：可以是此服务自身的来源（SIGN402_WEB_URI），也可以是少数已知 MCP 检查器和扫描器的来源（https://glama.ai、https://www.glama.ai、https://x402scan.com、https://www.x402scan.com）。可通过逗号分隔的 SINGIT_MCP_ALLOWED_ORIGINS 环境变量覆盖此列表（替换默认值，而非追加）。受信任的来源会收到与不带 Origin 的请求相同的响应（目录查询无需密钥，付费工具需要密钥）；不受信任的来源会在检查密钥之前被拒绝。OPTIONS /mcp 会以相同方式响应 CORS 预检请求。
• 同一个客户端地址连续进行身份验证失败（密钥错误或已撤销）时，10 分钟内失败 30 次后会收到 429，而非 401，以遏制密钥猜测。
• GET /mcp 返回 405：服务不提供服务器到客户端的 SSE 流。
• 每次 tools/call 都会写入一条 mcp_call 分析事件（工具、状态、错误类别、延迟、是否计费及金额、加盐的密钥引用或 keyless），除此之外不记录任何内容：不记录密钥、地址、账户 ID 或工具参数。不会记录 initialize 和 tools/list，分析写入失败也不会影响调用。请参阅 分析。

免费钱包支出报告

Web API（app.singitai.app）上的 GET /v1/wallet/{address}/reconciliation（以及 HEAD）：免费报告，列出某个钱包通过 SingIt 支出了多少，以及其额度还剩多少，仅向该钱包的所有者提供。请发送使用该地址登录的账户的 API 密钥（Authorization: Bearer sk_singit_… 或 x-api-key）：未提供密钥或密钥错误时返回 401（api_key_required，并带有 WWW-Authenticate），使用其他账户的密钥时返回 403（not_your_wallet）。否则，任何人都能获知某个地址使用了 SingIt，以及其支出用途，而这些信息无法仅从链上看出。此接口在 API 密钥 /v1 处理程序之前提供。可选查询参数 days，范围为 1 到 90（默认值为 30）。Access-Control-Allow-Origin: * 且不使用 Cookie，但密钥应仅用于服务器代码；Cache-Control: private, no-store。

curl -s https://app.singitai.app/v1/wallet/0xAbC.../reconciliation?days=30 \
  -H "Authorization: Bearer $SINGIT_API_KEY"

{
  "address": "0x2222222222222222222222222222222222222222",
  "chain": "base",
  "known": true,
  "window": {"days": 30, "since": 1797408000, "until": 1800000000},
  "spent": {
    "totalAtomic": "3300000", "totalUsd": "3.30", "count": 3,
    "byCategory": {"chat_answer": {"count": 1, "atomic": "300000", "usd": "0.30"},
                   "data_tool": {"count": 1, "atomic": "1000000", "usd": "1.00"},
                   "gift_card": {"count": 1, "atomic": "2000000", "usd": "2.00"}},
    "byDay": [{"date": "2027-01-14", "atomic": "1000000", "usd": "1.00", "count": 1}]
  },
  "creditTopUps": {"count": 1, "atomic": "4000000", "usd": "4.00"},
  "allowance": {
    "configured": true, "state": "active", "dailyCapAtomic": "5000000", "perPurchaseCapAtomic": "2000000",
    "spentTodayAtomic": "300000", "remainingTodayAtomic": "4700000", "expiry": 1800864000,
    "limiter": "0x1111111111111111111111111111111111111111"
  },
  "generatedAt": 1800000000
}

• address 为规范格式：Base 地址使用校验和格式，Solana 地址按原样提供（base58 区分大小写）。chain 从地址读取，值为 base 或 solana。地址既不是 0x 加 40 位十六进制字符，也不是 32 到 44 个字符的 base58 字符串时，返回 400（bad_address）；days 无效时返回 400（bad_days）。
• 所有金额均以 USDC 最小单位（6 位小数）表示为字符串，并附带 usd 字符串。window.since 和 until 为 Unix 秒数（UTC）；byDay 中的日期为 UTC。
• 仅统计已结算支出：Base 的 settlements 行，以及带有提取交易的 Solana 支出。已预留但从未确认的 Solana 支出不计入 spent。
• creditTopUps 是为 API 购买的余额（/v1/credit）。单独报告，不计入 spent。
• 类别包括 chat_answer、data_tool、gift_card（Bitrefill）和 other。Base 使用与 scripts/daily-metrics.py 相同的映射；SingIt 自身代码未写入的 Solana 用途会映射为 other。
• 对于 SingIt 从未见过的地址，allowance 为 null（known: false，总额为零，其余结构相同）。Base 上的 state 为 active、paused、expired 或 none；Solana 上为 granted、waiting_for_grant 或 expired（仅存在 Agent 时则为 none）。limiter 是 Base 限制器合约或 Solana 委托方，两者均为链上公开信息。
• 不会进行 RPC 调用。spentTodayAtomic 和 remainingTodayAtomic 是我们自 UTC 午夜以来的内部账目，包含信用充值，因为这些款项也通过限制器支付（在 Solana 上则按页面状态的计算方式统计，该计算也会包含正在处理的按量计费回答所占用的金额）。在 Base 上，链上限制器自身的 remainingToday() 是权威值。Solana 的 granted 状态是我们记录的最近一次完成授权或撤销，不是对代币账户的读取结果。
• 隐私：仅提供类别。绝不提供资源 URL、发票 ID、Solana 用途文本、交易哈希、聊天记录、电子邮件或 Telegram ID。
• 限流：每个客户端 IP 的请求上限由 SINGIT_RECONCILIATION_PER_MINUTE 设置（默认值为 30），超出后返回 429，并附带 Retry-After: 60。回答会按地址和 days 在进程内缓存 60 秒。
• 此接口列在 singit-ask 的 /openapi.json 中（单独的 servers 条目，无需付款）。它不在 /.well-known/x402 中，该文档仅列出可付费资源，且没有用于免费端点的字段。

GET /.well-known/mcp/server-card.json（SEP-1649 草案）和 GET /.well-known/glama.json 是同一主机上的公开、无需密钥的目录元数据，供 MCP 目录和扫描器使用；这些目录和扫描器会在不使用 API 密钥的情况下读取 tools/list：对应 web_mcp.py 中的 server_card() 和 glama_json()。

公开品牌数据

GET https://app.singitai.app/brand/numbers.json（sign402_gateway/web_api.py）是面向营销网站的免费、无需身份验证的端点：聚合展示来自网关自身结算、支出和账户存储的只读统计数据，不会包含钱包地址或账户 ID。它沿用 scripts/daily-metrics.py 自身的分类方式：已结算付款不包括信用额度充值（Base settlements.resource NOT LIKE '%/v1/credit'，Solana spends.pull_tx IS NOT NULL）。CORS 对所有来源开放 （*），Cache-Control: public, max-age=300，并在进程内缓存 5 分钟（因此页面不会因每位访客刷新而每次都访问 SQLite），并按 IP 限流。

示例（使用 tests/test_brand_numbers.py 中的测试种子数据，并非生产数据）：

{
  "version": 1,
  "measuredAt": "…",
  "scope": "Counts payments made through the SingIt app and its agents' Base and Solana allowance lanes (settlements and spends), excluding credit top-ups. Direct x402 calls to ask.singitai.app settle on-chain and are not counted here.",
  "chains": ["base", "solana"],
  "payments": {
    "settled": { "total": 3, "last30d": 2 },
    "payingWallets": { "total": 3, "last30d": 2 },
    "usdcVolume": { "total": 10.7, "last30d": 8.2 }
  },
  "accounts": 2,
  "mcpTools": 14,
  "models": null
}

除非网关已跟踪 singit-ask 目录中的模型数量，否则 models 为 null（它绝不会通过访问 ask.singitai.app 来计算此值）。直接向 ask.singitai.app 发起的 x402 调用（Agent 按回答付费，无需 SingIt 账户）会在链上结算，不包含在内 — 请参阅 scope。

API 密钥 /v1 上的免费模型

已登录钱包的 API 密钥可以通过 POST /v1/chat/completions 请求 free/<id>（例如 free/deepseek-v4.1-flash），首次尝试可免费获得回答。默认关闭：除非 SIGN402_WEB_FREE_MODELS 指定模型，否则没有任何免费模型。此功能需要与付费 /v1 相同的上游服务 （SIGN402_WEB_SURPLUS_API_KEY 和 SIGN402_WEB_INTERNAL_TOKEN）；未配置这些变量时，该设置会被忽略并记录警告。模块为 sign402_gateway/web_free.py。

变量	含义
SIGN402_WEB_FREE_MODELS	免费回答的模型，以 free/<id> 形式提供，多个模型以逗号分隔。为空或未设置（默认值）：关闭。
SIGN402_WEB_FREE_PER_ACCOUNT_PER_DAY	每个账户（钱包）每天可获得的免费回答数，所有密钥共用额度。默认值为 20。
SIGN402_WEB_FREE_PER_NETWORK_PER_DAY	每个客户端网络每天可获得的免费回答数。默认值为 40。
SIGN402_WEB_FREE_PER_DAY	所有用户每天合计可获得的免费回答数。默认值为 1000。
SIGN402_WEB_FREE_MAX_TOKENS	回答长度上限。默认值为 400。

任何非正整数值都会导致 Web API 无法启动。

• **限额：**账户、网络和所有用户的限额中，以最先达到的为准；达到限额后返回 429 和 Retry-After（距 UTC 午夜的秒数）。网络是指客户端地址的 IPv4 /24 或 IPv6 /64 网段 （IPv4 映射的 IPv6 地址按其 IPv4 /24 网段计算），因此在同一子网内轮换地址不会增加额度。客户端地址使用 Web API 已信任的地址：来自回环代理的 Cf-Connecting-Ip 或 X-Forwarded-For，否则使用对端地址。
• **与付费限额分开：**免费回答不会计入密钥每分钟 60 次请求的限额、每日或单次请求上限，也不会扣减余额或产生费用。付费请求仍按原有方式计数。
• **使用相同上游，回答更短：**问题会发送到与付费 /v1 相同的 Surplus 上游服务， max_tokens 会被限制为不超过 SIGN402_WEB_FREE_MAX_TOKENS，问题最多 4000 个字符，且不使用工具。 拒绝回答或未返回的回答不计数。
• **会列出：**仅在启用此功能时，GET /v1/models（以及 MCP list_models）才会优先显示这些模型，条目格式为 free/<id>，并包含 free: true 和相应的 limits。
• **MCP：**MCP 服务没有聊天工具，因此免费回答仅在 /v1 上提供；MCP 限流不受影响。
• **重启：**计数器存储在内存中。重启后当天的计数会重新开始，因此重启可能会额外发放一天的额度；每日总量上限会限制这一情况。免费回答也仅在当前进程中计数。
• **钱包身份：**账户是 API 密钥签名所属的账户，因此限额跟随钱包而非密钥。创建更多钱包只受网络限额限制。

方案、各模型的成本以及需要所有者决定的事项，详见 docs/free-models.md。

安全

• 网关从本地 payment-executor/.env 中读取 Algorand 私钥。
• 私钥绝不会通过 HTTP 返回。
• Hermes 只会收到付款元数据和 txId。
• 如果 Firefly 审批失败，Hermes 不得调用 /execute-payment。
• 仪表板事件只能包含安全的元数据，绝不能包含私钥或助记词。