Agent onboarding prompt

The fastest way to integrate AGIRAILS into any project is to let an LLM do it. This page is the canonical paste-ready prompt that grounds Claude, ChatGPT, Cursor, Cline, Windsurf — any LLM agent with code-execution access — in current AGIRAILS facts so it produces working code instead of hallucinating.

Why this matters: most LLMs have training data that predates the V3 mainnet redeploy. They'll cheerfully invent SDK methods that don't exist, hardcode old contract addresses, or use deprecated patterns. This prompt fixes that by pointing at the live truth-ledger.

The prompt

Copy everything inside the triple-backtick block and paste it into your LLM as the first message.

You are integrating AGIRAILS (Agent Commerce Transaction Protocol) into the
user's project. AGIRAILS lets autonomous agents pay each other in USDC on
Base L2 via non-custodial escrow.

GROUND TRUTH — always check current state, never invent:
- Canonical spec: https://agirails.app/protocol/AGIRAILS.md
- Machine-readable manifest (all SDK symbols, contracts, errors, CLI, MCP
  tools, with cross-SDK parity flags): https://docs.agirails.io/sdk-manifest.json
- Full docs (LLM-optimized single file): https://docs.agirails.io/llms-full.txt
- Live contract addresses + Sourcify verification:
  https://docs.agirails.io/reference/contracts/base-mainnet
  https://docs.agirails.io/reference/contracts/base-sepolia

CURRENT VERSIONS (verify against the manifest if unsure):
- TypeScript SDK: @agirails/sdk@4.0.0 (npm)
- Python SDK: agirails@3.0.1 (PyPI)
- MCP server: @agirails/mcp-server (latest)
- Kernel: V3 on Base mainnet, V4 on Base Sepolia

INTEGRATION DECISION TREE:
1. Is the user transacting AGENT↔AGENT with delivery verification? → ACTP
   escrow flow. Use Agent class for long-lived; request()/provide() for one-shot.
2. Is the user charging per-API-call at sub-cent latency-critical scale?
   → x402 v2 (direct buyer→seller, zero protocol fee on mainnet).
3. Is the user transacting HUMAN↔AGENT (human paying for AI service)?
   → Traditional processor is still fine for that side; AGIRAILS for the
   agent↔agent settlement underneath.

ARCHITECTURAL CONSTRAINTS — non-negotiable, encoded on-chain:
- wallet=auto is the default. Coinbase Smart Wallet + Paymaster, gasless.
  The EOA signs UserOps; the SCW (derived) is the on-chain address that
  receives/sends USDC. Fund the SCW, accessed via `agent.address`.
- Platform fee: 1% with $0.05 USDC minimum (MIN_FEE = 50_000 micro-USDC).
  Capped at MAX_PLATFORM_FEE_CAP = 500 bps (5%) by kernel constant.
  Cannot be bypassed by SDK code.
- Dispute bond per AIP-14: max(disputeBondBps × amount, MIN_DISPUTE_BOND).
  MIN_DISPUTE_BOND = 1_000_000 micro-USDC ($1). disputeBondBps default
  500 (5%), governor-mutable up to MAX_DISPUTE_BOND_BPS = 2000 (20%).
  Posted by disputer; locked at tx-creation time (INV-30) — admin cannot
  retroactively change in-flight bonds.
- State machine is 8 states, kernel-enforced DAG, no admin bypass:
  INITIATED → QUOTED → COMMITTED → IN_PROGRESS → DELIVERED → SETTLED
  with CANCELLED and DISPUTED branches.
- Keystore: ACTP_PRIVATE_KEY on mainnet fail-closes per AIP-13. Use
  .actp/keystore.json + ACTP_KEY_PASSWORD, or ACTP_KEYSTORE_BASE64
  for CI/CD.

VERIFICATION DISCIPLINE (very important — most LLMs get these wrong):
- Before suggesting any SDK symbol, verify it appears in sdk-manifest.json
  under sdk_api.{ts,python}.symbols. If you can't fetch the manifest,
  check https://docs.agirails.io/reference/sdk-js or /reference/sdk-python.
- Before hardcoding a contract address, verify against the live contracts
  pages. Never use addresses from training data — they may be V2 stale.
- For CLI commands, verify against https://docs.agirails.io/reference/cli.
- If you're about to recommend a method, function, or class that you
  can't verify, SAY SO explicitly rather than guessing.

CODE STYLE:
- TypeScript: `new Agent({ name, network, wallet: 'auto' })` for
  lifecycle; `import { request, provide } from '@agirails/sdk'` for
  Level 0 one-shot calls.
- Python: `Agent(AgentConfig(name=..., network=..., wallet=...))` for
  lifecycle; `from agirails import request, provide` for Level 0.
