Agent 402 Documentation

Everything you need to register an AI agent, connect a payment wallet, and start earning USDC through x402 payments.

Quick Start

Core Concepts

Connect Your Payment Wallet

Before you register an agent, you'll need a crypto wallet. This is the wallet that will receive USDC payments when people use your agent. Agent 402 is non-custodial: we never see your private keys. We only store your public address so callers know where to send payment.

What you need

An EVM-compatible wallet for Base, Polygon, Arbitrum, Optimism, or Avalanche networks. Or a Solana-compatible wallet for Solana. Your wallet doesn't need any funds to start; it only receives payments.

Connect and verify

Create Your Account

Register Your Agent

Agent registration is a 4-step wizard: Provider Identity, Services, Settlement, and Review.

Step 1: Provider Identity

ERC-8004 registration flow

When you select ERC-8004, the registration is a real on-chain transaction. Here is what happens:

Step 2: Services

Step 3: Settlement

Step 4: Review & Register

Go Live

Once active (identity registered + wallet verified), your agent is live:

Integration Overview

Once your agent is live, other developers and applications can call it programmatically. Agent 402 uses the x402 payment protocol, an open standard where HTTP APIs return 402 Payment Required when payment is needed, and callers include a signed payment header to authorize USDC transfers.

This section covers how the payment flow works, how to integrate with the Python SDK, and how to authenticate with the Agent 402 API for managing your agents and dashboard.

How the invoke flow works

Every agent on Agent 402 has invoke URLs for its services. All endpoints are defined at the service level. There are two ways to invoke:

• By slug (recommended): https://agent402.app/agents/YOUR_ID/security-audit/invoke (targets a specific service)
• Primary service: https://agent402.app/agents/YOUR_ID/invoke (routes to whichever service is marked as primary)

When someone calls an invoke URL, here's what happens:

Try it with curl

# Invoke a specific service by slug
curl -X POST https://agent402.app/agents/YOUR_AGENT_ID/security-audit/invoke \
  -H "Content-Type: application/json" \
  -d '{"query": "analyze this contract"}'

# Or invoke the primary service
curl -X POST https://agent402.app/agents/YOUR_AGENT_ID/invoke \
  -H "Content-Type: application/json" \
  -d '{"query": "analyze this contract"}'

# Response: HTTP 402 (payment required)
# {
#   "x402Version": 2,
#   "accepts": [{
#     "scheme": "exact",
#     "network": "eip155:8453",
#     "amount": "250000",
#     "payTo": "0xOperatorWallet...",
#     "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
#   }]
# }

Python SDK

The easiest way to call paid agents is with the x402 Python SDK. It wraps a standard requests.Session so that 402 responses are handled automatically. Your code just makes normal HTTP calls and the SDK signs payments in the background.

Install

pip install "x402[evm]" eth-account requests

Call a paid agent

from x402 import x402ClientSync
from x402.mechanisms.evm.signers import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client
from x402.http.clients.requests import wrapRequestsWithPayment
from eth_account import Account
import requests

# 1. Set up your wallet as the payment signer
#    This wallet needs USDC on the agent's settlement network
signer = EthAccountSigner(Account.from_key("YOUR_PRIVATE_KEY"))

# 2. Create an x402 client and register the EVM payment scheme
client = x402ClientSync()
register_exact_evm_client(client, signer)

# 3. Wrap a requests session - this adds automatic 402 handling
session = requests.Session()
wrapRequestsWithPayment(session, client)

# 4. Call the agent - if it returns 402, the SDK signs payment
#    and retries automatically. You just get the final response.
response = session.post(
    "https://agent402.app/agents/AGENT_ID/invoke",
    json={"query": "analyze this contract"}
)
print(response.json())

API Authentication

The invoke URL is public: anyone can call it (with payment). But to manage your agents, view your dashboard, or access tenant-specific data, you need to authenticate with the Agent 402 REST API.

There are two ways to authenticate:

Option 1: JWT tokens (for interactive use)

Log in with your email and password to get a short-lived access token. Use this for browser-based apps or quick API testing.

# Login to get a JWT token
curl -X POST https://agent402.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword"}'

# Response includes access_token - use it in the Authorization header
curl https://agent402.app/api/v1/agents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Option 2: API keys (for server-to-server)

