Docs/ERC-1066-x402/Guides/Gateway Setup

Gateway Setup

The gateway service provides HTTP endpoints for intent validation and execution, mapping onchain status codes to HTTP responses.

Overview

The gateway acts as a bridge between AI agents and blockchain networks. It receives HTTP requests, validates intents on-chain, and returns standardized HTTP responses with status codes.

Gateway Flow

1Agent sends intent validation request to gateway
2Gateway calls validator contract on-chain
3Validator returns status code (e.g., 0x01 for SUCCESS)
4Gateway maps status code to HTTP response
5Agent receives HTTP response with status code

Installation

Navigate to the gateway package and install dependencies:

Terminal

# Navigate to gateway directory
cd packages/gateway

# Install dependencies
npm install

# Copy environment template
cp env.template .env

Configuration

Configure the gateway with your deployed contract addresses and RPC endpoints:

.env

# Contract addresses (JSON format)
EXECUTOR_ADDRESSES={"{"133717":"0x...","59902":"0x..."}"}
VALIDATOR_ADDRESSES={"{"133717":"0x...","59902":"0x..."}"}
REGISTRY_ADDRESSES={"{"133717":"0x...","59902":"0x..."}"}

# RPC URLs (optional - gateway uses Chainlist by default)
RPC_URLS={"{"133717":"https://...","59902":"https://..."}"}

# Server configuration
PORT=3001
NODE_ENV=development

Network-Agnostic Design

The gateway automatically discovers RPC endpoints via Chainlist, so you can add new networks without code changes. See the Multi-Chain Guide for details.

API Endpoints

POST /intents/validate

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

Request

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

Status 200: Intent is valid

Status 403: Intent is disallowed

Status 402: Insufficient funds (x402 payment required)

Other status codes: Based on validation result

POST /intents/execute

Executes a validated intent on-chain.

Request

# Same request format as validate endpoint
{
  "sender": "0x...",
  "target": "0x...",
  "data": "0x...",
  "value": "0",
  "nonce": "0",
  "policyId": "0x..."
}

Headers

X-Chain-Id - Chain ID for the request
X-Status-Code - Onchain status code (bytes1)
X-Payment-Required - Set to "true" when payment is required

Testing

Start the gateway and test the endpoints:

Terminal

# Start gateway
npm run dev

# Expected output:
Server listening on http://0.0.0.0:3001

# Test health check
curl http://localhost:3001/health

# Test intent validation
curl -X POST http://localhost:3001/intents/validate \
  -H "Content-Type: application/json" \
  -H "X-Chain-Id: 133717" \
  -d '{...}'

Guides

Agent Integration