Docs/ERC-1066-x402/Core Concepts

Core Concepts

Understand the fundamental concepts behind ERC-1066-x402: status codes, intent validation, policies, and the overall architecture.

Overview

ERC-1066-x402 provides a standardized way to validate and execute intents across multiple blockchain networks. It combines three key components:

Status Codes

Machine-readable codes that indicate validation results

Intent Validation

Pre-flight checks before executing transactions

Policies

Configurable rules for access control

Status Codes

ERC-1066-x402 uses standardized status codes based on the ERC-1066 specification. These codes map to HTTP status codes and provide machine-readable results for AI agents and autonomous systems.

Key Insight

The 0x54 → HTTP 402 mapping enables standardized payment flows. When an agent receives HTTP 402 with X-Payment-Required, it knows to request payment before retrying.

Code	Name	Category	HTTP	Description	Agent Action
`0x01`	SUCCESS	Success	200	Intent validated or executed successfully	Execute immediately
`0x11`	ALLOWED	Success	200	Intent is allowed by policy	Execute immediately
`0x10`	DISALLOWED	Policy	403	Intent explicitly disallowed by policy	Deny, inform user
`0x54`	INSUFFICIENT_FUNDS	Payment	402	Insufficient funds for transaction	Request payment
`0x20`	TOO_EARLY	Timing	202	Intent is valid but too early to execute	Retry later
`0x21`	TOO_LATE	Timing	410	Intent has expired	Reject, expired
`0x22`	NONCE_USED	Replay	409	Nonce already used	Reject, replay detected
`0x50`	TRANSFER_FAILED	Execution	500	Transfer execution failed	Retry or investigate
`0xA0`	INVALID_FORMAT	Validation	400	Invalid intent format	Fix intent structure
`0xA2`	UNSUPPORTED_CHAIN	Network	421	Unsupported chain or network	Use different chain

Showing 10 of 10 status codes

Intent Validation

Intent validation is the process of checking whether an intent can be executed before actually executing it. This pre-flight validation saves gas and provides clear feedback to agents.

Validation Flow

1Agent creates intent with sender, target, data, value, and nonce
2Intent is sent to gateway for validation
3Gateway calls validator contract with intent parameters
4Validator checks policy, balance, timing, and format
5Status code is returned and mapped to HTTP response
6Agent makes decision based on status code

validation_example.py

# Pre-flight validation
result = client.validate_intent(intent, chain_id=133717)

# Agent decision logic
if result.status == "0x01":  # SUCCESS
    client.execute_intent(intent, chain_id=133717)
elif result.status == "0x54":  # INSUFFICIENT_FUNDS
    request_payment()
elif result.status == "0x20":  # TOO_EARLY
    schedule_retry(result.retry_after)

Policies

Policies define the rules for intent validation. They can restrict spending limits, allowed chains, permitted assets, and other parameters.

Spending Limits

Set maximum amounts that can be transferred per transaction or per time period

Allowed Chains

Restrict intents to specific blockchain networks

Permitted Assets

Control which tokens or assets can be used in transactions

Time Windows

Define when intents are valid (validAfter, validBefore)

Architecture

ERC-1066-x402 follows a layered architecture with clear separation between on-chain and off-chain components.

On-Chain Components

•
IntentExecutor - Executes validated intents
•
BaseIntentValidator - Base contract for validation logic
•
PolicyRegistry - Stores and manages policies
•
StatusCodes - Library of standardized status codes

Off-Chain Components

•
Gateway Service - HTTP API for intent validation and execution
•
TypeScript SDK - Client library for TypeScript/JavaScript
•
Python SDK - Client library for Python
•
AI Agents - Autonomous systems using the SDKs

Getting Started

Guides