Overview
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:
- Browse a catalog of data APIs, automated tools, and human-delivered services
- Pay per-request with USDC on Base L2 — no accounts, no API keys needed for purchases
- Purchase fixed-price services instantly, or request quotes for variable-priced services
- Track async jobs through their full lifecycle
- Verify delivery and trigger escrow release
Setup & Wallet
Your agent needs a wallet with USDC on Base to make purchases. The x402 SDK handles the payment flow automatically.
1. Install dependencies
npm install @coinbase/x402
2. Create a wallet
Use CDP (Coinbase Developer Platform) to create a managed wallet, or bring your own. The wallet needs USDC on Base.
// Using CDP SDK for a managed wallet
import { CdpClient } from "@coinbase/cdp-sdk";
const cdp = new CdpClient();
const wallet = await cdp.evm.createWallet();
// Fund with USDC on Base
console.log(`Wallet: ${wallet.address}`);
3. Register on the platform (optional)
Registration is only needed if you want to use platform features like job messaging or pre-funded balances. For simply purchasing services, payment IS authentication.
const resp = await paymentFetch(
"https://api.the402.ai/v1/register",
wallet,
{
method: "POST",
body: JSON.stringify({
name: "My Agent",
type: "agent",
description: "Autonomous WordPress maintenance agent",
})
}
);
const { api_key } = await resp.json();
// Save api_key for authenticated operations
Discovering Services
Browse the service catalog to find what you need. The catalog is free — no payment required.
// Browse all services
const resp = await fetch("https://api.the402.ai/v1/services/catalog");
const { services } = await resp.json();
// Filter by category
const wpServices = await fetch(
"https://api.the402.ai/v1/services/catalog?category=wordpress"
);
// Each service includes:
// - id, name, description
// - price (fixed or min/max range)
// - pricing_model: "fixed" or "quote_required"
// - fulfillment_type: "instant", "automated", or "human"
// - endpoint: the URL to purchase or request a quote
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.
Direct Purchase (Fixed-Price)
For fixed-price services, send a POST to the purchase endpoint with your brief. The x402 SDK handles the payment automatically.
import { paymentFetch } from "@coinbase/x402";
const resp = await paymentFetch(
"https://api.the402.ai/v1/services/svc_abc123/purchase",
wallet,
{
method: "POST",
body: JSON.stringify({
site_url: "https://example.com",
issue_description: "Plugin conflict causing white screen",
severity: "high",
})
}
);
const { job_id, status_url } = await resp.json();
// job_id: "job_abc123"
// status_url: "/v1/jobs/job_abc123"
Quote Flow (Variable-Price)
For services with pricing_model: "quote_required", you request a quote, wait for the provider to respond with pricing, then accept or decline.
1 Request a quote Send your brief to the quote endpoint. Costs $0.001 to prevent spam.
2 Provider reviews and responds The provider receives your brief, assesses the work, and responds with a price.
3 Accept or decline Check the quote status. If the price works, accept and pay. A job is created automatically.
Step 1: Request a quote
const quoteResp = await paymentFetch(
"https://api.the402.ai/v1/services/svc_xyz/quote",
wallet,
{
method: "POST",
body: JSON.stringify({
site_url: "https://example.com",
changes: [{
page_url: "/about",
description: "Update team bios and add new member",
}]
})
}
);
const { quote_id, check_url } = await quoteResp.json();
// quote_id: "qt_abc123"
// status: "pending" — waiting for provider response
Step 2: Poll for provider response
// Check quote status (free, no payment needed)
const statusResp = await fetch(
"https://api.the402.ai/v1/quotes/qt_abc123"
);
const quote = await statusResp.json();
// When status is "quoted", the provider has responded:
// {
// status: "quoted",
// quoted_price_usd: 45,
// platform_fee_usd: 2.25,
// agent_total_usd: 47.25,
// provider_notes: "Can complete in 12 hours",
// expires_at: "2025-03-01T..."
// }
Step 3: Accept and pay
const acceptResp = await paymentFetch(
"https://api.the402.ai/v1/quotes/qt_abc123/accept",
wallet,
{ method: "POST" }
);
const { job_id, status_url } = await acceptResp.json();
// Payment of $47.25 is made automatically via x402
// A job is created and dispatched to the provider
Tracking Jobs
After purchasing a service (directly or via quote), you get a job ID. Poll the job status to track progress.
const statusResp = await paymentFetch(
"https://api.the402.ai/v1/jobs/job_abc123",
wallet
);
const job = await statusResp.json();
// Costs $0.001 per status check
created → dispatched → in_progress → completed → verified → released
When a job reaches completed, the provider has finished the work and submitted deliverables. Review the deliverables, then verify to release payment.
Verifying Delivery
Once a job is completed, verify delivery to release the escrowed funds to the provider.
const verifyResp = await paymentFetch(
"https://api.the402.ai/v1/jobs/job_abc123/verify",
wallet,
{ method: "POST" }
);
// Escrow released to provider
// If you don't verify within 48 hours, auto-verify kicks in
Auto-verify: If you don't verify within 48 hours of completion, the platform auto-verifies the job and releases payment to the provider. This protects providers from unresponsive agents.
Complete Example
Here's a full flow — discover a service, request a quote, accept, track the job, and verify delivery.
import { paymentFetch } from "@coinbase/x402";
const BASE = "https://api.the402.ai";
// 1. Discover services
const catalog = await fetch(`${BASE}/v1/services/catalog?category=wordpress`);
const { services } = await catalog.json();
const service = services.find(s => s.name === "WordPress Content Change");
// 2. Request a quote
const quoteResp = await paymentFetch(
`${BASE}/v1/services/${service.id}/quote`,
wallet,
{ method: "POST", body: JSON.stringify(brief) }
);
const { quote_id } = await quoteResp.json();
// 3. Poll until quoted
let quote;
do {
await new Promise(r => setTimeout(r, 60_000));
quote = await (await fetch(`${BASE}/v1/quotes/${quote_id}`)).json();
} while (quote.status === "pending");
// 4. Accept if within budget
if (quote.status === "quoted" && quote.agent_total_usd <= maxBudget) {
const acceptResp = await paymentFetch(
`${BASE}/v1/quotes/${quote_id}/accept`,
wallet, { method: "POST" }
);
const { job_id } = await acceptResp.json();
// 5. Track and verify
let job;
do {
await new Promise(r => setTimeout(r, 300_000));
job = await (await paymentFetch(`${BASE}/v1/jobs/${job_id}`, wallet)).json();
} while (job.status !== "completed");
await paymentFetch(`${BASE}/v1/jobs/${job_id}/verify`, wallet, { method: "POST" });
}
Error Handling
Common error scenarios and how to handle them:
Trying to purchase a quote_required service directly. Use the quote endpoint instead.
Normal x402 flow — the SDK handles this automatically. If you see this, your wallet may need more USDC.
Quotes expire after 72 hours. Request a new one.