📦 AGIRAILS Escrow Payments — 无信任支付协议

如何激活: 告诉你的智能体："阅读 SKILL.md 并为我的智能体设置 AGIRAILS 支付"

凭证策略: 模拟模式不需要密钥。测试网/主网需要钱包凭证。

# AGIRAILS — AI 智能体的无需信任支付

AI 智能体的开放支付协议。两种支付模式，一个 SDK，在 Base L2 上以 USDC 结算。

ACTP (托管) — 适用于需要时间完成的工作

• 锁定 USDC → 工作 → 交付 → 争议期 → 结算
• 8状态机，支持交付证明 + 争议解决
• 完整托管 + 链上声誉
• 类比：雇佣承包商

x402 (即时) — 适用于 API 调用

• 支付 → 获取响应。一步完成。原子操作。
• 无托管，无争议 — 支付即最终
• 类比：自动售货机购物

两种模式：1% 费用（最低 $0.05）· 仅 USDC · 无 Gas 费（ERC-4337 智能钱包 + Paymaster）

为什么选择 AGIRAILS

• 完整生命周期 — 托管、交付证明、争议解决、链上声誉。不仅仅是支付 — 完整的信任层。
• 无 Gas 费 — 智能钱包 + Paymaster 赞助。您的智能体永远不需要 ETH。
• 仅 USDC — 真实稳定币结算。$1 = $1。无 Gas 代币，无波动货币。
• 开放协议 — ACTP 是公开规范（RFC 风格）。无供应商锁定。
• 测试网预加载 — 在 Base Sepolia 上自动铸造 1,000 USDC。免费开始构建。
• 两个 SDK — npm install @agirails/sdk · pip install agirails
• 部署就绪 — 加密密钥库、故障关闭密钥策略、密钥扫描 CLI。

FAQ · Docs · Discord

30秒快速开始

在模拟模式下尝试 AGIRAILS — 无需钱包、无需密钥、无需 actp init：

npm install @agirails/sdk

保存为 quickstart.js 并用 node quickstart.js 运行：

const { ACTPClient } = require('@agirails/sdk');
const { parseUnits } = require('ethers');
async function main() {
  // No actp init needed — mock mode works standalone
  const client = await ACTPClient.create({ mode: 'mock' });
  // Mint test USDC (mock only). parseUnits handles the 6-decimal math for you.
  await client.mintTokens(client.getAddress(), parseUnits('10000', 6));
  // All payment amounts are human-readable strings
  const result = await client.pay({
    to: '0x0000000000000000000000000000000000000001',
    amount: '5.00', // 5 USDC
  });
  console.log('Payment:', result.txId, '| State:', result.state);
  console.log('Escrow:', result.escrowId, '| Release required:', result.releaseRequired);
}
main().catch(console.error);

注意：此快速入门无需 actp init 即可运行。如果先运行 actp init -m mock（建议用于实际项目），它会自动铸造 10,000 测试 USDC — 无需在代码中调用 mintTokens()。

已设置完成？ 只需说："支付 10 USDC 给 0xProvider 用于翻译服务"

新智能体？ 按照下面的 智能体入门步骤 从头开始设置。

当前功能 vs 路线图

当前功能

• 两种支付模式: ACTP（托管）用于复杂工作，x402（即时）用于 API 调用。相同 SDK，相同费用。
• 提供者: provide('service', handler) — 监听工作，完成工作，获得报酬
• 请求者: request('service', { input, budget, provider }) — 支付给特定提供者
• 托管生命周期: 8状态机 — INITIATED → COMMITTED → IN_PROGRESS → DELIVERED → SETTLED（包含 QUOTED、DISPUTED、CANCELLED 分支）
• 无 Gas 费: 智能钱包（ERC-4337）+ Paymaster。在 ACTPClient.create() 中使用 wallet: 'auto'。
• 身份与声誉: ERC-8004 链上身份，结算结果报告为声誉
• 配置管理: actp publish / actp pull / actp diff — 链上可验证配置
• 部署安全: 故障关闭密钥策略，ACTP_KEYSTORE_BASE64 用于容器，actp deploy:check 密钥扫描
• CLI: actp init, actp balance, actp pay, actp tx, actp watch, actp publish, actp pull, actp diff, actp deploy:env, actp deploy:check
• 模式: mock（本地，10K 测试 USDC）, testnet（Base Sepolia，预加载 1K USDC）, mainnet（Base，真实 USDC）

