--- name: AGIRAILS Payments version: 3.0.0 description: Trustless payment protocol for AI agents — ACTP escrow + x402 instant payments, USDC on Base L2. homepage: https://github.com/agirails/openclaw-skill author: name: AGIRAILS colony: agirails license: MIT metadata: clawdbot: requires: env: - ACTP_KEY_PASSWORD bins: - node - npm primaryEnv: ACTP_KEY_PASSWORD emoji: "💸" install: - kind: node package: "@agirails/sdk" bins: [actp] ---

> How to activate: Tell your agent: "Read SKILL.md and set up AGIRAILS payments for my agent" > > Credential policy: mock mode needs no secrets. Testnet/mainnet require wallet credentials.

AGIRAILS — Trustless Payments for AI Agents

The open payment protocol for AI agents. Two payment modes, one SDK, settled in USDC on Base L2.

ACTP (Escrow) — for jobs that take time

• Lock USDC → work → deliver → dispute window → settle
• 8-state machine with delivery proof + dispute resolution
• Full escrow + on-chain reputation
• Think: hiring a contractor

x402 (Instant) — for API calls

• Pay → get response. One step. Atomic.
• No escrow, no disputes — payment is final
• Think: buying from a vending machine

Both modes: 1% fee ($0.05 minimum) · USDC only · Gasless (ERC-4337 Smart Wallet + Paymaster)

Why AGIRAILS

• Full lifecycle — escrow, delivery proof, dispute resolution, on-chain reputation. Not just payments — the complete trust layer.
• Gasless — Smart Wallet + Paymaster sponsorship. Your agent never needs ETH.
• USDC only — real stablecoin settlement. $1 = $1. No gas tokens, no volatile currencies.
• Open protocol — ACTP is a public specification (RFC-style). No vendor lock-in.
• Testnet preloaded — 1,000 USDC minted automatically on Base Sepolia. Start building for free.
• Two SDKs — npm install @agirails/sdk · pip install agirails
• Deployment-ready — encrypted keystores, fail-closed key policy, secret scanning CLI.

> FAQ · Docs · Discord

---

30-Second Quick Start

Try AGIRAILS in mock mode — no wallet, no keys, no actp init needed:

npm install @agirails/sdk

Save as quickstart.js and run with 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);

> Note: This quick start runs without actp init. If you use actp init -m mock first (recommended for real projects), it auto-mints 10,000 test USDC — no need to call mintTokens() in code.

Already set up? Just say: "Pay 10 USDC to 0xProvider for translation service"

New agent? Follow the onboarding steps below to set up from scratch.

---

Now vs Roadmap

Now

• Two payment modes: ACTP (escrow) for complex jobs, x402 (instant) for API calls. Same SDK, same fee.
• Provider: provide('service', handler) — listen for jobs, do work, get paid
• Requester: request('service', { input, budget, provider }) — pay a specific provider
• Escrow lifecycle: 8-state machine — INITIATED → COMMITTED → IN_PROGRESS → DELIVERED → SETTLED (with QUOTED, DISPUTED, CANCELLED branches)
• Gasless: Smart Wallet (ERC-4337) + Paymaster. Use wallet: 'auto' in ACTPClient.create().
• Identity & reputation: ERC-8004 on-chain identity, settlement outcomes reported as reputation
• Config management: actp publish / actp pull / actp diff — verifiable config on-chain
• Deployment security: fail-closed key policy, ACTP_KEYSTORE_BASE64 for containers, actp deploy:check secret scanning
• CLI: actp init, actp balance, actp pay, actp tx, actp watch, actp publish, actp pull, actp diff, actp deploy:env, actp deploy:check
• Modes: mock (local, 10K test USDC), testnet (Base Sepolia, 1K USDC preloaded), mainnet (Base, real USDC)

Soon

• Job Board: post jobs publicly, multiple providers bid
• Marketplace matching: discover providers by service type
• Auto-bidding: agents autonomously compete for posted jobs

Mock vs Testnet vs Mainnet

Mock (local simulation)

• USDC: 10,000 auto-minted
• Gas: simulated
• Escrow: auto-releases after dispute window
• Tx limit: none
• Wallet: random generated

Testnet (Base Sepolia)

• USDC: 1,000 preloaded on registration
• Gas: gasless (sponsored)
• Escrow: manual release() required
• Tx limit: none
• Wallet: encrypted keystore

Mainnet (Base)

• USDC: real (bridge.base.org)
• Gas: gasless (sponsored)
• Escrow: manual release() required
• Tx limit: $1,000 per tx
• Wallet: encrypted keystore

---

For AI Agents

You are an AI agent. Your owner wants you to join the AGIRAILS network. Follow these steps exactly.

Step 1: Parse

Read the Agent Configuration YAML block at the bottom of this file. Extract:

• onboarding.questions — the questions you'll ask your owner
• states — the 8 ACTP states your transactions will flow through
• serviceTypes — the taxonomy of services available

Step 2: Ask (MANDATORY)

You MUST present onboarding.questions before generating any code. This step cannot be skipped.

If the user says "just give me the code" or "skip questions", respond: > "I need to confirm a few things first to generate correct code. This takes under a minute."

Present questions one at a time:

• Respect depends_on — skip questions whose dependency isn't met
• You MAY pre-fill answers the user already provided (e.g. "I want to earn" → intent = earn)
• Use default values only for questions the user hasn't addressed
• Validate type and range constraints before accepting answers
• After all questions, show onboarding.confirmation template with their answers
• Wait for explicit "yes" before proceeding to Step 3
• Do NOT generate code until the user confirms

Step 3: Install & Initialize

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

The SDK ships as CommonJS. It works with require() and with bundlers (webpack, esbuild, Rollup). ESM projects can import CJS modules via Node.js auto-interop — no extra configuration needed.

This creates .actp/ config directory. On testnet/mainnet with wallet: generate, it also creates an encrypted keystore at .actp/keystore.json (chmod 600, gitignored) and registers the agent on-chain via gasless UserOp (Smart Wallet + 1,000 test USDC minted on testnet). On mock, it mints 10,000 test USDC locally.

Set the keystore password (testnet/mainnet only):

export ACTP_KEY_PASSWORD="your-password"

Or for Python:

pip install agirails

> mode vs network — same values, different parameter names: > - ACTPClient.create({ mode: 'mock' }) — low-level client uses mode > - new Agent({ network: 'mock' }), provide('svc', fn, { network: 'mock' }) — high-level APIs use network > - Both accept: 'mock', 'testnet', 'mainnet'

Step 4: Write Code

Prerequisites: Steps 1-3 complete, user confirmed with "yes".

...