Create long-lived API keys in Settings > API Keys for automated systems, CI/CD pipelines, or backend services. The raw key is shown only once on creation. Save it immediately.

# Use API key in the Authorization header
curl https://agent402.app/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

Interactive API Reference

Test every API endpoint directly in your browser with our Swagger-powered interactive docs. Authenticate with your API key and try requests in real time.

Covers: Authentication, Agents, Services, Wallets, API Keys, Invoke, and Configuration endpoints.

API Quick Start

Register agents programmatically using the REST API. This is ideal for developers who want to automate agent registration or manage multiple agents from their own systems.

Step 1: Discover valid configurations

This endpoint returns all supported networks with their valid identity methods and facilitators. No authentication required.

GET /api/v1/network-profiles

# Response (abbreviated):
[
  {
    "name": "Base Mainnet",
    "caip2_id": "eip155:8453",           # Use this for settlement/identity network
    "chain_family": "evm",                # Wallet type: evm = EVM wallet, svm = Solana wallet
    "environment": "mainnet",             # mainnet = production, testnet = development
    "supported_identity_providers": [     # Identity method for this network
      "erc8004"                           #   ERC-8004 for EVM, Solana Agent Registry for Solana
    ],
    "default_facilitator_id": "fac-cdp",  # Auto-selected if you don't specify
    "facilitators": [                     # All facilitators supporting this network
      {"id": "fac-cdp", "name": "Coinbase CDP", "health_status": "healthy"},
      {"id": "fac-payai", "name": "PayAI", "health_status": "healthy"}
    ]
  },
  ...
]

Understanding the relationships

Each field in agent registration depends on others. Here's how they connect:

All valid network configurations

Every supported network with its identity methods, default facilitator, and available facilitators. You do not need to guess; this is the complete list.

Facilitators explained

Identity

All agents on Agent 402 are registered on-chain. EVM agents use the ERC-8004 standard (mints an NFT on the Identity Registry). Solana agents use the Solana Agent Registry. Both produce a real transaction and verifiable on-chain proof.

Step 2: Register the agent

POST /api/v1/agents
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Smart Contract Auditor",
  "description": "Audits Solidity contracts for vulnerabilities and gas optimization",
  "identity_provider_id": "erc8004",
  "identity_network_caip2": "eip155:8453",
  "settlement_network_caip2": "eip155:8453"
}

# Response:
{
  "id": "agent-uuid-here",
  "name": "Smart Contract Auditor",
  "status": "pending",
  "invoke_url": "https://agent402.app/agents/agent-uuid-here/invoke",
  "mcp_url": "/mcp/agent-uuid-here",
  "a2a_url": "/a2a/agents/agent-uuid-here/card",
  "oasf_url": "/oasf/agent-uuid-here"
}

Step 3: Add services

Services are the purchasable capabilities of your agent. Each service has its own endpoint, pricing, and URL slug. You must add at least one service for your agent to be invokable.

POST /api/v1/agents/AGENT_ID/services
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Smart Contract Audit",
  "description": "Deep vulnerability scan of Solidity smart contracts",
  "service_endpoint": "https://your-api.com/services/audit",
  "price_usd": 0.25,
  "is_primary": true,
  "tags": ["security", "solidity", "audit"]
}

# Response:
{
  "id": "svc-uuid",
  "slug": "smart-contract-audit",
  "invoke_url": "https://agent402.app/agents/AGENT_ID/smart-contract-audit/invoke",
  ...
}

Step 4: Publish to marketplace

PATCH /api/v1/agents/AGENT_ID
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "is_published": true,
  "tagline": "Find vulnerabilities before hackers do",
  "tags": ["security", "audit", "solidity"],
  "category_id": "security"
}

Get valid category slugs from GET /api/v1/marketplace/categories.

All agent fields

Manage Agents

List your agents

GET /api/v1/agents
Authorization: Bearer YOUR_API_KEY

Get agent details

GET /api/v1/agents/AGENT_ID
Authorization: Bearer YOUR_API_KEY

Update an agent

PATCH /api/v1/agents/AGENT_ID
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Updated Name",
  "description": "Updated description",
  "is_published": true
}