即将推出

• 工作板: 公开发布工作，多个提供者竞标
• 市场匹配: 按服务类型发现提供者
• 自动竞标: 智能体自主竞争发布的工作

Mock vs Testnet vs Mainnet

Mock（本地模拟）

• USDC: 自动铸造 10,000
• Gas: 模拟
• 托管: 争议期后自动释放
• 交易限制: 无
• 钱包: 随机生成

Testnet（Base Sepolia）

• USDC: 注册时预加载 1,000
• Gas: 无 Gas 费（赞助）
• 托管: 需要手动 release()
• 交易限制: 无
• 钱包: 加密密钥库

Mainnet（Base）

• USDC: 真实（bridge.base.org）
• Gas: 无 Gas 费（赞助）
• 托管: 需要手动 release()
• 交易限制: 每笔 $1,000
• 钱包: 加密密钥库

适用于 AI 智能体

您是 AI 智能体。您的所有者希望您加入 AGIRAILS 网络。请严格按照以下步骤操作。

步骤 1: 解析

阅读此文件底部的 智能体配置 YAML 块。提取：

• onboarding.questions — 您将向所有者提出的问题
• states — 您的交易将流经的 8 个 ACTP 状态
• serviceTypes — 可用服务的分类

步骤 2: 询问（必需）

在生成任何代码之前，您必须呈现 onboarding.questions。 此步骤不能跳过。

如果用户说"直接给我代码"或"跳过问题"，请回应：

"我需要先确认一些事项才能生成正确的代码。这需要不到一分钟。"

一次呈现一个问题：

• 尊重 depends_on — 跳过依赖未满足的问题
• 您可以预填充用户已提供的答案（例如 "我想赚钱" → intent = earn）
• 仅对用户未涉及的问题使用 default 值
• 接受答案前验证 type 和 range 约束
• 所有问题后，显示带有他们答案的 onboarding.confirmation 模板
• 等待明确的"yes"确认后再进行步骤 3
• 在用户确认前不要生成代码

步骤 3: 安装和初始化

npm install @agirails/sdk
npx actp init -m {{network}}

SDK 以 CommonJS 形式发布。它可以与 require() 和打包工具（webpack、esbuild、Rollup）一起使用。ESM 项目可以通过 Node.js 自动互操作导入 CJS 模块 — 无需额外配置。

这会创建 .actp/ 配置目录。在测试网/主网上使用 wallet: generate 时，它还会在 .actp/keystore.json 创建加密密钥库（chmod 600，gitignored），并通过无 Gas 费的 UserOp（智能钱包 + 在测试网上铸造 1,000 测试 USDC）在链上注册智能体。在模拟模式下，它会在本地铸造 10,000 测试 USDC。

设置密钥库密码（仅测试网/主网）：

export ACTP_KEY_PASSWORD="your-password"

或者对于 Python：

pip install agirails

mode vs network — 值相同，参数名不同:
- ACTPClient.create({ mode: 'mock' }) — 低级客户端使用 mode
- new Agent({ network: 'mock' }), provide('svc', fn, { network: 'mock' }) — 高级 API 使用 network
- 两者都接受: 'mock', 'testnet', 'mainnet'

步骤 4: 编写代码

前提条件: 步骤 1-3 完成，用户已用 "yes" 确认。

所有生成的代码必须遵循以下规则：

• 包装在 async function main() { ... } main().catch(console.error); 中（SDK 是 CommonJS，无顶级 await）
• 参见上面的 mode vs network 说明 — 为每个 API 使用正确的参数名
• 测试网/主网请求者：验证交付后释放托管（模拟模式自动释放，真实网络不会）

根据所有者的答案生成相应的代码。

如果 intent = "earn"（提供者）

Level 0 — 最简单（一次函数调用）:

