arbiter

Arbiter

自主 Agent 的判断层。

即将对现实世界采取行动的 AI Agent，往往需要一种无法独自作出的判断：这笔交易签署起来安全吗？这个交易对手是真实的吗？这张照片真的是它声称的内容吗？ Arbiter 按次提供这些判断，通过 x402 使用 Algorand 上的 USDC 付款。

三个路由，一种响应约定：

路由	判断	价格
POST /v1/judge/transaction	机器 — 在签署前解码未签名交易并评估风险	$0.002
POST /v1/judge/counterparty	数据 — 这笔付款的交易对手是否就是其声称的对象	$0.01
POST /v1/judge/human	人类 — 模型无法独自判断的问题，由经过审核的评审员作答	$0.25

每个路由都会返回相同的判定封装，因此 Agent 只需集成一种数据结构，就能询问任意类型的判断，无需新增分支逻辑：

{
  "decision": "block",        // allow | warn | block | escalate
  "risk": 100,                // 0-100
  "confidence": 1,            // 0-1; low confidence forces "escalate"
  "findings": [ /* itemised, each with severity, detail and source */ ],
  "evidence": { /* the decoded transaction, the counterparty record */ },
  "meta": { "degraded": false, "latencyMs": 378 }
}

刚接触 Arbiter，或要向非技术人员介绍它？ Arbiter 实际上做什么 — 无代码，无术语。

线上服务

https://arbiter-hs23.onrender.com — API，以及位于 /work 的评审员应用。

预检：18 项通过，0 项阻塞性失败。运行在 Render 免费套餐上，没有持久磁盘，并会在闲置 15 分钟后休眠 — 关于相关影响以及 10 月排行榜窗口前所需的升级，请参阅 DEPLOY.md。

状态

组件	状态
x402 支付核心（Algorand、USDC、GoPlausible 促进器）	正常运行，已通过端到端验证
Bazaar 发现 + x402-global-challenge 标签	正常运行，已在 402 响应中验证
/v1/judge/transaction Algorand 防火墙	正常运行，5/5 个攻击案例通过
/v1/judge/transaction EVM 防火墙	正常运行，7/7 种资金抽干模式通过，支持 EIP-7702
/v1/judge/counterparty 引擎	正常运行，针对实时主网 + NFD 的 5/5 个案例通过
/v1/judge/human 市场	正常运行，包含共识、评审员可靠性和付款账本
链上付款结算	正常运行 — 已在链上向评审员支付真实 USDC
SDK、MCP 服务、LangChain、ElizaOS、付款代理	已构建、通过类型检查并完成运行时验证
CrewAI 工具（Python）	已构建；通过付款代理运行 — 见下文
KeeperHub 集成	正常运行，已执行真实的 Sepolia 交易
评审员应用（React）	已上线于 /work，已通过付费问题完成端到端验证

交易防火墙

自主 Agent 只会因少数几种特定方式损失资金。防火墙会解码实际交易字节，并报告签署后真正会发生什么：

• Rekey — rekeyTo 会永久转移账户的签名权限
• Close-remainder — 无论声明的金额是多少，都会转出全部 ALGO 余额
• Asset close-out — 无论声明的金额是多少，都会转出全部 ASA 持仓
• Clawback — 从第三方账户转出资产
• Fee drain — 余额通过过高的手续费转出，而非通过显眼的转账
• App delete / update — 销毁或悄然替换合约逻辑
• 资产级风险：由创建者持有的 clawback 和冻结权限、不存在的资产
• 账户级风险：签名者已重新指定、收款人未注资、有效期窗口已过

使用真实且刚编码的交易运行：

npm run demo:attacks

[BLOCK]  Rekey attack              risk=100/100  confidence=1  1365ms
[BLOCK]  Close-remainder drain     risk=100/100  confidence=1   378ms
[BLOCK]  Asset close-out drain     risk=100/100  confidence=1  1432ms
[BLOCK]  Fee drain                 risk=100/100  confidence=1   379ms
[ALLOW]  Benign payment            risk=0/100    confidence=1   398ms

良性案例返回零条发现，与拦截风险同样重要 — 一个误报的防火墙最终会被关闭。

交易对手验证

