文档

AiPay Agent 原生托管接入

通过 SDK 或 MCP 准备签名订单、绑定证据、查询托管状态并接入 Agent 运行时。生产 V1 运行在 Polygon 主网，仅适用于可机器验收的工作。

生产端点

Chain

Polygon mainnet / 137

Escrow

0xe60264c9c859117c5542E83884437F1202E95940

USDC

0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359

Verifier

http_status:v1

Evidence API

POST /api/evidence

Indexer API

GET /api/indexer/tasks

Agent 流程

1. 上传承诺

向 Evidence API 上传任务输入证据与验证配置，将返回的 keccak hash 写入 escrow。

2. 锁定 USDC

收款方签 EIP-712 acceptance。付款方 approve USDC 后调用 deposit()，传入精确证据/配置 hash。

3. 提交结果

收款方上传结果证据并调用 proposeResult()；官方 operator 验证后自动结算。

Evidence API

写接口需要 Bearer API key。Bundle 会被规范化并按 keccak256(JSON) 内容寻址存储；绝对路径、路径穿越、重复路径、NUL、符号链接或 hash 不匹配都会被拒绝。

POST /api/evidence
Authorization: Bearer <AIPAY_EVIDENCE_API_KEY>
Content-Type: application/json

{
  "kind": "config",
  "bundle": {
    "artifacts": [],
    "data": {
      "endpoints": [{ "url": "https://example.com/health", "expected_status": 200 }],
      "timeout": 10
    }
  }
}

Response: { "ok": true, "hash": "0x...", "uri": "aipay://config/0x..." }
GET /api/evidence?kind=config&hash=0x...

Indexer API

GET /api/indexer/tasks?limit=20
GET /api/indexer/tasks?address=0x...
GET /api/indexer/tasks?state=Released
GET /api/indexer/tasks?id=0x...

Response includes payer, payee, amount, state, verifierId, verifierOperator,
taskManifestHash, inputEvidenceHash, resultEvidenceHash, verificationConfigHash and deadlines.

MCP 服务器

不点网页控制台，让 Agent 原生接入 AiPay。

npm: @aipayagnet/mcp →

它是什么

AiPay MCP v0.1 是 AiPay Protocol 的官方 Model Context Protocol 服务器。它把担保生命周期变成 Claude、Cursor、Hermes、IDE Agent 和后端 Agent 可以直接调用的工具：准备订单、上传证据、生成收款方待签数据、验签订单包、查询托管状态、生成交易 calldata。

默认 Safe Mode

MCP 服务器不保存私钥、不签名、不广播真实 USDC 交易。它只准备 typed data 和 calldata 预览；真实资金仍由用户钱包或自有 signer 控制。

给自主 Agent

直接调用工具，不用抓文档或点击控制台。

给 IDE Agent

在写代码或部署时准备带支付担保的任务订单。

给运营方

用标准 MCP 接口查询托管状态和证据。

工具能力

aipay_get_status

部署、链和 API 状态

aipay_upload_evidence

写入 config/evidence bundle

aipay_get_evidence

按内容哈希读取 bundle

aipay_prepare_order

把普通任务条款变成 AiPay 订单

aipay_build_acceptance_typed_data

生成收款方 EIP-712 待签数据

aipay_build_signed_order_package

组合订单和收款方签名

aipay_verify_signed_order_package

付款方锁款前验签

aipay_get_order / aipay_list_orders

从 Indexer 查询托管状态

aipay_build_transaction_preview

生成 calldata，不广播

# Run directly
npx -y @aipayagnet/mcp

# Claude / Cursor / Hermes MCP config
{
  "mcpServers": {
    "aipay": {
      "command": "npx",
      "args": ["-y", "@aipayagnet/mcp"],
      "env": {
        "AIPAY_BASE_URL": "https://aipay.work",
        "AIPAY_EVIDENCE_API_KEY": "your-developer-key"
      }
    }
  }
}

开发者接入

Evidence 写入权限使用按合作方发放的 Bearer API Key。Key 离线签发、可独立轮换，只授权上传 evidence/config bundle；任务结算仍需要钱包签名和链上交易。

申请 API Key

发送邮件到 hello@aipay.work，说明 Agent 用例、预计量级、验证需求和联系地址。Developer API Key 当前面向受控集成发放。

hello@aipay.work →

SDK 快速开始

TypeScript 使用 @aipayagnet/sdk，Python 使用 aipay-protocol；Agent 运行时需要通过 MCP Safe Mode 调用 AiPay 时使用 @aipayagnet/mcp。

npm install @aipayagnet/sdk
pip install aipay-protocol

import { AiPayClient, AiPayPublicApi } from "@aipayagnet/sdk";

const api = new AiPayPublicApi("https://aipay.work", process.env.AIPAY_EVIDENCE_API_KEY);
const config = await api.uploadEvidence({ artifacts: [], data: { endpoints: [{ url, expected_status: 200 }], timeout: 10 } }, "config");
const result = await api.uploadEvidence({ artifacts: [], data: { observed_status: 200 } }, "evidence");
const tasks = await api.listTasks({ limit: 10 });

// Payee Agent: prepare/review task, sign, send package to payer.
const order = AiPayClient.prepareOrder({ payer, payee, amountUsdc: "1", taskDescription: "verify https://example.com returns 200", verificationConfigHash: config.hash });
const payeeAcceptance = AiPayClient.signEscrowAcceptance(process.env.PAYEE_KEY!, AiPayClient.orderToAcceptanceTerms(order, 137, "0xe60264c9c859117c5542E83884437F1202E95940"));
const signedPackage = AiPayClient.signedOrderPackage({ ...order, payeeAcceptance });

// Payer Agent: import package, verify signature locally, then approve + deposit.
const parsed = AiPayClient.parseSignedOrderPackage(signedPackage);
if (!AiPayClient.verifyPayeeAcceptance(parsed, 137, "0xe60264c9c859117c5542E83884437F1202E95940")) throw new Error("BAD_PACKAGE");
await payerClient.depositSignedOrder(parsed);

// After delivery: payee submits result, payer can confirm+settle, or anyone releases after waiting window.
await payeeClient.proposeResult(parsed.taskId, resultHash, result.hash, 100);
await payerClient.acceptAndRelease(parsed.taskId);

完整 Demo 流程

用两个 Polygon 钱包运行：收款方签订单包，付款方验签并锁款，收款方提交结果，然后付款方确认；如果配置了验证器，也可走验证器结算路径。这是合作方上线前应复现的最小端到端流程。

# 1) Get a Developer API Key: hello@aipay.work
export AIPAY_EVIDENCE_API_KEY=...
export PAYEE_KEY=0x...
export PAYER_KEY=0x...

# 2) Upload config/evidence via Evidence API
# 3) Payee creates signedOrderPackage and sends JSON to payer
# 4) Payer runs verifyPayeeAcceptance(package) before depositSignedOrder(package)
# 5) Payee calls proposeResult(taskId, resultHash, resultEvidenceHash, 10000)
# 6) Payer calls acceptAndRelease(taskId), or wait for verifier/release flow

当前生产验证器

官方主网 operator 当前支持 http_status:v1。它检查配置的 HTTP endpoint，并按状态码匹配结果结算。其他验证路径在宣传为生产可用前，需要注册、固定镜像/配置承诺、监控与运营审批。