---
title: "Agent402 API"
description: "Autonomous agent orchestration and payment framework — swarms, skills, Hedera, x402, Circle USDC"
canonical: "https://docs.ainative.studio/docs/web3/agent402"
last-updated: "2026-09-23T01:51:08.820Z"
---

# Agent402 API

Source: https://docs.ainative.studio/docs/web3/agent402

> Autonomous agent orchestration and payment framework — swarms, skills, Hedera, x402, Circle USDC

## Agent402 API

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

:::tip 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.
```bash
## 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
```
:::

:::info 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

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

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

### Login

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

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

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

### Other Auth Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/auth/me` | Current user |
| `POST` | `/api/v1/auth/refresh` | Refresh JWT |
| `POST` | `/api/v1/auth/logout` | Logout |
| `POST` | `/api/v1/auth/change-password` | Change password |

---

## Agents

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/agents` | List agents |
| `POST` | `/api/v1/agents` | Create 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}/provision` | Provision agent (allocate resources) |
| `POST` | `/api/v1/agents/{id}/message` | Send message to agent |
| `POST` | `/api/v1/agents/{id}/pause` | Pause agent |
| `POST` | `/api/v1/agents/{id}/resume` | Resume agent |
| `POST` | `/api/v1/agents/{id}/heartbeat` | Agent heartbeat |
| `GET` | `/api/v1/agents/{id}/settings` | Get agent settings |

### Agent Personality

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/agents/{id}/personality` | Get personality config |
| `POST` | `/api/v1/agents/{id}/personality/initialize` | Initialize personality |
| `GET` | `/api/v1/agents/{id}/personality/context/system` | System context |
| `GET` | `/api/v1/agents/{id}/personality/context/task` | Task context |
| `GET` | `/api/v1/agents/{id}/personality/context/minimal` | Minimal context |

---

## Swarms

Multi-agent coordination.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/swarms` | List swarms |
| `POST` | `/api/v1/swarms` | Create 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}/agents` | Add agents to swarm |
| `DELETE` | `/api/v1/swarms/{id}/agents` | Remove agents |
| `POST` | `/api/v1/swarms/{id}/start` | Start swarm |
| `POST` | `/api/v1/swarms/{id}/pause` | Pause swarm |
| `POST` | `/api/v1/swarms/{id}/resume` | Resume swarm |
| `GET` | `/api/v1/swarm/health` | Swarm health |
| `GET` | `/api/v1/swarm/timeline` | Activity timeline |
| `GET` | `/api/v1/swarm/monitoring/status` | Monitoring status |
| `GET` | `/api/v1/swarm/alerts/thresholds` | Alert thresholds |
| `PUT` | `/api/v1/swarm/alerts/thresholds` | Update thresholds |

---

## Skills

Pluggable capabilities for agents.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/skills` | List installed skills |
| `GET` | `/api/v1/skills/installable` | Available skills |
| `GET` | `/api/v1/skills/ready` | Ready skills |
| `GET` | `/api/v1/skills/missing` | Skills with missing dependencies |
| `GET` | `/api/v1/skills/{name}` | Get skill details |
| `POST` | `/api/v1/skills/{name}/install` | Install skill |
| `DELETE` | `/api/v1/skills/{name}/install` | Uninstall skill |
| `GET` | `/api/v1/skills/{name}/install-info` | Installation requirements |
| `GET` | `/api/v1/skills/{name}/installation-status` | Installation status |
| `GET` | `/api/v1/agents/{id}/skills` | Agent skill list |
| `POST` | `/api/v1/agents/{id}/skills` | Attach skill to agent |
| `DELETE` | `/api/v1/agents/{id}/skills/{name}` | Detach skill |
| `POST` | `/api/v1/agents/{id}/skills/{name}/configure` | Configure skill |

---

## Tasks

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/tasks` | List tasks |
| `POST` | `/api/v1/tasks` | Create task |
| `GET` | `/api/v1/tasks/{id}` | Get task |
| `DELETE` | `/api/v1/tasks/{id}` | Delete task |
| `GET` | `/api/v1/tasks/{id}/history` | Task history |
| `GET` | `/api/v1/tasks/stats` | Task statistics |
| `GET` | `/api/v1/tasks/queue` | Task queue |
| `GET` | `/api/v1/tasks/active-leases` | Active task leases |

---

## Conversations

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/conversations` | List conversations |
| `POST` | `/api/v1/conversations` | Create conversation |
| `GET` | `/api/v1/conversations/{id}` | Get conversation |
| `DELETE` | `/api/v1/conversations/{id}` | Delete conversation |
| `GET` | `/api/v1/conversations/{id}/messages` | Get messages |
| `POST` | `/api/v1/conversations/{id}/messages` | Add message |
| `POST` | `/api/v1/conversations/{id}/attach-agent` | Attach agent |
| `GET` | `/api/v1/conversations/{id}/context` | Context window |
| `GET` | `/api/v1/conversations/{id}/search` | Search messages |
| `POST` | `/api/v1/conversations/{id}/archive` | Archive |

---