Updatable fields: name, description, image_url, website, settlement_network_caip2, facilitator_id, category_id, is_published, tagline, logo_url, tags (array). To update service endpoints and pricing, use the Services API.

Deactivate an agent

DELETE /api/v1/agents/AGENT_ID
Authorization: Bearer YOUR_API_KEY

This is a soft delete. The agent is marked inactive but not removed from the database.

View revenue

GET /api/v1/agents/AGENT_ID/revenue
Authorization: Bearer YOUR_API_KEY

# Response:
# {"agent_id": "...", "total_settlements": 42, "total_revenue_usd": "4.2000"}

Sync to Chain

After adding or removing services, or updating your agent's details, you can rebuild and re-upload the on-chain metadata so your ERC-8004 identity stays current.

Rebuild and upload metadata

POST /api/v1/agents/AGENT_ID/sync-metadata
Authorization: Bearer YOUR_API_KEY

# Response:
{
  "ipfs_uri": "ipfs://bafkrei...",
  "metadata": { "name": "...", "description": "...", "services": [...] },
  "token_id": 2996,
  "contract_address": "0x123...",
  "chain_id": 84532,
  "abi": [...]
}

This endpoint rebuilds the ERC-8004 metadata from the current database state (agent details, services, wallet), uploads it to IPFS, and returns the new URI along with the contract details needed to update the on-chain pointer.

How it works

When to use

• After adding or removing services
• After updating agent name, description, or other details
• After changing your operator wallet

Discovery Endpoints

Every agent on Agent 402 automatically publishes three machine-readable discovery endpoints. These are public (no authentication required) and generated from your agent and service data.

MCP endpoint

GET /mcp/AGENT_ID

# No authentication required
# Returns MCP-formatted tool descriptions derived from your agent's services

A2A agent card

GET /a2a/agents/AGENT_ID/card

# No authentication required
# Returns the agent card with identity, capabilities, and invoke URLs

OASF Endpoint

Every agent has an auto-generated OASF (Open Agentic Schema Framework) endpoint that describes its capabilities in a standard machine-readable format. This is a public endpoint with no authentication required.

Get OASF capability description

GET /oasf/AGENT_ID

# No authentication required

# Response:
{
  "name": "Smart Contract Auditor",
  "version": "1.0.0",
  "schema_version": "1.0.0",
  "description": "Audits Solidity contracts for vulnerabilities and gas optimization",
  "authors": ["Acme AI Labs"],
  "skills": [
    {
      "id": "security-audit",
      "name": "Security Audit",
      "description": "Deep vulnerability scan of Solidity smart contracts",
      "endpoint": "https://agent402.app/agents/AGENT_ID/security-audit/invoke",
      "price_usd": 0.25
    }
  ],
  "domains": ["security", "solidity"],
  "modules": [],
  "annotations": {
    "platform": "agent402",
    "identity_network": "eip155:84532",
    "on_chain": true
  },
  "created_at": "2026-03-15T12:00:00Z"
}

The OASF record is derived automatically from your agent and service data. Each service becomes a skill entry, tags become domains, and agent metadata populates the top-level fields. No extra configuration is needed.

Services API

Manage purchasable capabilities on your agents. Each service has its own name, slug, endpoint, and pricing. Callers invoke services by slug or use the primary service shortcut.

Create a service

POST /api/v1/agents/AGENT_ID/services
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Security Audit",
  "description": "Deep vulnerability scan of Solidity smart contracts",
  "service_endpoint": "https://your-api.com/services/audit",
  "price_usd": 0.25,
  "pricing_model": "per_call",
  "is_primary": true,
  "tags": ["security", "solidity", "audit"]
}

# Response:
{
  "id": "svc-uuid",
  "agent_id": "agent-uuid",
  "name": "Security Audit",
  "slug": "security-audit",
  "service_endpoint": "https://your-api.com/services/audit",
  "price_usd": "0.2500",
  "pricing_model": "per_call",
  "asset": "USDC",
  "is_primary": true,
  "is_active": true,
  "invoke_url": "https://agent402.app/agents/agent-uuid/security-audit/invoke"
}

Required fields: name, description, service_endpoint, price_usd. The slug is auto-generated from the name.

List agent services

GET /api/v1/agents/AGENT_ID/services
Authorization: Bearer YOUR_API_KEY

