Overview
the402 connects your services with AI agents that need them. As a provider, you:
- Register once and list your services with pricing, input schemas, and delivery estimates
- Receive job requests via webhook when agents purchase your services
- Fulfill jobs and submit deliverables through the API
- Get paid in USDC on Base L2 — escrow protects both parties
- Offer fixed-price or variable-price (quote-based) services
How payment works: When an agent purchases your service, their payment goes into escrow. You fulfill the work, the agent verifies delivery, and escrow releases funds to you (minus a 5% platform fee). If the agent doesn't verify within 48 hours, auto-verify kicks in.
Registration
Register as a provider by calling the registration endpoint. This is a paid call ($0.01 via x402) that creates your provider account.
curl -X POST https://api.the402.ai/v1/register \
-H "Content-Type: application/json" \
-d '{
"name": "GoWP",
"description": "Professional WordPress maintenance and support",
"type": "provider",
"webhook_url": "https://yoursite.com/api/the402/webhook",
"capabilities": ["wordpress-maintenance", "content-changes", "support"]
}'
You'll receive an API key in the response. Save this — you need it for all authenticated operations.
// Response:
{
"id": "p_abc123",
"api_key": "pk_live_...",
"wallet": "0x..."
}
Listing Services
List services that agents can purchase. Each service has a pricing model: fixed for direct purchase, or quote_required for variable pricing.
Fixed-price service
curl -X POST https://api.the402.ai/v1/services \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "WordPress Technical Support",
"description": "Expert WordPress troubleshooting. Plugin conflicts, white screen, performance issues.",
"price": { "fixed": "$50.00" },
"pricing_model": "fixed",
"fulfillment_type": "human",
"estimated_delivery": "48h",
"category": "wordpress",
"tags": ["support", "wordpress", "troubleshooting"],
"input_schema": {
"type": "object",
"required": ["site_url", "issue_description"],
"properties": {
"site_url": { "type": "string" },
"issue_description": { "type": "string" },
"severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] } } } }'
Variable-price service (quote required)
curl -X POST https://api.the402.ai/v1/services \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "WordPress Content Change",
"description": "Human-fulfilled WordPress content updates. Text edits, image swaps, page creation.",
"price": { "min": "$25.00", "max": "$100.00" },
"pricing_model": "quote_required",
"fulfillment_type": "human",
"estimated_delivery": "24h",
"category": "wordpress",
"tags": ["content", "wordpress", "human"]
}'
Pricing models: Use "fixed" when every job costs the same. Use "quote_required" when the price depends on the scope of work — you'll review each brief and respond with a specific price.
Receiving Jobs
When an agent purchases a fixed-price service, your webhook receives a job dispatch:
// POST to your webhook_url
// Header: X-Platform-Secret: your-api-key
{
"type": "job_dispatch",
"job_id": "job_abc123",
"service_id": "svc_xyz",
"brief": {
"site_url": "https://example.com",
"issue_description": "Plugin conflict causing white screen"
},
"deadline": "2025-03-03T00:00:00Z",
"callback_url": "https://api.the402.ai/v1/jobs/job_abc123/update"
}
Verify the X-Platform-Secret header matches your API key, then acknowledge with a 200 response.
Responding to Quote Requests
For quote_required services, you receive a quote request instead of a job dispatch. Review the brief and respond with your price.
1. Receive the quote request
// POST to your webhook_url
{
"type": "quote_request",
"quote_id": "qt_abc123",
"service_id": "svc_xyz",
"service_name": "WordPress Content Change",
"brief": {
"site_url": "https://example.com",
"changes": [{ "page_url": "/about", "description": "Update team bios" }]
},
"respond_url": "https://api.the402.ai/v1/quotes/qt_abc123/respond"
}
2. Respond with your price
curl -X POST https://api.the402.ai/v1/quotes/qt_abc123/respond \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"quoted_price_usd": 45,
"provider_notes": "Can complete in 12 hours. Includes 2 page edits."
}'
The platform adds a 5% fee for the agent. Your quoted price of $45 means the agent pays $47.25, and you receive $45.
Expiry: Quotes expire 72 hours after your response if the agent doesn't accept. Pending quotes (no response from you) expire 72 hours after creation.
Fulfilling Jobs
Update job status as you work. When complete, submit deliverables.
Mark as in progress
curl -X POST https://api.the402.ai/v1/jobs/job_abc123/update \
-H "X-API-Key: your-api-key" \
-d '{ "status": "in_progress" }'
Submit deliverables
curl -X POST https://api.the402.ai/v1/jobs/job_abc123/update \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"status": "completed",
"deliverables": {
"summary": "Resolved plugin conflict between WooCommerce and Elementor",
"changes_made": ["Deactivated conflicting plugin", "Applied compatibility patch"],
"tested": true
},
"notes": "Site is back online. Recommend updating Elementor to 3.18+"
}'
created → dispatched → in_progress → completed → verified → released
Getting Paid
Payment flows through escrow for protection:
1 Agent purchases USDC payment goes into escrow (on-chain or platform-managed).
2 You fulfill the job Complete the work and submit deliverables via the API.
3 Agent verifies (or auto-verify) Agent reviews and verifies delivery. If no response within 48 hours, auto-verify triggers.
4 Escrow releases to you Funds released minus the 5% platform fee. For a $50 job, you receive $47.50.
Webhook Reference
Your webhook URL receives two types of events:
Sent when an agent purchases a fixed-price service. Contains type: "job_dispatch", job details, brief, deadline, and callback URL.
Sent when an agent requests a quote for a quote_required service. Contains type: "quote_request", brief, and respond URL.
Both include the X-Platform-Secret header with your API key for verification. Always return a 200 response promptly.
API Reference
All provider API calls require the X-API-Key header.
List a new service. Requires: name, description, price, fulfillment_type, estimated_delivery, category.
Update an existing service listing.
Update job status. Set status to "in_progress", "completed", or "failed". Include deliverables when completing.
Respond to a quote request with quoted_price_usd and optional provider_notes.
Post a message to the job conversation thread. Useful for clarifications and updates.