## Channels (OpenClaw)

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

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/openclaw/channels/available` | Available channel types |
| `GET` | `/api/v1/openclaw/channels/configured` | Configured channels |
| `POST` | `/api/v1/openclaw/channels/login` | Authenticate channel |
| `POST` | `/api/v1/openclaw/channels/add/slack` | Add Slack channel |
| `POST` | `/api/v1/openclaw/channels/add/bot-token` | Add bot token channel |
| `DELETE` | `/api/v1/openclaw/channels/remove` | Remove channel |
| `GET` | `/api/v1/openclaw/channels/{channel}/status` | Channel status |
| `GET` | `/api/v1/agents/{id}/channels` | Agent's channels |

### Zalo

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/v1/zalo/connect` | Connect Zalo |
| `GET` | `/api/v1/zalo/oauth/authorize` | OAuth authorize |
| `GET` | `/api/v1/zalo/status` | Zalo status |

---

## Networking (WireGuard Mesh)

Secure agent mesh networking.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/network/peers` | List peers |
| `GET` | `/api/v1/network/topology` | Network topology |
| `GET` | `/api/v1/network/ip-pool` | IP pool |
| `POST` | `/api/v1/wireguard/provision` | Provision WireGuard peer |
| `GET` | `/api/v1/wireguard/peers` | List WireGuard peers |
| `GET` | `/api/v1/wireguard/health` | WireGuard health |
| `GET` | `/api/v1/wireguard/quality` | Connection quality |
| `GET` | `/api/v1/wireguard/pool/stats` | Pool statistics |

---

## Security & API Keys

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/api-keys` | List configured service API keys |
| `POST` | `/api/v1/api-keys/{service}` | Store API key for service |
| `POST` | `/api/v1/api-keys/{service}/verify` | Verify API key |
| `GET` | `/api/v1/settings/api-keys` | Settings: API keys |
| `POST` | `/api/v1/settings/api-keys` | Add key |
| `DELETE` | `/api/v1/settings/api-keys/{id}` | Remove key |
| `POST` | `/api/v1/settings/api-keys/test` | Test key |
| `GET` | `/api/v1/security/audit-logs` | Audit logs |
| `GET` | `/api/v1/security/tokens` | Active tokens |
| `POST` | `/api/v1/security/tokens` | Issue token |
| `POST` | `/api/v1/security/tokens/{jti}/rotate` | Rotate token |

---

## Team

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/team/members` | List members |
| `POST` | `/api/v1/team/members/invite` | Invite member |
| `PATCH` | `/api/v1/team/members/{id}/role` | Update role |
| `DELETE` | `/api/v1/team/members/{id}` | Remove member |
| `POST` | `/api/v1/team/members/accept-invite/{token}` | Accept invite |

---

## Templates

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/templates` | List agent templates |
| `GET` | `/api/v1/templates/{id}` | Get template |
| `POST` | `/api/v1/templates/seed` | Seed default templates |

---

## 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

| Header | Description |
|--------|-------------|
| `X-Payment` | Base64-encoded payment payload (amount, currency, payer wallet) |
| `X-Payment-Response` | Returned by server with settlement proof |

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/v1/cloud/x402/verify` | Verify an x402 payment header |
| `POST` | `/api/v1/cloud/x402/settle` | Settle a verified payment |
| `GET` | `/api/v1/cloud/x402/rates` | Current 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:

```json
{
  "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

| Guard | Default | Description |
|-------|---------|-------------|
| Single payment cap | $10.00 | Maximum per-transaction amount |
| Period spending limit | $100.00/month | Maximum spend per billing period |
| Balance check | — | Transaction rejected if balance insufficient |

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/v1/cloud/x402/wallets` | Create wallet for agent |
| `GET` | `/api/v1/cloud/x402/wallets/{agent_id}` | Get wallet balance and limits |
| `POST` | `/api/v1/cloud/x402/wallets/{agent_id}/fund` | Fund wallet with USDC |
| `POST` | `/api/v1/cloud/x402/wallets/{agent_id}/withdraw` | Withdraw from wallet |
| `PUT` | `/api/v1/cloud/x402/wallets/{agent_id}/limits` | Update spending limits |
| `GET` | `/api/v1/cloud/x402/wallets/{agent_id}/transactions` | Transaction history |

### Create Wallet

```http
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:

```json
{
  "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

```http
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

```http
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

| Recipient | Share | Description |
|-----------|-------|-------------|
| Tool owner | 90% | Developer who published the tool |
| Platform | 5% | AINative platform fee |
| Referrer | 5% | Agent/user who referred the caller (goes to platform if none) |

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/cloud/x402/marketplace/revenue` | Revenue breakdown for authenticated user |
| `GET` | `/api/v1/cloud/x402/marketplace/settlement` | Settlement status and pending earnings |
| `POST` | `/api/v1/cloud/x402/marketplace/withdraw` | Withdraw settled earnings |
| `GET` | `/api/v1/cloud/x402/marketplace/withdrawals` | Withdrawal history |

### Revenue Breakdown

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

Response:

```json
{
  "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

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

{
  "amount_usd": 100.0
}
```

Response:

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

---

## Health & Metrics

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health` | Service health |
| `GET` | `/metrics` | Prometheus metrics |
| `GET` | `/rate-limit-status` | Rate limit status |
| `GET` | `/api/v1/db/health` | DB health |
| `GET` | `/api/v1/db/pool-stats` | DB pool stats |
| `GET` | `/api/v1/metrics` | App metrics |