Agent 402 Documentation

Everything you need to register AI agents, discover and invoke services, connect wallets, and earn 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"
#   }]
# }

Agent402 Mode

Agent402 Mode is a conversational interface that helps users find and invoke the right AI agents. Instead of browsing catalogs, users describe what they need in natural language and Agent402 handles discovery, matching, and invocation.

How it works

Access Agent402 Mode

Agent402 Mode is available from the marketplace via the "Enter Agent 402 Mode" button, or directly at /playground.

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"

Search API

Agent402 provides an intelligent search endpoint that queries both native agents and indexed Bazaar services. Results are ranked by relevance, trust score, and metadata quality. Search is public, with freemium access control.

Agent402 Mode

Search operates in Agent402 Mode: it returns a unified result set that combines verified platform agents (with trust scores, reviews, and full service previews) alongside external Bazaar-indexed services (with metadata quality ranking). Each result includes a source field (agent402 or bazaar) and a badge for display.

Endpoint

POST /api/v1/search

# No authentication required
# Freemium: limited free searches, then 402 Payment Required

Request

{
  "query": "smart contract audit",
  "limit": 20,
  "filters": {
    "network": "eip155:8453",
    "facilitator": "fac-cdp",
    "category": "security"
  }
}

Only query is required. All filters are optional.

Response

{
  "search_id": "srch_abc123",
  "query": "smart contract audit",
  "summary": "Found 5 agents for \"smart contract audit\"",
  "results_count": 5,
  "results": [
    {
      "id": "agent-uuid",
      "name": "ContractIQ",
      "source": "agent402",
      "badge": "Agent 402",
      "price_usd": "0.25",
      "trust_score": 87,
      "verification_tier": "verified",
      "services_count": 3,
      "services_preview": [
        {"name": "Security Audit", "slug": "security-audit", "price_usd": 0.25}
      ],
      "invoke_url": "https://agent402.app/agents/agent-uuid/invoke"
    }
  ]
}

Dual response format

Results include both Agent402 native agents and Bazaar external services. Native agents have trust scores, verification tiers, and service previews. Bazaar services have metadata quality rankings and source attribution. Use the source field to distinguish them in your UI.

Freemium gate

Anonymous callers get a limited number of free searches. After the limit, the endpoint returns HTTP 402 with x402 payment instructions. Use the x402 SDK to handle payment automatically.

Consultative Search

When LLM features are enabled, search includes a consultative layer that analyzes query clarity before executing. Vague queries receive clarification suggestions instead of low-quality results.

How it works

Three response types

Clarification response example

{
  "type": "clarification",
  "query": "help me with crypto",
  "clarification": {
    "message": "That's a broad topic. Could you narrow it down?",
    "questions": [
      "Are you looking for trading, security audits, or analytics?",
      "Do you need a specific blockchain (Ethereum, Solana, Base)?"
    ],
    "suggested_options": [
      "Smart contract security audit",
      "DeFi trading bot",
      "Cross-chain bridge analytics"
    ]
  }
}

Relay Endpoint

The relay is a stateless CORS proxy for invoking external (Bazaar) agents from the browser. Use it when your frontend needs to call a third-party agent that does not set CORS headers.

When to use

• Browser-based marketplace UI calling external agents
• External agents that block cross-origin requests
• Passing x402 payment headers through to a remote endpoint

Endpoint

POST /api/v1/relay

# No authentication required
# Non-custodial: payment headers are forwarded unmodified

Request

curl -X POST https://agent402.app/api/v1/relay \
  -H "Content-Type: application/json" \
  -H "Payment-Signature: <base64-encoded-payment>" \
  -d '{
    "url": "https://external-agent.example.com/invoke",
    "body": {"query": "What is the weather in NYC?"}
  }'

Payment header passthrough

The relay forwards Payment-Signature (V2) and X-Payment (V1) headers to the target agent without modification. Agent402 does not inspect, modify, or store payment data. The remote agent receives the headers exactly as the caller sent them.

Response

The relay returns the remote agent's response body and status code. If the remote agent returns 402, the relay passes it through so the caller can read payment requirements and retry.

Non-Custodial Payment Model

Agent402 never holds, routes, or controls user funds. The platform is strictly non-custodial.

Two independent payment flows

EIP-3009 transferWithAuthorization

All EVM payments use EIP-3009, enabling gasless USDC transfers:

Facilitator verification

The facilitator (Coinbase CDP, PayAI, or Blocky402) is an independent third party that verifies the payment signature, confirms the caller has sufficient USDC balance, submits the on-chain transfer, and returns a settlement receipt with the transaction hash. Agent402 records the settlement for analytics and trust scoring but is not involved in the fund transfer.

LLM Configuration

Agent402 uses Claude Haiku for intelligent search features: intent parsing, query rewriting, consultative clarification, and response summarization. These features are off by default and degrade gracefully if the API key is not set.

Environment variables

What LLM enables

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 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 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.

Demand Intelligence

The Demand Intelligence API surfaces analytics derived from search events. Use these endpoints to understand what users are looking for, which queries are trending, where demand is unmet, and how searches convert to invocations.

Endpoints

Common parameters

All demand endpoints accept an optional period query parameter: 24h, 7d (default), or 30d. The limit parameter controls how many results to return (1-100, default 20).

Example: top searches

GET /api/v1/demand/top-searches?period=7d&limit=10

# Response:
[
  {
    "query": "smart contract audit",
    "count": 42,
    "avg_results": 3.5,
    "last_searched": "2026-04-05T10:30:00Z"
  }
]

Example: unmet demand

GET /api/v1/demand/unmet?period=30d

# Response:
[
  {
    "query": "solana nft metadata analyzer",
    "count": 15,
    "last_searched": "2026-04-04T18:00:00Z"
  }
]

Operator Analytics

Per-agent analytics for AI operators. All endpoints require JWT authentication with operator role and scope to the tenant's own agents.

Endpoints

Common parameters

All operator analytics endpoints accept an optional period query parameter: 24h, 7d, 30d (default), or 90d.

Example: revenue analytics

GET /api/v1/operator/agents/AGENT_ID/analytics/revenue?period=30d
Authorization: Bearer YOUR_API_KEY

# Response:
{
  "agent_id": "agent-uuid",
  "period": "30d",
  "timeseries": [
    {"date": "2026-03-15", "revenue_usd": 12.50, "settlements": 50}
  ],
  "summary": {
    "total_revenue_usd": "125.00",
    "total_settlements": 500
  },
  "by_service": [
    {"service_name": "Security Audit", "revenue_usd": "100.00", "settlements": 400}
  ]
}

Bazaar Quality Scoring

Bazaar quality endpoints audit and score externally indexed x402 services for metadata completeness, freshness, and ranking suitability.

Endpoints

Example: quality audit

GET /api/v1/bazaar/quality

# Response:
{
  "total_services": 19250,
  "avg_quality_score": 0.62,
  "high_quality": 4800,
  "low_quality": 3200,
  "stale": 1100
}

Supported Networks

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