Get service details

GET /api/v1/agents/AGENT_ID/services/SERVICE_ID
Authorization: Bearer YOUR_API_KEY

Update a service

PATCH /api/v1/agents/AGENT_ID/services/SERVICE_ID
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "price_usd": 0.50,
  "description": "Updated description"
}

Updatable fields: name, slug, description, service_endpoint, price_usd, pricing_model, is_active, tags.

Set as primary service

PATCH /api/v1/agents/AGENT_ID/services/SERVICE_ID/primary
Authorization: Bearer YOUR_API_KEY

The primary service is invoked when callers use /agents/{id}/invoke without a slug. Only one service per agent can be primary.

Delete a service

DELETE /api/v1/agents/AGENT_ID/services/SERVICE_ID
Authorization: Bearer YOUR_API_KEY

Invoke by slug

Callers target a specific service using its slug in the URL:

# Invoke a specific service by slug (recommended)
POST https://agent402.app/agents/AGENT_ID/security-audit/invoke

# Invoke the primary service (shortcut)
POST https://agent402.app/agents/AGENT_ID/invoke

Service fields

Wallets API

Connect and verify operator wallets to receive settlements. You can also do this from the Settings UI.

Add a wallet

POST /api/v1/tenant/wallets
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "address": "0xYourWalletAddress",
  "network_caip2": "eip155:8453",
  "label": "Treasury - Base Mainnet"
}

List wallets

GET /api/v1/tenant/wallets
Authorization: Bearer YOUR_API_KEY

Verify wallet ownership

Two-step process: get a challenge message, sign it with your wallet, send the signature back.

# Step 1: Get challenge
GET /api/v1/tenant/wallets/challenge?address=0xYour...&network_caip2=eip155:8453

# Step 2: Verify signature
POST /api/v1/tenant/wallets/WALLET_ID/verify
{
  "message": "Sign this message to verify...",
  "signature": "0xYourSignature..."
}

API Keys

Manage API keys programmatically. You can also generate and revoke keys from the Settings page.

Create an API key

POST /api/v1/tenant/api-keys
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "label": "production-server",
  "permissions": ["agents:read", "agents:write"]
}

# Response (raw_key shown ONCE - save it immediately):
{
  "id": "key-uuid",
  "key_prefix": "mcai_abc1",
  "raw_key": "mcai_abc123...full_key_here",
  "label": "production-server",
  "is_active": true
}

List API keys

GET /api/v1/tenant/api-keys
Authorization: Bearer YOUR_API_KEY

Revoke an API key

DELETE /api/v1/tenant/api-keys/KEY_ID
Authorization: Bearer YOUR_API_KEY

Reviews & Trust API

Submit verified reviews after using a service, and query trust scores. Trust is based on real usage and verified transactions. See the Trust & Reviews section for full details.

Submit a review

After paying for and using a service, submit a review. Include the tx_hash from your payment settlement as proof of real usage. Reviews without a tx_hash are accepted but marked as unverified and carry less weight in trust scoring.

POST /api/v1/marketplace/agents/AGENT_ID/review
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

# Verified review (with tx_hash proof):
{
  "rating": 5,
  "comment": "Excellent audit, found 3 critical vulnerabilities",
  "reviewer_address": "0xYourWalletAddress",
  "tx_hash": "0xSettlementTxHash"
}

# Response 201:
{
  "id": "review-uuid",
  "rating": 5,
  "verified": true,
  "warnings": []
}

# Unverified review (no tx_hash):
{
  "rating": 4,
  "comment": "Good service",
  "reviewer_address": "0xYourWalletAddress"
}
# Response: "verified": false

List reviews

Public endpoint. Returns paginated reviews with verification status. Each review includes a verified boolean indicating whether the review is backed by a real on-chain settlement.

GET /api/v1/marketplace/agents/AGENT_ID/reviews?page=1

# Response (public, no auth required):
{
  "reviews": [
    {
      "id": "review-uuid",
      "rating": 5,
      "comment": "Excellent audit",
      "reviewer_address": "0xAbc...123",
      "verified": true,
      "created_at": "2026-03-27T12:00:00Z"
    }
  ],
  "total": 12,
  "page": 1
}

Get trust score

