Skip to main content

Agent402 API

Agent402 API​

Base URL: https://agent402.ainative.studio
API Prefix: /api/v1
Interactive API Docs: agent402.ainative.studio/docs
Auth: AINative platform API keys (X-API-Key) or JWT Bearer (email/password login)
Source: github.com/AINative-Studio/agent402

Live & Public

Agent402 is deployed and publicly available at https://agent402.ainative.studio — no local setup needed. Use your AINative API key and start calling the endpoints below.

## Public API: https://agent402.ainative.studio
## Interactive docs: https://agent402.ainative.studio/docs

## Or run it yourself:
git clone https://github.com/AINative-Studio/agent402.git
cd agent402 && docker-compose up
Auth Model

Agent402 accepts AINative platform API keys (sk_, svc_, agk_, pa_, tmp_ prefixes) via X-API-Key header or Authorization: Bearer — no registration needed. Note: tmp_ keys expire after 72 hours; use sk_ keys for production agents. It also supports email/password JWT for its own user system: register at POST /api/v1/auth/register, then log in at POST /api/v1/auth/login.

Agent402 (AgentClaw backend) is an autonomous agent orchestration platform. Agents get persistent personalities, pluggable skills, multi-channel comms (Slack, email, Zalo), WireGuard mesh networking, swarm coordination, and x402 HTTP payment rails.

Authentication​

Register​

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "dev@example.com",
  "password": "SecurePass123!",
  "name": "Dev User",
  "workspace_id": "your-workspace-id"
}

Login​

POST /api/v1/auth/login
Content-Type: application/json

{"email": "dev@example.com", "password": "SecurePass123!"}

Returns {"access_token": "...", "refresh_token": "..."}.

Other Auth Endpoints​

MethodPathDescription
GET/api/v1/auth/meCurrent user
POST/api/v1/auth/refreshRefresh JWT
POST/api/v1/auth/logoutLogout
POST/api/v1/auth/change-passwordChange password

Agents​

MethodPathDescription
GET/api/v1/agentsList agents
POST/api/v1/agentsCreate agent
GET/api/v1/agents/{id}Get agent
PUT/api/v1/agents/{id}Update agent
DELETE/api/v1/agents/{id}Delete agent
POST/api/v1/agents/{id}/provisionProvision agent (allocate resources)
POST/api/v1/agents/{id}/messageSend message to agent
POST/api/v1/agents/{id}/pausePause agent
POST/api/v1/agents/{id}/resumeResume agent
POST/api/v1/agents/{id}/heartbeatAgent heartbeat
GET/api/v1/agents/{id}/settingsGet agent settings

Agent Personality​

MethodPathDescription
GET/api/v1/agents/{id}/personalityGet personality config
POST/api/v1/agents/{id}/personality/initializeInitialize personality
GET/api/v1/agents/{id}/personality/context/systemSystem context
GET/api/v1/agents/{id}/personality/context/taskTask context
GET/api/v1/agents/{id}/personality/context/minimalMinimal context

Swarms​

Multi-agent coordination.

MethodPathDescription
GET/api/v1/swarmsList swarms
POST/api/v1/swarmsCreate swarm
GET/api/v1/swarms/{id}Get swarm
PATCH/api/v1/swarms/{id}Update swarm
DELETE/api/v1/swarms/{id}Delete swarm
POST/api/v1/swarms/{id}/agentsAdd agents to swarm
DELETE/api/v1/swarms/{id}/agentsRemove agents
POST/api/v1/swarms/{id}/startStart swarm
POST/api/v1/swarms/{id}/pausePause swarm
POST/api/v1/swarms/{id}/resumeResume swarm
GET/api/v1/swarm/healthSwarm health
GET/api/v1/swarm/timelineActivity timeline
GET/api/v1/swarm/monitoring/statusMonitoring status
GET/api/v1/swarm/alerts/thresholdsAlert thresholds
PUT/api/v1/swarm/alerts/thresholdsUpdate thresholds

Skills​

Pluggable capabilities for agents.

