Docs/ERC-1066-x402

ERC-1066-x402

A set of Ethereum-compatible smart contracts that standardize status codes, policy checks, and intent validation for Web3 transactions. Integrates with HTTP/x402 gateway and agent layer to provide machine-readable status codes for autonomous decision-making.

Activev2.0.0

What is ERC-1066-x402?

ERC-1066-x402 combines the ERC-1066 status code standard with the x402 payment protocol, creating a unified system for intent validation and payment handling in Web3 applications. It enables AI agents and autonomous systems to make decisions based on standardized, machine-readable status codes.

Standardized Semantics

Instead of parsing unstructured error messages, agents can branch directly on status codes like 0x54 (INSUFFICIENT_FUNDS) or 0x01 (SUCCESS).

Key Features

Standardized Status Codes

ERC-1066 status codes for intents, account abstraction, and payments

Pre-flight Validation

Check if intent will succeed before spending gas

Policy-Based Access Control

Limits, permissions, chains, and asset controls

Multi-Chain Support

EVM, Solana, and Sui support with network-agnostic gateway

Why ERC-1066-x402?

Without ERC-1066-x402

Each project implements custom error strings and status handling
AI agents must parse unstructured error messages
No standardized way to handle payment requirements (x402)
Gas waste from verbose error strings
Difficult to monitor and aggregate across protocols

With ERC-1066-x402

Machine-readable status codes that agents can branch on directly
Standardized x402 integration with HTTP 402 mapping
Gas-efficient single-byte status codes vs. string errors
Cross-protocol monitoring and aggregation
Pre-flight validation before spending gas

Architecture

ERC-1066-x402 consists of two main layers: an on-chain layer with smart contracts for validation and execution, and an off-chain layer with gateway services and SDKs for integration.

On-Chain Layer

• IntentExecutor
• BaseIntentValidator
• PolicyRegistry
• StatusCodes Library

Off-Chain Layer

• Gateway Service
• TypeScript SDK
• Python SDK
• AI Agents/Wallets

Quick Example

Here's how an AI agent uses ERC-1066-x402 to handle payment-required scenarios:

agent_example.py

from erc1066_x402 import ERC1066Client, Intent

client = ERC1066Client("https://gateway.example.com")

intent = Intent(
    sender="0x...",
    target="0x...",
    data="0x...",
    value="1000000000000000",  # 0.001 ETH
    nonce="1",
    policyId="0x..."
)

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

if result.status == "0x54":  # INSUFFICIENT_FUNDS
    # Gateway returns HTTP 402 with X-Payment-Required header
    # Agent requests payment from user
    payment_url = f"{gateway_url}/pay?intent={intent_hash}"
    request_payment(payment_url)
elif result.status == "0x01":  # SUCCESS
    # Execute immediately
    client.execute_intent(intent, chain_id=133717)