arbitova

Arbitova

为 Base 上 Agent-to-Agent 支付提供非托管 USDC 托管与 AI 仲裁。

两个 Agent 将 USDC 锁定在合约中，一个交付，另一个确认或提出争议，然后由中立的 AI 仲裁者裁决。Arbitova 从不持有资金——资金由合约持有。

无需 API 密钥。无需注册。无需托管。你的 Ethereum 地址就是你的身份。

• 合约：Base Sepolia 上的 EscrowV1，地址为 0xA8a031bcaD2f840b451c19db8e43CEAF86a088fC——已在 Basescan 上验证，主网将在审计后上线
• 规范：A2A-ESCROW-RFC-v0.1
• 机器可读描述文件：/.well-known/arbitova.json
• 个案裁决面板：arbitova.com/verdicts
• 集成方式：arbitova.com/integrate（原始合约 / 参考 SDK / Agent 原生）
• 参考 UI（非规范，仅供人类使用）：arbitova.com/pay
• 15 分钟教程：docs/tutorials/15-min-paid-agent.md

---

为什么要做这个项目

目前所有 A2A / Agent 商务规范——MCP、Google 的 A2A、ERC-7683、Coinbase 的 Agent Commerce——都定义了 Agent 如何通信。但它们都没有定义 当 Agent 彼此不信任时，资金如何流转。

Arbitova 补上了缺失的结算基础构件：

• 确定性状态机。 createEscrow → markDelivered → {confirmDelivery | dispute → resolve | cancel}。没有隐藏分支，也没有管理员覆写。
• 超时后不会自动放款。 审核窗口到期后进入 DISPUTED，而不是向卖家付款。保持沉默比错误确认更安全。
• 链上固定内容哈希。 买家检查交付文件后，卖家无法替换文件。
• 逐案裁决透明度。 每项仲裁决定都是一个经过签名的 JSON 数据块，其 keccak256 哈希存储在链上。可在 /verdicts 查询完整裁决历史——不汇总、不延迟。

这不是一个市场。没有 Arbitova 账户、上架费或 Pro 级别。协议就是全部产品。

---

快速开始 — Node.js SDK

npm install @arbitova/sdk ethers

import { Arbitova } from '@arbitova/sdk';

const buyer = await Arbitova.fromPrivateKey({ privateKey: process.env.BUYER_PK });

const { escrowId, txHash } = await buyer.createEscrow({
  seller: process.env.SELLER_ADDRESS,
  amount: '5.00',
  deliveryHours: 24,
  reviewHours: 24,
  verificationURI: 'https://example.com/spec.json',
});

console.log(`Escrow #${escrowId} locked — ${buyer.explorerTx(txHash)}`);

卖家端、仲裁者端及浏览器钱包集成，请参阅 packages/sdk-js/README.md。

快速开始 — Python SDK

pip install "arbitova[path_b]"

from arbitova import path_b

result = path_b.arbitova_create_escrow(
    seller="0x...",
    amount=5.00,
    verification_uri="https://example.com/spec.json",
)
print(result)

快速开始 — Claude / 任意 MCP 客户端

{
  "mcpServers": {
    "arbitova": {
      "command": "npx",
      "args": ["-y", "@arbitova/mcp-server"],
      "env": {
        "ARBITOVA_RPC_URL": "https://sepolia.base.org",
        "ARBITOVA_ESCROW_ADDRESS": "0xA8a031bcaD2f840b451c19db8e43CEAF86a088fC",
        "ARBITOVA_USDC_ADDRESS": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        "ARBITOVA_AGENT_PRIVATE_KEY": "0x..."
      }
    }
  }
}

六个工具：arbitova_create_escrow、arbitova_mark_delivered、arbitova_confirm_delivery、arbitova_dispute、arbitova_cancel_if_not_delivered、arbitova_get_escrow。所有操作都通过 ethers v6 在本地签名。你的私钥永远不会离开进程。

省略 ARBITOVA_AGENT_PRIVATE_KEY 即可进入只读查询模式（适用于可观测性）。

---

生命周期

                      ┌──────────────────┐
                      │     CREATED      │ buyer locked USDC
                      └────────┬─────────┘
                               │
                               ▼ seller.markDelivered()
                      ┌──────────────────┐
                      │    DELIVERED     │ deliveryHash on-chain
                      └────────┬─────────┘
                               │
        buyer.confirmDelivery()│        │ buyer.dispute()
                               │        │ or seller.dispute()
                               ▼        ▼
                   ┌─────────────┐  ┌──────────┐
                   │  RELEASED   │  │ DISPUTED │ waiting for arbiter
                   └─────────────┘  └────┬─────┘
                                         │ arbiter.resolve(bps split + verdictHash)
                                         ▼
                                   ┌──────────┐
                                   │ RESOLVED │
                                   └──────────┘

图中未绘制的两个终止状态：CANCELLED（买家在交付窗口结束后调用 cancelIfNotDelivered），以及审核窗口到期且未获确认时自动升级为 DISPUTED。

---

框架参考 Agent

三个在 Base Sepolia 上运行的端到端 A2A 演示，使用实时 AI 仲裁者：

• Claude Agent SDK — 进程内 MCP 工具
• LangGraph — ReAct Agent，包含买家、卖家和仲裁者
• CrewAI — Agent + Task + Crew

每个演示都会通过真实的链上交易，运行完整的 CREATED → DELIVERED → CONFIRMED（或 DISPUTED → RESOLVED）流程。

---

Packages

包	用途
@arbitova/sdk	Node.js / 浏览器 SDK（ethers v6）
arbitova	Python SDK，安装时添加 [path_b] extra 以支持链上功能
@arbitova/mcp-server	MCP 服务（6 个链上工具），适用于 Claude Desktop、Claude Code 及任何 MCP 客户端

每个包都提供相同的六个入口，因此使用 Python SDK 的 Agent 可以与使用 MCP 服务的 Agent 结算——它们调用的是同一份合约。

---

费用

情况	费用	支付方
confirmDelivery / 审核窗口到期后自动结算	0.5%	从卖方的款项中扣除
仲裁员解决争议	2%	按仲裁员裁决分摊

费用会在合约中累积。协议依靠这些费用运行；无需订阅。

---

网络

网络	状态	合约
Base Sepolia	已上线，使用真实的 Circle USDC	0xA8a031bcaD2f840b451c19db8e43CEAF86a088fC
Base 主网	待审计并配置多签仲裁员	TBA

关注 开发日志，了解主网上线情况。

---

旧版（Path A）

SDK 的 v2.x 版本和 MCP 服务的 v3.4.0 版本曾是面向 api.arbitova.com 的托管式 HTTP 客户端。该架构存在四个结构性问题（数据库与链上数据不一致、托管钱包 Gas、单一 ADMIN_KEY、单一 WALLET_ENCRYPTION_KEY 故障点），因此已弃用，转而采用 Path B——上文所述的非托管链上设计。

• SDK 用户迁移指南：sdk/MIGRATION_PATH_A_TO_B.md
• MCP 用户迁移指南：mcp-server/MIGRATION.md

旧版包仍保留在 npm/PyPI 上，但已弃用。

---

许可证

MIT