MethodPathDescription
GET/api/v1/skillsList installed skills
GET/api/v1/skills/installableAvailable skills
GET/api/v1/skills/readyReady skills
GET/api/v1/skills/missingSkills with missing dependencies
GET/api/v1/skills/{name}Get skill details
POST/api/v1/skills/{name}/installInstall skill
DELETE/api/v1/skills/{name}/installUninstall skill
GET/api/v1/skills/{name}/install-infoInstallation requirements
GET/api/v1/skills/{name}/installation-statusInstallation status
GET/api/v1/agents/{id}/skillsAgent skill list
POST/api/v1/agents/{id}/skillsAttach skill to agent
DELETE/api/v1/agents/{id}/skills/{name}Detach skill
POST/api/v1/agents/{id}/skills/{name}/configureConfigure skill

Tasks​

MethodPathDescription
GET/api/v1/tasksList tasks
POST/api/v1/tasksCreate task
GET/api/v1/tasks/{id}Get task
DELETE/api/v1/tasks/{id}Delete task
GET/api/v1/tasks/{id}/historyTask history
GET/api/v1/tasks/statsTask statistics
GET/api/v1/tasks/queueTask queue
GET/api/v1/tasks/active-leasesActive task leases

Conversations​

MethodPathDescription
GET/api/v1/conversationsList conversations
POST/api/v1/conversationsCreate conversation
GET/api/v1/conversations/{id}Get conversation
DELETE/api/v1/conversations/{id}Delete conversation
GET/api/v1/conversations/{id}/messagesGet messages
POST/api/v1/conversations/{id}/messagesAdd message
POST/api/v1/conversations/{id}/attach-agentAttach agent
GET/api/v1/conversations/{id}/contextContext window
GET/api/v1/conversations/{id}/searchSearch messages
POST/api/v1/conversations/{id}/archiveArchive

Channels (OpenClaw)​

Multi-channel communication: Slack, email, Zalo, bot tokens.

MethodPathDescription
GET/api/v1/openclaw/channels/availableAvailable channel types
GET/api/v1/openclaw/channels/configuredConfigured channels
POST/api/v1/openclaw/channels/loginAuthenticate channel
POST/api/v1/openclaw/channels/add/slackAdd Slack channel
POST/api/v1/openclaw/channels/add/bot-tokenAdd bot token channel
DELETE/api/v1/openclaw/channels/removeRemove channel
GET/api/v1/openclaw/channels/{channel}/statusChannel status
GET/api/v1/agents/{id}/channelsAgent's channels

Zalo​

MethodPathDescription
POST/api/v1/zalo/connectConnect Zalo
GET/api/v1/zalo/oauth/authorizeOAuth authorize
GET/api/v1/zalo/statusZalo status

Networking (WireGuard Mesh)​

Secure agent mesh networking.

MethodPathDescription
GET/api/v1/network/peersList peers
GET/api/v1/network/topologyNetwork topology
GET/api/v1/network/ip-poolIP pool
POST/api/v1/wireguard/provisionProvision WireGuard peer
GET/api/v1/wireguard/peersList WireGuard peers
GET/api/v1/wireguard/healthWireGuard health
GET/api/v1/wireguard/qualityConnection quality
GET/api/v1/wireguard/pool/statsPool statistics

Security & API Keys​

MethodPathDescription
GET/api/v1/api-keysList configured service API keys
POST/api/v1/api-keys/{service}Store API key for service
POST/api/v1/api-keys/{service}/verifyVerify API key
GET/api/v1/settings/api-keysSettings: API keys
POST/api/v1/settings/api-keysAdd key
DELETE/api/v1/settings/api-keys/{id}Remove key
POST/api/v1/settings/api-keys/testTest key
GET/api/v1/security/audit-logsAudit logs
GET/api/v1/security/tokensActive tokens
POST/api/v1/security/tokensIssue token
POST/api/v1/security/tokens/{jti}/rotateRotate token

Team​