可以发现仅靠阅读发票无法识别的两种隐蔽且代价高昂的失败：

• 付款地址被替换 — 发票是真的，收款方也真实存在，但该地址属于其他人。通过 NFD 注册表进行核实，并与身份合法控制的所有地址进行比对。
• 未开通资产接收 — 在 Algorand 上，向未开通接收该资产的账户转账 ASA 会被直接拒绝。款项根本不会到账。

此外还会检查已重新设定密钥的收款方、被冻结的持仓、低于最低余额的账户、未注册或已过期的身份，以及从未收到过资金的地址。

npm run demo:counterparty     # live NFD registry + Algorand mainnet, read-only

最值得了解的两个案例相邻而又相反：一个身份验证通过，但其地址无法接收该资产；另一个身份在一个本可接收资产的地址上验证失败。两者都会阻止付款，但原因截然不同。

人工判断

模型无法独自定论的问题会交由经过审核的审核员处理。付费调用会在限定时间内进行长轮询；如果审核员及时作答，结果会直接返回，否则调用方会收到待处理结果和一个免费的查询 URL。超时不会导致再次付费。

npm run demo:human

• 通过可配置的法定人数进行多数投票，并公开一致率
• 置信度是经过审核员能力证明程度折扣后的一致率，因此不会把未经验证的审核员给出的一致答案视为确定结论
• 审核员因参与而获得报酬，而不是因达成一致而获得报酬——按一致意见付费会激励审核员猜测多数意见，而不是报告他们看到的情况
• 将不合常理的快速作答标记为质量信号
• 根据长期与共识一致的情况，逐步累积每位审核员的可靠性

