Learning Roadmap

Experimental Project

AgentPay is currently experimental and has not undergone an independent security audit. Do not use with production funds. Testing on testnets with test tokens is strongly recommended.

Agents are evolving from "answering questions" to "executing tasks": calling paid APIs, purchasing data, renting compute, and even hiring other agents. When agents begin to spend money, a fundamental question emerges:

Without human sign-off on every transaction, under what conditions is an agent authorized to spend money?

This knowledge base explains the background of the problem and how AgentPay addresses it. No prior blockchain or payment expertise is required.

AgentPay in a Nutshell

LLMs can propose payments, but must never approve payments.

AgentPay is an independent control layer placed between agents and real funds. Per-transaction limits, rolling budgets, payee whitelists, circuit breakers, failure recovery, and audit trails are all enforced by deterministic code, never left to model discretion.

Division of responsibility with the x402 protocol:

	Question Answered
x402	How to pay?
AgentPay	Should it be paid? How much? What happens if it fails?

Where Should I Start?

🚀 Want to see results first: 10-Minute Experience

Walk through three scenarios in one script: Normal payment success → Over-budget rejection → Runaway loop tripped by circuit breaker.

→ 10-Minute Demo

Choose Your Learning Path by Role

I am an Agent Developer (Buyer)

I want my agent to safely call paid APIs without draining funds.

1. Common Agent Failure Modes
2. Why We Need a Financial Firewall
3. Budget Reservation: Why "Check Then Pay" Fails
4. Timeout Is Not Failure
5. 10-Minute Demo

I am an API Provider (Seller)

I want to monetize my API into a pay-per-request endpoint.

1. HTTP 402 & x402
2. Complete Payment Lifecycle
3. Configure Your First Paid Route in the Console
4. Draft, Publish & Rollback

I am an Enterprise Administrator

I manage multiple agents and am accountable for all outgoing expenditures.

1. Agent Infrastructure Landscape
2. Tenants, Projects, Agents & API Keys
3. Dual-Rail Architecture: Virtual Wallets vs On-Chain
4. Agent Identity: Observation vs Self-Reporting
5. Troubleshooting with Audit Timelines

Complete Table of Contents

Organized from broad to specific: first universal agent and payment knowledge, then where AgentPay fits in the infrastructure stack, followed by core architectural concepts and hands-on tutorials.

Chapter 1: Agent Development Basics

Universal knowledge independent of AgentPay, explaining why agents require financial boundaries.

What is an Agent · Tool Calling · MCP Standard · Agent Frameworks · Failure Modes · Autonomy Levels

Chapter 2: Agent Payments

Why agents need to spend money, limitations of current payment methods, and what x402 and stablecoins solve.

Why Agents Need to Pay · Payment Options Compared · HTTP 402 & x402 · Stablecoins & USDC · Gasless Auth (EIP-3009) · Micropayment Economics · Five Trust Problems · Ecosystem Landscape

Chapter 3: Infrastructure Map

Connecting earlier concepts to understand where AgentPay sits in the agent infrastructure stack and what it deliberately does not do.

Agent Stack Layers · Where AgentPay Fits · AgentPay vs x402

Chapter 4: AgentPay Core Concepts

The "why" behind the design, with each article starting from a real failure scenario.

Financial Firewall · Payment Lifecycle · Timeout Is Not Failure · Three-State Model · Budget Reservation · Dual-Rail Architecture · Agent Identity · Idempotency & Free Replays · Multi-Tenant Model · Threat Model Lite

Chapter 5: Hands-On Tutorials

Practical guides based on Python SDK, Go Gateway, and Web Management Console.

10-Minute Demo · First Paid Route · Policy in Action · Read Payment Trace · Audit Timeline & Kill Switch · Draft, Publish & Rollback

Chapter 6: Quick Reference

Glossary · ID Prefixes · Safety Redlines · FAQ · Further Reading

Differences Between Learn, Guide, and Specs

Section	Question Answered	When to Read
Learn (Here)	Why is it designed this way?	Understanding concepts, threat models, and rationale
Guide	How do I do it?	Hands-on deployment, coding, and configuration
Specs	What is the exact contract?	Implementation, protocol integration, or auditing details

Learn focuses on design concepts without repeating raw specification text. Each concept page links to corresponding Specs for deep dives.

Conventions

• Amounts are represented in atomic integer units (USDC uses 6 decimals: 1 USDC = 1_000_000). No floating-point numbers are used.
• Code samples default to the Python SDK.
• Sample networks default to testnets (such as Arbitrum Sepolia) with test tokens.