MethodPathDescription
GET/api/v1/team/membersList members
POST/api/v1/team/members/inviteInvite member
PATCH/api/v1/team/members/{id}/roleUpdate role
DELETE/api/v1/team/members/{id}Remove member
POST/api/v1/team/members/accept-invite/{token}Accept invite

Templates​

MethodPathDescription
GET/api/v1/templatesList agent templates
GET/api/v1/templates/{id}Get template
POST/api/v1/templates/seedSeed default templates

Machine Payments Protocol (MPP)​

Every 402 Payment Required response that carries structured payment requirements also attaches a WWW-Authenticate: Payment header with the SAME requirements (scheme, network, asset, amount, pay_to) as the JSON body — never a static or generic string. This lets an autonomous agent discover payment terms from the header alone, per the standard HTTP WWW-Authenticate challenge convention, without having to parse the response body at all. Refs #9247 (introduced), #9337 (extended to A2A).

Header shape​

WWW-Authenticate: Payment scheme="exact", network="<network>", asset="<asset>", amount="<amount>", pay_to="<wallet>"
FieldMeaning
schemePayment scheme — currently always exact
networkSettlement network (e.g. circle, BASE-SEPOLIA, hedera)
assetPayment asset — currently always USDC
amountAmount required, in the asset's minor units (x402 purchases) or USD (A2A budget top-up)
pay_toThe wallet address/id to pay

Where it appears today​