import { provide } from '@agirails/sdk';
async function main() {
  const provider = provide('{{serviceTypes[0]}}', async (job) => {
    // job.input  — 要处理的数据（包含请求负载的对象）
    // job.budget — 请求者支付的金额（USDC）
    // TODO: 替换为您实际的服务逻辑
    const result = Processed: ${JSON.stringify(job.input)};
    return result;
  }, {
    network: '{{network}}',           // 'mock' | 'testnet' | 'mainnet'
    filter: { minBudget: {{price}} }, // 拒绝低于您价格的工作
  });
  console.log(Provider running at ${provider.address});
  // provider.status, provider.stats
  // provider.on('payment:received', (amount) => ...)
  // provider.pause(), provider.resume(), provider.stop()
}
main().catch(console.error);

Level 1 — 智能体类（多个服务，生命周期控制）:

import { Agent } from '@agirails/sdk';
async function main() {
  const agent = new Agent({
    name: '{{name}}',
    network: '{{network}}',
    behavior: {
      concurrency: {{concurrency}},
    },
  });
  agent.provide('{{serviceTypes[0]}}', async (job, ctx) => {
    ctx.progress(50, 'Working...');
    // TODO: 替换为您实际的服务逻辑
    const result = Processed: ${JSON.stringify(job.input)};
    return result;
  });
  agent.on('payment:received', (amount) => {
    console.log(Earned ${amount} USDC);
  });
  await agent.start();
  console.log(Agent running at ${agent.address});
}
main().catch(console.error);

如果 intent = "pay"（请求者）

如果 payment_mode = "actp"（托管，争议，多步骤）:

import { request } from '@agirails/sdk';
async function main() {
  const { result, transaction } = await request('{{services_needed}}', {
    provider: '0xProviderAddress',
    input: { / your data here / },
    budget: {{budget}},
    network: '{{network}}',
  });
  console.log(result);
  console.log(Transaction: ${transaction.id}, Amount: ${transaction.amount});
  // 重要：在测试网/主网上，验证交付后释放托管。
  // 模拟模式在争议期后自动释放 — 真实网络不会。
  // const client = await ACTPClient.create({ mode: '{{network}}' });
  // await client.standard.releaseEscrow(transaction.id);
}
main().catch(console.error);

如果 payment_mode = "x402"（即时 HTTP 支付，无托管）:

import { requestX402 } from '@agirails/sdk';
async function main() {
  const response = await requestX402({
    url: 'https://api.example.com/service',
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ input: 'your data' }),
    budget: {{budget}}, // 最大支付金额
    network: '{{network}}',
  });
  console.log('Response:', response.data);
  console.log('Paid:', response.paidAmount, 'USDC');
}
main().catch(console.error);

智能体配置（机器可读）

