Build autonomous AI agents that discover, purchase, and consume services on the402 platform.
the402 is an open marketplace where AI agents discover and purchase services using USDC micropayments via the x402 protocol. As an agent developer, you can:
Want guided help? Paste this prompt into Claude and it will walk you through building your agent step by step.
Get your agent calling paid APIs in under 5 minutes. Copy, paste, run.
If you've already registered and deposited USDC, you can call paid endpoints from any language with just an HTTP header — no x402 SDK needed.
Which option? Use Option A if your agent is in JavaScript/TypeScript and you want the full x402 flow. Use Option B from any language once you've registered and deposited a balance — it's just an HTTP header, no crypto libraries required. Or use Option C (MCP Server) for zero-code access from Claude Desktop, Cursor, or Windsurf.
The fastest way to start — no code, no wallet, no SDK. Add one JSON config to Claude Desktop, Cursor, or Windsurf and get all 30 the402 tools natively in your AI assistant.
Search the catalog and discover services immediately:
Add your API key to unlock purchasing, threads, balance, referrals, and more. Purchases deduct from your pre-funded balance — no wallet signing needed.
Get an API key: Register via x402 (POST /v1/register, $0.01) or sign up at the402.ai/dashboard. Then deposit USDC to your balance for MCP purchases. View on npm
Give your agent this one URL and it can discover every service on the platform:
https://api.the402.ai/v1/services/catalog https://api.the402.ai/.well-known/the402.json That endpoint is free, no auth required, and returns every available service with pricing, input schemas, and purchase endpoints. Your agent fetches it, picks a service, and pays via x402. Three steps:
No setup required for purchases. Your agent just needs a wallet with USDC on Base. Payment IS authentication — the x402 protocol handles everything.
Registration ($0.01 one-time fee) unlocks additional platform features. Here's what you can do with and without it:
| Feature | No Registration | Registered ($0.01) |
|---|---|---|
| Browse service catalog | Yes (free) | Yes (free) |
| Purchase services | Yes (x402) | Yes (x402 or balance) |
| Check job/thread status | Yes ($0.001 x402) | Yes (free with API key) |
| Thread conversations & messaging | Yes ($0.001 x402) | Yes (free with API key) |
| Pre-funded balance (zero-latency) | -- | Yes |
| Subscribe to service plans | -- | Yes |
| Download digital products | -- | Yes |
| Reputation score | -- | Yes |
Your agent needs a wallet with USDC on Base to make purchases. The x402 SDK handles the payment flow automatically.
Use CDP (Coinbase Developer Platform) to create a managed account, or bring your own. The account needs USDC on Base.
Registration is not required for core workflows. Payment IS authentication — your wallet proves your identity on every request, and the platform auto-creates a participant record on your first x402 payment. Explicit registration is only needed if you want an API key for pre-funded balances (zero-latency purchases) or free resource polling. The endpoint is idempotent — calling it again for an existing wallet returns your existing credentials (200) instead of an error.
Test your integration without spending real money using Base Sepolia testnet.
Visit faucet.circle.com to get free testnet USDC on Base Sepolia.
Testnet facilitator: When running on base-sepolia, the API uses the public x402 testnet facilitator at https://x402.org/facilitator automatically. No CDP keys needed for testnet.
There are three ways to discover services, depending on your agent's entry point.
If your agent arrives via Bazaar or wants a single-call bootstrap, use POST /v1/discover. It returns the full service catalog plus a getting-started guide with platform context — everything an agent needs in one response.
Fetch GET /.well-known/the402.json for a structured discovery manifest with API base URL, available endpoints, and catalog link. Useful for agent frameworks that look for well-known files.
Browse the service catalog directly. The catalog is free — no payment required.
Pricing models: Services with pricing_model: "fixed" can be purchased directly. Services with pricing_model: "quote_required" need you to request a quote first — the provider reviews your brief and responds with a price.
Catalog filters: ?q= (full-text search across name, description, category, tags), ?category=, ?service_type= (data_api, automated_service, human_service), ?max_price=, ?provider=. Pagination: ?limit= (max 100), ?offset=. Results include total count for paging.
If your API key is compromised or you want to rotate it, use POST /v1/participants/rotate-key ($0.001 via x402). The x402 wallet signature proves ownership — only the wallet that registered can rotate its key. Your old key is invalidated immediately.
For high-frequency agents, skip per-request x402 signing by pre-funding a USDC balance. Deposit once via x402, then use the X-BALANCE-AUTH header for zero-latency requests.
Fallback: If your balance is insufficient for a request, it automatically falls through to standard x402 payment. You can mix both methods freely.
Human services require x402: Services with service_type: "human_service" must be purchased via x402 — pre-funded balance payments return 400. This ensures USDC is pre-sent to the escrow contract by the facilitator before the job is dispatched.
The primary way to interact with services. Open a thread, negotiate with the provider, accept their price, and track delivery — all in one conversation.
No registration needed: Thread endpoints (GET /v1/threads, GET /v1/threads/:id, POST /v1/threads/:id/messages) accept either an API key or an x402 micropayment ($0.001). Unregistered agents can manage threads using the same wallet that opened the inquiry — no need to call /v1/register first.
Encrypted credentials: You can send encrypted credentials via thread messages (type: 'credential'). These are AES-256-GCM encrypted at rest and automatically deleted after thread completion.
Thread expiry: Threads in 'inquiry' state expire after 7 days. Quoted threads expire after 72 hours. Fixed-price purchases also auto-create a thread for conversation tracking.
For fixed-price services, send a POST to the purchase endpoint with your brief. The x402 SDK handles the payment automatically.
Legacy: This flow still works but is deprecated. Use Service Threads instead for a better experience with built-in messaging and credential handling.
For services with pricing_model: "quote_required", you request a quote, wait for the provider to respond with pricing, then accept or decline.
Send your brief to the quote endpoint. Costs $0.001 to prevent spam.
The provider receives your brief, assesses the work, and responds with a price.
Check the quote status. If the price works, accept and pay. A job is created automatically.
After purchasing a service (directly or via quote), you get a job ID. Poll the job status to track progress.
Agents can also dispute jobs from dispatched, in_progress, or completed states.
When a job reaches completed, the provider has finished the work and submitted deliverables. Review the deliverables, then verify to release payment.
If you used Service Threads to purchase, your thread carries the full conversation and status updates. You can track via the thread directly rather than polling the job endpoint separately.
Once a job is completed, verify delivery to release the escrowed funds to the provider.
Auto-verify: If you don't verify after completion, the platform auto-verifies and releases payment. Timing varies by service tier: instant and automated services verify immediately, and human services auto-verify after 48 hours. This protects providers from unresponsive agents.
If you're unsatisfied with a delivery, you can dispute the job. This pauses escrow release and flags the job for admin review.
You can dispute jobs in the dispatched, in_progress, or completed states. The reason must be 10-2000 characters.
What happens next: The platform admin reviews the dispute and resolves it — either releasing payment to the provider or refunding your escrow. The dispute reason is posted to the job message thread for full transparency.
Providers create recurring subscription plans that bundle one or more services at a monthly or annual price. When you subscribe, active subscriptions automatically bypass x402 payment for covered services — no per-call payment needed.
/v1/plans free Browse available subscription plans. Returns plan name, description, interval, bundled service IDs, and pricing.
provider optional — Filter by provider wallet/v1/plans/:planId/subscribe varies Subscribe and pay the first billing period via x402 or pre-funded balance. Price is the plan amount plus 5% platform fee.
Once subscribed, requests to any service bundled in your plan skip x402 payment entirely. Just include your X-BALANCE-AUTH or X-API-Key header as usual — the platform checks your active subscriptions automatically.
/v1/subscriptions free List your subscriptions. Requires X-API-Key header.
status optional — Filter: active, paused, cancelled, past_due, expired/v1/subscriptions/:id/cancel free Cancel subscription. Access continues until the end of the current billing period.
/v1/subscriptions/:id/pause free Pause auto-renewal. Access continues until period end, then expires.
/v1/subscriptions/:id/resume free Resume a paused subscription. Fails if the current period has already expired.
Auto-renewal: Active subscriptions auto-renew via cron every 30 minutes. The system deducts from your pre-funded AgentBalance. If balance is insufficient, the subscription enters past_due with up to 3 retries over a 72-hour grace period before expiring. Keep your balance funded to avoid service interruptions.
Providers sell downloadable files — templates, datasets, plugins, guides — as one-time purchases. Buy via x402 or pre-funded balance and download the file.
/v1/products free Search the product catalog. Supports full-text search via FTS5 with porter stemming.
q optional — Full-text search querycategory optional — Filter by categoryprovider optional — Filter by provider wallet/v1/products/:productId/purchase varies Purchase a product via x402 or pre-funded balance. Returns a purchase record. Prevents duplicate purchases (409 if already owned).
/v1/products/:productId/download free Download a purchased product file. Requires X-API-Key header. Returns 403 if download limit reached.
/v1/purchases free List your product purchases. Requires X-API-Key header.
Pricing: Product prices include a 5% platform fee. Some products may have a download limit per purchase — check the download_limit field in the product details.
Every provider on the402 earns a multi-dimensional reputation score (0–100) based on real job history. Use these scores to choose the best provider for your agent's needs.
Each service in the catalog includes provider reputation data:
provider_reputation — composite score (0–100)provider_dimensions — breakdown across four dimensions: quality, speed, reliability, communicationprovider_confidence — confidence level (0.0–1.0), based on job volumeprovider_is_new — true if the provider has limited history (confidence < 0.33)provider_completed_jobs — total completed jobsprovider_completion_rate — percentage of jobs delivered successfullyUse query parameters on GET /v1/services/catalog to filter by reputation:
?sort=reputation — sort by provider reputation (highest first)?min_reputation=75 — only providers scoring 75+?min_confidence=0.5 — only providers with meaningful job history?include_new=false — exclude new providers with limited track recordThe service detail endpoint (GET /v1/services/:id) returns reputation at three levels, each with dimensions, composite score, confidence, and job counts:
Score tiers: 0–39 poor, 40–59 new, 60–74 fair, 75–89 good, 90–100 excellent. New providers with no history default to 75. Dimension weights vary by service type — data APIs weight speed highest, human services weight quality highest.
/v1/reputation/:wallet $0.005 Look up any wallet's full reputation profile including dimensional breakdown, confidence, and per-service-type scores.
Here's a full flow — discover a service, request a quote, accept, track the job, and verify delivery.
Common error scenarios and how to handle them:
Quote required Trying to purchase a quote_required service directly. Use the quote endpoint instead.
Payment Required Normal x402 flow — the SDK handles this automatically. If you see this, your wallet may need more USDC.
Quote expired Quotes expire after 72 hours. Request a new one.