Docs/ERC-1066-x402/Guides/Agent Integration

Agent Integration

Integrate ERC-1066-x402 with AI agents and autonomous systems using the TypeScript or Python SDKs.

Overview

Agents can integrate with ERC-1066-x402 using the provided SDKs. The SDKs handle HTTP communication with the gateway and provide helper methods for status code mapping and decision-making.

SDK Benefits

The SDKs abstract away HTTP details and provide type-safe interfaces for intent validation and execution. They also include helper methods for mapping status codes to agent actions.

TypeScript SDK

Install and use the TypeScript SDK:

npm install @hyperkit/erc1066-x402-sdk

agent.ts

import { ERC1066Client } from '@hyperkit/erc1066-x402-sdk';

// Initialize client
const client = new ERC1066Client('https://gateway.example.com');

// Create intent
const intent = {
  sender: '0x...',
  target: '0x...',
  data: '0x...',
  value: '0',
  nonce: '0',
  validAfter: '0',
  validBefore: '0',
  policyId: '0x...'
};

// Validate intent
const result = await client.validateIntent(intent, 1);

// Map status to action
const action = client.mapStatusToAction(result.status);

// Execute based on action
if (action === 'execute') {
  await client.executeIntent(intent, 1);
} else if (action === 'request_payment') {
  requestPayment(result.paymentUrl);
}

Python SDK

Install and use the Python SDK:

Terminal

# Install Python SDK
pip install hyperkitlabs-erc1066-x402

agent.py

from erc1066_x402 import ERC1066Client

# Initialize client
client = ERC1066Client('https://gateway.example.com')

# Create intent
intent = {
    'sender': '0x...',
    'target': '0x...',
    'data': '0x...',
    'value': '0',
    'nonce': '0',
    'validAfter': '0',
    'validBefore': '0',
    'policyId': '0x...'
}

# Validate intent
result = client.validate_intent(intent, 1)

# Map status to action
action = client.map_status_to_action(result['status'])

# Execute based on action
if action == 'execute':
    client.execute_intent(intent, 1)
elif action == 'request_payment':
    request_payment(result['payment_url'])

Status Code Mapping

Map status codes to agent actions:

Status Code	Action	Description
`0x01`	Execute immediately	SUCCESS
`0x20`	Retry later	TOO_EARLY
`0x54`	Request payment	INSUFFICIENT_FUNDS
`0x10`	Deny and inform user	DISALLOWED

Best Practices

1. Always Validate Before Executing

Use validateIntent before executeIntent to avoid wasting gas on failed transactions.

2. Handle Payment Required Scenarios

When receiving status 0x54 (INSUFFICIENT_FUNDS), request payment from the user before retrying.

3. Implement Retry Logic

For status 0x20 (TOO_EARLY), implement exponential backoff retry logic.

4. Log Status Codes

Log all status codes for monitoring and debugging purposes.

Gateway Setup

Multi-Chain Deployment