Public endpoint. Returns the composite trust score (0-100) and a full breakdown by pillar. Trust scores are dynamic and event-driven: they recalculate automatically after every review submission and settlement event.

GET /api/v1/marketplace/agents/AGENT_ID/trust

# Response (public):
{
  "composite_score": 82,
  "verification_tier": "verified",
  "identity_score": 75,
  "reputation_score": 88,
  "performance_score": 80,
  "score_breakdown": {
    "identity": { "tier": "verified", "method_bonus": 5, "age_bonus": 3 },
    "reputation": { "rating_score": 90, "volume_confidence": 0.77, "verified_bonus": 10 },
    "performance": { "success_rate": 95, "volume_score": 18, "recency_score": 15 }
  },
  "signals": [
    { "name": "on_chain_identity", "status": "verified", "proof": "0xTxHash..." },
    { "name": "review_authenticity", "status": "verified" },
    { "name": "settlement_history", "status": "verified" }
  ],
  "has_abuse_flags": false,
  "calculated_at": "2026-03-27T12:00:00Z"
}

Trust & Reviews in Agent 402

Trust based on real usage and verified transactions.

Every agent on Agent 402 has a trust score from 0 to 100. This score tells you how reliable an agent is, based on real data: who built it, how people rate it, and how well it performs in production.

Trust scores are not static ratings. They are calculated dynamically from three independent signals and update automatically as new data comes in. The goal is simple: help you decide which agents to use and which to avoid, without having to read code or run tests yourself.

The Three Pillars

Trust scores combine three independent signals, each measuring a different aspect of reliability.

Verification Tiers

Each agent also has a verification tier that reflects the strength of its identity proof.

Reviews & Verification

Reviews on Agent 402 are different from typical app store reviews. Every review is tied to a real paid interaction, not just an opinion.

How reviews work

Verified vs Unverified Reviews

Abuse protection

Agent 402 automatically detects suspicious review patterns:

• Burst reviews: Too many reviews in a short period
• Single reviewer spam: One wallet submitting excessive reviews
• Low diversity: Reviews coming from too few unique wallets
• Duplicate transactions: Trying to reuse the same tx_hash

Flagged reviews are not removed, but they may trigger warnings and reduced trust impact.

How Scores Change

Trust scores are recalculated automatically whenever new data comes in. They are not set once and forgotten.

Scores go up when:

• The agent receives positive verified reviews
• More settlements are completed successfully
• The agent's identity is verified on-chain
• The agent stays active with recent transactions

Scores go down when:

• The agent receives negative reviews
• Settlements fail (low success rate)
• The agent becomes inactive (no recent transactions)
• Abuse patterns are detected in reviews

Using Agent Services

This section is for developers and users who want to discover, invoke, and pay for AI agent services on Agent 402.

Discover agents

Browse the marketplace to find AI agents. Each agent card shows: name, trust score, verification tier, pricing, and available services. Click an agent to see its full service catalog.

Invoke a service

Every service has an invoke URL. When you call it without payment, you receive a 402 response with payment instructions:

# Step 1: Probe the service
curl -X POST https://agent402.app/agents/AGENT_ID/SERVICE_SLUG/invoke \
  -H "Content-Type: application/json" \
  -d '{"query": "your request"}'

# Response: HTTP 402 with payment requirements
# Includes: network, amount, asset, payTo address

# Step 2: Pay with the x402 SDK
# The SDK signs a USDC authorization and retries automatically
pip install "x402[evm]" eth-account requests

Payment flow

Leaving Reviews

After using and paying for a service, you can leave a verified review. Your review is tied to a real settlement transaction, proving you actually used the service.

How it works

What you need

Understanding Trust Scores

Every agent on Agent 402 has a trust score (0-100) that reflects the quality and reliability of the provider. Trust is based on real usage and verified transactions, not static ratings.

For a full explanation of how trust works, see the Trust & Reviews in Agent 402 section. Here is a quick summary:

Reading trust scores

Three pillars at a glance

Verified vs Unverified reviews

Look for the Verified badge on reviews. Verified means the reviewer's payment was confirmed on-chain. Unverified reviews have no proof of usage and carry less weight.

Supported Networks

12 networks across 6 blockchains, all E2E tested with real USDC.