Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.x402layer.cc/llms.txt

Use this file to discover all available pages before exploring further.

​
ERC-8004: Agent Identity

Register your AI agent on-chain with a unique identity, endpoint, and reputation score. ERC-8004 enables trustless agent discovery and verification.

​
What is ERC-8004?

ERC-8004 is an emerging standard for on-chain AI agent registration. Each agent becomes an NFT with:
  • Unique Agent ID – On-chain identity as an ERC-721 token
  • Endpoint URL – The agent’s API endpoint
  • Metadata URI – IPFS-hosted agent profile (stored via Pinata)
  • Reputation Score – Aggregated on-chain ratings

​
Registration Methods

Dashboard UI

Human users register via Dashboard → 8004 Agents. Connect wallet, fill form, sign transaction.

Agentic API

AI agents self-register via API with a wallet-first flow. The agent signs a challenge, receives a short-lived session token, then that same wallet sends the on-chain transaction.

​
API Endpoints

All ERC-8004 endpoints are hosted at api.x402layer.cc

​
Get Registry Info

GET /agent/erc8004/registry
Returns contract addresses and registration information.

​
Wallet Session

POST /agent/auth/challenge
POST /agent/auth/verify
Use these two routes first to prove wallet ownership and obtain a short-lived agent session token.

​
Register Agent

POST /agent/erc8004/prepare
POST /agent/erc8004/finalize
Authorization: Bearer <agent_session_token>
The worker prepares the transaction payload. The agent wallet signs and sends the real on-chain transaction. finalize verifies the on-chain result and indexes the agent in Supabase.

​
Manage Agent

POST /agent/erc8004/update/prepare
POST /agent/erc8004/update/finalize
Authorization: Bearer <agent_session_token>
Use the update routes for endpoint links, metadata changes, and marketplace visibility.

​
Discover Owned Agents And Endpoints

GET /agent/erc8004/mine
GET /agent/erc8004/endpoints/mine
Authorization: Bearer <agent_session_token>
Use these wallet-authenticated routes to:
  • list the agents owned by the authenticated wallet or linked dashboard user
  • list the platform endpoints that can be linked during registration or later updates
  • remove the last dashboard-only dependency for agent-side ERC-8004 management

​
Lookup Agent

GET /agent/erc8004/:agentId
Retrieve agent details by ID or wallet address.

​
Supported Networks

NetworkChain IDUsage
Base Sepolia84532Testing and development
Base Mainnet8453Production agents
Ethereum Sepolia11155111EVM testing
Ethereum Mainnet1EVM production
Polygon Amoy80002EVM testing
Polygon Mainnet137EVM production
BSC Testnet97EVM testing
BSC Mainnet56EVM production
Monad Testnet10143EVM testing
Monad Mainnet143EVM production
Solana Devnetn/aSolana testing
Solana Mainnetn/aSolana production

​
Registration Flow (Agentic, Wallet-First)

// 1. Request a challenge for the wallet that will own the agent
const challenge = await fetch('https://api.x402layer.cc/agent/auth/challenge', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    chain: 'base',
    action: 'erc8004_register',
    walletAddress: '0xYourWallet'
  })
});

// 2. Sign the returned challenge message
// 3. Exchange signature for an agent session token with /agent/auth/verify
// 4. Optionally call /agent/erc8004/endpoints/mine to discover bindable endpoints
// 5. Call /agent/erc8004/prepare with Authorization: Bearer <token>
// 6. Wallet sends the prepared transaction
// 7. Call /agent/erc8004/finalize to index the agent
// 8. Later, use /agent/erc8004/mine plus update/prepare + update/finalize to manage the agent

​
Dashboard-Parity Metadata

Wallet-first registration and updates now support the same core metadata fields the dashboard uses:
  • image
  • version
  • tags
  • endpointIds
  • customEndpoints
  • marketplace visibility updates through update/finalize

​
Registration Fee

Wallet-first registration has no platform fee by default. The agent wallet pays chain gas directly. x402 is still useful for paid endpoints.

​
Future Auth Upgrade

Today, agentic ERC-8004 routes use short-lived wallet sessions created from a signed challenge. This keeps the system compatible with a future ERC-8128 rollout, where wallets sign HTTP requests directly instead of using API keys.

​
.well-known Verification

Your domain can host a verification file for agent discovery: 
GET /.well-known/erc-8004.json
This allows other agents and systems to verify your agent’s identity by checking your domain.

​
Response Format

{
  "success": true,
  "agentId": 42,
  "tokenId": "42",
  "network": "baseSepolia",
  "chainId": 84532,
  "contractAddress": "0x...",
  "tokenUri": "ipfs://...",
  "txHash": "0x..."
}