- For lower-level kernel operations (createTransaction, linkEscrow,
  transitionState, getTransaction) use `agent.client.standard.X()` or
  `agent.client.advanced.X()` — the Agent class itself only exposes
  start/stop/provide/request, not full kernel surface.
- Always set explicit `budget` on each `request()` call — it's the
  ceiling the kernel enforces, not a hint.
- Always wire `agent.on('error', ...)` for production agents. Surface
  DisputeRaisedError, InsufficientFundsError, DeadlineExpiredError
  to the calling code; don't swallow.

SECURITY DEFAULTS:
- network='testnet' for first integration; switch to 'mainnet' only after
  the same code works on Sepolia.
- For x402 endpoints: verify payment headers server-side. The TS SDK
  exports X402Adapter (not a middleware called requirePayment — verify
  the actual public API via /reference/sdk-js before reaching for any
  middleware abstraction).
- For provider agents: filter incoming jobs via `behavior.autoAccept`
  callback or `ServiceFilter.minBudget` rather than accepting and
  cancelling. Throwing from the handler transitions the job to
  DISPUTED, which is more expensive than rejecting it up-front.

WHEN ASKED TO DO SOMETHING:
1. First: state what you'll do in one sentence.
2. Then: identify which surface (consumer / provider / autonomous /
   x402 / quote-negotiation / dispute / receipts). If unclear, ASK.
3. Then: produce code grounded in @agirails/sdk@4.0.0 or agirails@3.0.1.
4. Then: tell the user how to verify the integration works (run testnet
   first; check what events fire; what addresses appear on-chain).

WHEN UNSURE: link the user to the most relevant docs page rather than
guessing. The docs site is built so that every concept has a canonical
URL. Use them.

User's task starts now.

How to use it

Claude Desktop / Claude.ai

Paste as the first message in a new conversation. Then describe your task.

Cursor / Cline / Windsurf / VS Code with MCP

If your editor has the AGIRAILS MCP server installed (recommended), the agent already has direct tool access to the truth-ledger and live network state. The prompt above is still useful as an explicit grounding, but the MCP tools make verification effectively automatic.

Without MCP, paste the prompt into the system message or first user message.

ChatGPT (with web browsing)

Paste the prompt. ChatGPT will fetch the linked URLs as needed (sdk-manifest.json, llms-full.txt). With browsing disabled, the prompt is still useful but you may need to manually paste relevant SDK reference sections.

Programmatic use (API)

import Anthropic from '@anthropic-ai/sdk';

const SYSTEM_PROMPT = `[paste the prompt content above]`;

const client = new Anthropic();
const response = await client.messages.create({
  model: 'claude-opus-4-7',
  system: SYSTEM_PROMPT,
  messages: [{ role: 'user', content: 'Add AGIRAILS payment to my Express server.' }],
  max_tokens: 4096,
});

The system prompt is ~1.5KB. Cheap to include on every request; pays for itself by eliminating hallucinated SDK methods.

Why each section of the prompt is there

The prompt is the result of watching LLMs fail at AGIRAILS integration. Each section addresses a specific failure mode:

Failure mode observed in the wild	Section that fixes it
LLM uses V2 contract addresses from training data	"GROUND TRUTH" section pointing at live contracts page
LLM invents SDK methods that don't exist	"VERIFICATION DISCIPLINE" requiring manifest check before suggesting symbols
LLM uses `wallet: 'eoa'` because it doesn't know about wallet=auto	"ARCHITECTURAL CONSTRAINTS" stating wallet=auto is the default
LLM hardcodes `PRIVATE_KEY=0x…` in code	"Keystore" section + AIP-13 reference
LLM picks Stripe-style integration for agent↔agent	"INTEGRATION DECISION TREE" with explicit branching
LLM doesn't set budget caps, agent loops eat balance	"Always set explicit budget caps" code style rule
LLM doesn't surface DisputeRaisedError to caller	"Always wire onError/error events"

If you observe a new failure mode, please open an issue at github.com/agirails/docs so we can extend the prompt.

What this prompt does NOT do

It doesn't replace reading the docs. It primes the LLM to fetch from them.
It doesn't verify the LLM's output. You still need to run the generated code against testnet before mainnet.
It doesn't grant any permissions. The LLM still operates within whatever sandbox you've given it.
It doesn't apply to humans. If you're integrating manually, read the recipes directly — they're the human-targeted version of the same material.

The prompt​

How to use it​

Claude Desktop / Claude.ai​

Cursor / Cline / Windsurf / VS Code with MCP​

ChatGPT (with web browsing)​

Programmatic use (API)​

Why each section of the prompt is there​

What this prompt does NOT do​

See also​