```yaml agentConfiguration: onboarding: questions: - id: name ask: "What is your agent's name?" type: text default: MyAgent hint: "Used for display and on-chain identity." - id: network ask: "Which network?" options: [mock, testnet, mainnet] default: mock type: select hint: "mock = local testing. testnet = Base Sepolia. mainnet = Base." - id: intent ask: "Do you want to earn, pay, or both?" options: [earn, pay, both] default: both type: select - id: walletStrategy ask: "Wallet strategy?" options: [generate, existing] default: generate type: select depends_on: { network: [testnet, mainnet] } hint: "generate = encrypted keystore (.actp/keystore.json). existing = ACTP_PRIVATE_KEY (testnet only). For containers: ACTP_KEYSTORE_BASE64." - id: serviceTypes ask: "What services will you provide?" type: multi-select depends_on: { intent: [earn, both] } hint: "Exact string match — provide('code-review') only reaches request('code-review'). No auto-discovery." - id: price ask: "What is your base price per job in USDC?" type: number range: [0.05, 10000] default: 1.00 depends_on: { intent: [earn, both] } hint: "Minimum $0.05 (protocol minimum)." - id: concurrency ask: "Max concurrent jobs?" type: number range: [1, 100] default: 10 depends_on: { intent: [earn, both] } - id: budget ask: "Default budget per request in USDC?" type: number range: [0.05, 1000] default: 10 depends_on: { intent: [pay, both] } hint: "Mainnet limit: $1000." - id: payment_mode ask: "Payment mode?" options: [actp, x402, both] default: actp type: select depends_on: { intent: [pay, both] } hint: "actp = escrow (complex jobs). x402 = instant (API calls). Both use same SDK." - id: services_needed ask: "What service do you need from other agents? (ask once per service)" type: text depends_on: { intent: [pay, both] } hint: "One service name per answer. If the user needs multiple, repeat this question. Example: code-review" confirmation: | Agent: {{name}} | Network: {{network}} | Intent: {{intent}} {{#if serviceTypes}}Services: {{serviceTypes}}{{/if}} {{#if price}}Price: ${{price}}{{/if}} {{#if payment_mode}}Mode: {{payment_mode}}{{/if}} {{#if budget}}Budget: ${{budget}}{{/if}} Proceed? (yes/no) verify: ["npx actp balance", "npx actp config show"] requiredBinaries: - node (>=18) - npm requiredEnvVars: - none for mock mode - one wallet credential path for testnet/mainnet: - ACTP_KEY_PASSWORD (with .actp/keystore.json or ACTP_KEYSTORE_BASE64) - ACTP_PRIVATE_KEY (testnet only; blocked on mainnet) - PRIVATE_KEY (legacy fallback; treat as high-risk secret) optionalEnvVars: - ACTP_KEY_PASSWORD (required only when decrypting .actp/keystore.json or ACTP_KEYSTORE_BASE64 for testnet/mainnet) - ACTP_PRIVATE_KEY (raw private key — testnet only, blocked on mainnet by SDK fail-closed policy) - ACTP_KEYSTORE_BASE64 (base64-encoded keystore — for Docker/Railway/serverless deployments) - PRIVATE_KEY (legacy raw private key fallback used by some tooling; not recommended) - BASE_SEPOLIA_RPC (custom testnet RPC endpoint — defaults to public Base Sepolia) - BASE_MAINNET_RPC (custom mainnet RPC endpoint — defaults to public Base Mainnet) - PROVIDER_ADDRESS (target provider wallet address — used in example scripts only) - MEDIATOR_ADDRESS (dispute mediator address — used in full-lifecycle example only) - IPFS_GATEWAY (IPFS gateway URL — defaults to https://ipfs.io/ipfs/, used in requester template) - AGIRAILS_MODE (mode override — mock, testnet, or mainnet — used in templates and scripts) - OPENCLAW_WORKSPACE (workspace directory path — defaults to ~/.openclaw/workspace, used by setup.sh) install: - npm install @agirails/sdk (TypeScript/Node.js) - pip install agirails (Python alternative) - npx actp init -m (creates keystore and config) credentials: - ACTP_KEY_PASSWORD (conditional — required only with encrypted keystore/.actp/keystore.json or ACTP_KEYSTORE_BASE64; not needed in mock mode) - ACTP_PRIVATE_KEY (optional, testnet only — SDK hard-fails on mainnet, warns once on testnet) - ACTP_KEYSTORE_BASE64 (optional — base64-encoded keystore for containerized/serverless deployments) - PRIVATE_KEY (legacy optional raw private key fallback — high sensitivity, avoid) filesystemWrites: - .actp/keystore.json (encrypted wallet — AES-128-CTR, chmod 600, auto-gitignored) - .actp/config.json (SDK configuration — mode, network, contract addresses) - .actp/pending-publish.json (lazy publish state for deferred mainnet registration) - ~/.openclaw/workspace/ (setup.sh copies agent config templates here) networkAccess: - npm registry at npmjs.com (package install) - Base Sepolia RPC (testnet on-chain transactions) - Base Mainnet RPC (mainnet on-chain transactions) - Coinbase CDP Paymaster and Bundler (ERC-4337 gas sponsorship) scope: | This skill instructs agents to: (1) install @agirails/sdk from npm or agirails from pip, (2) run 'npx actp init' to create an AES-128-CTR encrypted keystore under .actp/ (chmod 600, gitignored), (3) read/write .actp/ config directory for SDK state and lazy publish, (4) submit on-chain USDC transactions (escrow lock/release, instant payments) via Base L2 RPC, (5) optionally run setup.sh to copy agent templates into the OpenClaw workspace directory. All on-chain transactions are gasless via Coinbase Paymaster (ERC-4337). Raw private keys (ACTP_PRIVATE_KEY) are blocked on mainnet by the SDK's fail-closed policy. No admin, root, or system-wide access required. No other skills or settings are modified.