API Reference
AgentEconomy exposes each agent as an HTTP endpoint gated behind x402 payments. Pay per request in USDC on Base — no accounts, no API keys, no subscriptions.
Base URL (local): http://localhost:3000 – 3007
All endpoints except
All endpoints except
/health and /balance require x402 payment.
Authentication — x402 Protocol
Every gated endpoint follows the x402 flow:
flow
1. Client sends request (no payment) 2. Server responds: 402 Payment Required { x402Version: 1, accepts: [{ scheme: "exact", network: "base-sepolia", maxAmountRequired: "1000", // USDC atomic units payTo: "0xAGENT_WALLET", asset: "0x036CbD...USDC" }] } 3. Client sends USDC on Base Sepolia 4. Client retries with header: X-Payment: <txHash>:<amount>:<sender> 5. Server verifies tx on-chain → serves response
Using x402Fetch (recommended)
typescript
import { x402Fetch } from './lib/x402'; // Automatically handles 402, pays, retries const { data, paymentTx, amountPaid } = await x402Fetch( 'http://localhost:3001/research?query=base+chain', PRIVATE_KEY, { method: 'GET' } );
Manual (raw HTTP)
bash
# Step 1: Get payment requirements curl http://localhost:3001/research?query=base # Step 2: Send USDC, get tx hash # (use cast, ethers, viem, etc.) # Step 3: Retry with payment proof curl http://localhost:3001/research?query=base \ -H "X-Payment: 0xabc123:1000:0xYOUR_ADDR"
Quickstart
bash
# Install the AgentEconomy SDK npm install @agenteconomy/sdk # Or run the full stack locally npx agenteconomy init my-project cd my-project && npm install # Run all agents (dry run = no real funds) DRY_RUN=true npm run researcher & DRY_RUN=true npm run summarizer & DRY_RUN=true npm run writer & DRY_RUN=true npm run analyst & DRY_RUN=true npm run translator & DRY_RUN=true npm run coder & DRY_RUN=true npm run critic & DRY_RUN=true npm run orchestrator & # Send a task curl -X POST http://localhost:3000/task \ -H "Content-Type: application/json" \ -d '{"task": "Write a blog post about Base"}'
🎯 Orchestrator port 3000
Plans tasks and coordinates all sub-agents. This is your main entry point.
POST
/task
Free — orchestrator pays sub-agents
| Body param | Type | Description |
|---|---|---|
| task required | string | Natural language task description |
response
{
"task": "Write a blog post about Base",
"result": "# Base Chain\n\n...",
"payments": [
{ "agent": "researcher", "amount": "0.001 USDC", "txHash": "0x..." },
{ "agent": "summarizer", "amount": "0.001 USDC", "txHash": "0x..." },
{ "agent": "writer", "amount": "0.002 USDC", "txHash": "0x..." }
],
"totalCost": "0.004 USDC",
"elapsedSeconds": "3.21"
}
🔬 Researcher port 3001 0.001 USDC
🔒 x402 required
GET
/research
| Query param | Type | Description |
|---|---|---|
| query required | string | Topic to research |
bash
curl "http://localhost:3001/research?query=base+chain" \
-H "X-Payment: 0xabc:1000:0xYOU"
📝 Summarizer port 3002 0.001 USDC
🔒 x402 required
POST
/summarize
| Body param | Type | Description |
|---|---|---|
| items optional | string[] | Array of facts/sentences to summarize |
| text optional | string | Raw text (newline-separated) to summarize |
✍️ Writer port 3003 0.002 USDC
🔒 x402 required
POST
/write
| Body param | Type | Description |
|---|---|---|
| task required | string | Original task/title |
| summary required | string | Summary from Summarizer agent |
📊 Analyst port 3004 0.003 USDC
🔒 x402 required
POST
/analyze
| Body param | Type | Description |
|---|---|---|
| topic required | string | Topic to analyze (e.g. "base", "x402") |
🌐 Translator port 3005 0.001 USDC
🔒 x402 required
POST
/translate
| Body param | Type | Description |
|---|---|---|
| text required | string | Text to translate |
| targetLang required | string | Target language code: es, fr, zh, ja, de |
💻 Coder port 3006 0.005 USDC
🔒 x402 required
POST
/code
| Body param | Type | Description |
|---|---|---|
| description required | string | What to generate code for |
| type optional | string | x402-middleware, usdc-transfer, agent, default |
🎭 Critic port 3007 0.002 USDC
🔒 x402 required
Reviews and scores content quality. Returns a score, feedback, and pass/fail verdict.
POST
/review
| Body param | Type | Description |
|---|---|---|
| content required | string | Content to review |
| type optional | string | blog, code, analysis, general |
response
{
"agent": "critic",
"score": 87,
"grade": "B+",
"verdict": "pass",
"feedback": [
"Strong structure and clear narrative",
"Good use of technical terminology",
"Could benefit from more concrete examples"
],
"strengths": ["clarity", "structure"],
"improvements": ["add examples", "shorter paragraphs"]
}
Free Endpoints (all agents)
GET
/health
No payment required
{ "status": "ok", "agent": "researcher", "address": "0x..." }
GET
/balance
No payment required
{ "agent": "researcher", "address": "0x...", "ethBalance": "0.01", "usdcBalance": "1.234", "usdcEarned": "0.045" }