工作者 API（/v1/work/*）不收费：审核员属于供给方。

向审核员付款

npm run settle -- --dry-run    # check everything, send nothing
npm run settle                 # pay

这件事有两条规则，遵守每条规则都要付出代价：

广播交易前先认领。 在发送任何交易之前，付款会转为 settling 状态并获得一个 attempt id，该 id 会写入交易的 note 字段。因此，如果进程在执行途中崩溃，结果会是款项未付，而不是重复付款——人工核对卡住的记录与账本后，可以补付未付款项；重复付款则无法挽回。

付款前核验收款方。 每个付款地址都会先经过 Arbiter 自有的 /v1/judge/counterparty 引擎检查。这并非装饰：向未开通接收 USDC 的账户转账会被协议拒绝，因此盲目付款只会浪费手续费，审核员也会在没有任何解释的情况下收不到款项。被拦截的付款会保持待处理状态，并在审核员开通接收后重试。

[PAID]  0.150000 USDC -> GBRO5EM4JM57PDPS…
        txid  SIEXIGX6KQKA4D4PTOUL7R6M5BDP4BIUEW2TTOIFZHBU233LSKWQ
        note  arbiter:payout:pay_msft8csu_rfq0ch

[SKIP]  0.150000 USDC -> OEQWDYGTEXMDWSH2…
        Arbiter blocked this payee: Counterparty has not opted in to the asset

付款账户与 PAY_TO 分开配置，这是有意为之。PAY_TO 用于累积收入，其密钥无需保存在服务器上；付款账户只持有运营资金，因此即使主机遭到入侵，攻击者也无法提走收入。

设计规则：调用方已经付过费

引擎开始运行时，Agent 已经被收费。因此，上游故障不得导致抛出异常。每次 algod 查询都有严格的超时限制，并会返回结果，说明是否确实获取到了数据；查询失败会降低 confidence 并设置 meta.degraded，而仍会运行可捕获关键严重级别问题的静态解码规则。降级的判定结果依然有用。

此外，confidence < 0.4 时会返回 escalate，而不是 allow，因此证据不足的判定结果绝不会被误认为一切正常。

将其接入 Agent

按使用量排名的排行榜上的流量来自其他人的 Agent 调用你，因此客户端是产品的主要入口，而非事后才考虑的内容。完整详情请见 clients/README.md。

Package	用途
@arbiterlabs/sdk	TypeScript Agent；自动支付 x402
@arbiterlabs/mcp	任意 MCP 主机——Claude Code、Claude Desktop、OpenClaw
@arbiterlabs/langchain	LangChain.js 工具
@arbiterlabs/eliza	ElizaOS 插件
@arbiterlabs/proxy	为非 TypeScript Agent 提供本地支付 Sidecar
arbiter-crewai	CrewAI（Python），通过 Sidecar

支出限额由客户端负责，而不是依靠给集成方的建议，因为 Agent 在付费端点上陷入重试循环会造成钱包被耗尽的漏洞：

const client = new ArbiterClient({
  baseUrl: process.env.ARBITER_URL,
  privateKey: process.env.ALGO_KEY,
  maxPricePerCallUsd: 0.5,
  maxTotalSpendUsd: 10,
});

两个上限都会在支付选择器中强制执行，并且早于任何签名操作。

为什么 Python 需要 Sidecar

在 Algorand 上支付 x402 需要 AVM 方案客户端，而目前只有 TypeScript 提供这种客户端。x402 2.18 没有提供 AVM 客户端，而 x402-avm 2.0.2——尽管名称如此——也没有提供，既不依赖 algosdk，还会安装到 x402 命名空间中，覆盖基础软件包。因此，Python Agent 根本无法构建 Algorand x402 支付。

因此，@arbiterlabs/proxy 负责持有密钥并支付，再通过 loopback 以非付费方式重新暴露这些判断结果。这通常也是更好的安排：由一个进程持有已注资的密钥并执行一项预算，而不是让每个 Agent 进程都携带两者的副本。

设置

npm install
cp .env.example .env    # then set PAY_TO
npm run dev

PAY_TO 必须是一个真实的 Algorand 地址，并且已针对你运行的网络选择加入 USDC ASA（测试网 10458941，主网 31566704），否则结算会失败。

验证支付门控：

curl -i -X POST http://localhost:4021/v1/judge/transaction \
  -H 'content-type: application/json' \
  -d '{"chain":"algorand","transaction":"abc"}'

预期会收到 HTTP 402，并带有一个 base64 编码的 PAYMENT-REQUIRED 标头，其中包含价格、资产、payTo、feePayer 和 Bazaar 发现架构。

关于 Facilitator 网络标识符的说明

GoPlausible facilitator 使用完整填充的 base64 genesis hash 作为 CAIP-2 引用来公布 Algorand：

algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=

而 @x402/avm 的 ALGORAND_TESTNET_CAIP2 使用的是符合 CAIP-2 规范、截断为 32 个字符的形式：

algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDe

在 AVM 方案中，两者都会规范化为同一网络，但资源服务器会通过精确匹配来验证路由配置与 facilitator 公布的字符串，因此使用 SDK 常量会导致启动失败并报 missing_facilitator。src/facilitator.ts 会在启动时从 /supported 获取标识符，并通过规范化进行匹配，因此两种形式都适用；如果上游修复了填充问题，它也会继续正常工作。它还会读取公布的 feePayer，让调用方可以使用 USDC 支付，而无需持有 ALGO 来支付 gas。

竞赛配置

本项目为 Algorand Global x402 Challenge 打造，属于组合参赛作品：三个路由共用一个 payTo，因此它们的交易量会汇总到同一个商家条目中，同时每个路由仍可在 Bazaar 中单独发现。

已接入并在实时 402 响应中验证的要求：

• 未付款时，付费端点返回 HTTP 402
• 使用 GoPlausible facilitator（不使用其他 facilitator）
• Bazaar 发现扩展包含各路由的输入 / 输出架构
• 每个路由都带有 x402-global-challenge 标签
• 所有路由使用一致的 payTo
• 已部署至 MainNet 上的公共 HTTPS
• 已完成一笔真实的 MainNet 付款，确认收到 USDC
• 已列入 Algorand MainNet USDC 排行榜

首笔完成结算的 MainNet 付款为 IUTXAWFK…： 0.002 USDC（ASA 31566704），发生于第 63,807,235 轮；此交易通过索引器核实，而非依据结算响应。

归属依据为 payTo 地址。排行榜不提供标签筛选，因此 x402-global-challenge 标签有助于在 Bazaar 中发现项目，但不会影响计分——现在 npm run preflight -- <url> 会直接确认榜单条目，而不是根据标签推断。

如果 MainNet 部署仍指向 localhost 或普通 HTTP，assertChallengeReady() 会阻止启动。