Docs/ERC-1066-x402/API Reference/Gateway API

Gateway API

REST API endpoints for intent validation and execution. The gateway maps onchain status codes to HTTP responses.

Overview

The gateway provides HTTP endpoints that accept intent requests, validate them on-chain, and return standardized HTTP responses with status codes.

Base URL

All endpoints are relative to the gateway base URL (e.g., https://gateway.example.com)

POST /intents/validate

Validates an intent without executing it. Returns HTTP status codes based on validation result.

Request

Request Body

{
  "sender": "0x...",
  "target": "0x...",
  "data": "0x...",
  "value": "0",
  "nonce": "0",
  "validAfter": "0",
  "validBefore": "0",
  "policyId": "0x..."
}

Response

200 OKIntent is valid

Returns when validation succeeds

403 ForbiddenIntent is disallowed

Returns when policy check fails

402 Payment RequiredInsufficient funds

Returns when payment is required (x402 flow)

POST /intents/execute

Executes a validated intent on-chain.

Request

Same request format as validate endpoint

Response

200 OKExecution successful

Returns when execution succeeds

402 Payment RequiredPayment required

Returns when payment is required (x402 flow)

Headers

All responses include these custom headers for on-chain context:

X-ERC1066-Status

The raw hex status code (e.g., 0x11)

X-Intent-Hash

The Keccak256 hash of the intent payload

X-Chain-Type

The runtime environment (evm, solana, sui)

X-Chain-Id

The unique identifier for the network

X-Payment-Required

Set to "true" when payment is required

HTTP Status Codes

Status code mapping from ERC-1066 status codes to HTTP responses:

HTTP Code	ERC-1066 Status	Meaning
`200`	`0x01, 0x11`	Intent validated or executed successfully
`202`	`0x20`	Intent is pending (TOO_EARLY)
`402`	`0x54`	Payment required (INSUFFICIENT_FUNDS)
`403`	`0x10`	Intent explicitly disallowed (DISALLOWED)
`410`	`0x21`	Intent has expired (TOO_LATE)
`421`	`0xA2`	Unsupported chain or network

Smart Contracts

TypeScript SDK