Call siteTriggerNotes
POST /api/v1/cloud/x402/subscriptions/subscribeNo payment_proof supplied for a plan purchaseamount is the plan price in USDC minor units (e.g. 500 = $5.00)
POST /cloud/a2a/{agent_id}/message, POST /cloud/a2a/routeAgentSpawnGate.check_budget() raises BudgetExceededError (caller's spend would exceed their configured budget)amount is the USD shortfall (requested_usd, or task_cost_usd for a per-task cap) — there's no on-chain purchase here, so the header tells the agent how much budget headroom to add, via the same platform wallet/network it would use to buy a subscription

Both call sites build the header with the same shared helper (app/services/mpp_headers.py's build_www_authenticate_payment_header), so the shape never drifts between the two paths.

Example — x402 subscribe challenge​

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment scheme="exact", network="BASE-SEPOLIA", asset="USDC", amount="500", pay_to="0xPLATFORMWALLET..."
Content-Type: application/json

{
  "detail": "Payment required — pay the USDC amount to the pay_to wallet, then re-call with payment_proof.",
  "error_code": "payment_required",
  "next_action": "submit_x402_payment",
  "requirements": {
    "plan_id": "hobbyist",
    "amount": 500,
    "asset": "USDC",
    "network": "BASE-SEPOLIA",
    "pay_to": "0xPLATFORMWALLET...",
    "expires_at": "2026-10-27T18:30:00Z"
  }
}

Example — A2A budget-exceeded 402​

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment scheme="exact", network="circle", asset="USDC", amount="2.5", pay_to="0xPLATFORMWALLET..."
Content-Type: application/json

{
  "detail": "Agent user-abc123 budget exceeded: $10.0000 spent of $10.0000 monthly limit, requested $2.5000"
}
Scope

This is a header-discovery convention on top of the existing 402 JSON bodies — it does not change any status code, and the JSON body remains the authoritative payload. It's distinct from the X-Payment / X-Payment-Response wire-format headers documented below, which carry an actual payment proof/settlement, not a discovery challenge.

x402 Cloudflare Wire Format​

Cloudflare-compatible payment headers for tool-level micropayments. Agents include these headers to pay for API calls automatically. Refs #5007

Headers​

HeaderDescription
X-PaymentBase64-encoded payment payload (amount, currency, payer wallet)
X-Payment-ResponseReturned by server with settlement proof

Endpoints​

MethodPathDescription
POST/api/v1/cloud/x402/verifyVerify an x402 payment header
POST/api/v1/cloud/x402/settleSettle a verified payment
GET/api/v1/cloud/x402/ratesCurrent tool pricing schedule

Payment Flow​

Agent → Tool API
  ├── X-Payment: <base64 payload>
  ├── Server verifies payment header
  ├── Server executes tool call
  ├── Server settles payment (90/5/5 split)
  └── X-Payment-Response: <settlement proof>

The payment payload includes:

{
  "amount": "0.001",
  "currency": "USDC",
  "payer": "wallet-id",
  "nonce": "unique-nonce",
  "expires_at": "2026-07-13T12:00:00Z"
}

Agent Wallets (USDC)​

Per-agent USDC wallets with 3-layer spending guards. Each agent gets an isolated wallet with configurable limits. Refs #5008

Spending Guards​

GuardDefaultDescription
Single payment cap$10.00Maximum per-transaction amount
Period spending limit$100.00/monthMaximum spend per billing period
Balance check—Transaction rejected if balance insufficient

Endpoints​

MethodPathDescription
POST/api/v1/cloud/x402/walletsCreate wallet for agent
GET/api/v1/cloud/x402/wallets/{agent_id}Get wallet balance and limits
POST/api/v1/cloud/x402/wallets/{agent_id}/fundFund wallet with USDC
POST/api/v1/cloud/x402/wallets/{agent_id}/withdrawWithdraw from wallet
PUT/api/v1/cloud/x402/wallets/{agent_id}/limitsUpdate spending limits
GET/api/v1/cloud/x402/wallets/{agent_id}/transactionsTransaction history

Create Wallet​

POST /api/v1/cloud/x402/wallets
Authorization: Bearer <token>
Content-Type: application/json

{
  "agent_id": "agent-abc-123",
  "spending_limit_usd": 100.0,
  "single_payment_limit_usd": 10.0,
  "period": "monthly"
}

Response:

{
  "wallet_id": "uuid",
  "agent_id": "agent-abc-123",
  "balance_usd": 0.0,
  "spending_limit_usd": 100.0,
  "single_payment_limit_usd": 10.0,
  "period": "monthly",
  "status": "active"
}

Fund Wallet​

POST /api/v1/cloud/x402/wallets/agent-abc-123/fund
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount_usd": 50.0,
  "source": "platform_credits"
}

Update Spending Limits​

PUT /api/v1/cloud/x402/wallets/agent-abc-123/limits
Authorization: Bearer <token>
Content-Type: application/json

{
  "spending_limit_usd": 200.0,
  "single_payment_limit_usd": 25.0,
  "period": "monthly"
}

Marketplace Revenue Share​

Automatic revenue splitting for tool marketplace payments. Every x402 payment is split between tool owner, platform, and referrer. Refs #5009

Default Split​

RecipientShareDescription
Tool owner90%Developer who published the tool
Platform5%AINative platform fee
Referrer5%Agent/user who referred the caller (goes to platform if none)

Endpoints​

MethodPathDescription
GET/api/v1/cloud/x402/marketplace/revenueRevenue breakdown for authenticated user
GET/api/v1/cloud/x402/marketplace/settlementSettlement status and pending earnings
POST/api/v1/cloud/x402/marketplace/withdrawWithdraw settled earnings
GET/api/v1/cloud/x402/marketplace/withdrawalsWithdrawal history

Revenue Breakdown​

GET /api/v1/cloud/x402/marketplace/revenue?period_start=2026-07-01&period_end=2026-07-31
Authorization: Bearer <token>

Response:

{
  "user_id": "user-uuid",
  "period_start": "2026-07-01",
  "period_end": "2026-07-31",
  "total_earned_usd": 450.00,
  "total_splits": 50,
  "breakdown": {
    "as_owner": 400.00,
    "as_referrer": 50.00
  }
}

Withdraw Earnings​

POST /api/v1/cloud/x402/marketplace/withdraw
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount_usd": 100.0
}

Response:

{
  "withdrawal_id": "uuid",
  "amount_usd": 100.0,
  "split_count": 12,
  "status": "completed"
}

Health & Metrics​

MethodPathDescription
GET/healthService health
GET/metricsPrometheus metrics
GET/rate-limit-statusRate limit status
GET/api/v1/db/healthDB health
GET/api/v1/db/pool-statsDB pool stats
GET/api/v1/metricsApp metrics