REST API 参考

基础 URL

沙盒环境: https://api-sandbox.agentwallex.com/api/v1
生产环境: https://api.agentwallex.com/api/v1

认证方式

AgentWallex 当前支持两种认证：

• X-API-Key（SDK / 服务端集成）
• Authorization: Bearer <access_token>（Web 控制台 OAuth 会话）

# API Key 模式
X-API-Key: awx_your_api_key
 
# JWT 模式
Authorization: Bearer eyJhbGciOi...

OAuth 端点

启动 Google OAuth（服务端授权码流程）

GET /auth/google/redirect

OAuth 回调

GET /auth/google/callback

交换一次性 code 为 Token

POST /auth/exchange

{
  "exchange_code": "one_time_code"
}

刷新 Token

POST /auth/refresh

{
  "refresh_token": "..."
}

退出登录（JWT）

POST /auth/logout

分页契约

所有列表接口使用：

• page_num（默认 1）
• page_size（默认 20，最大 100）

返回格式：

{
  "data": [],
  "total": 42,
  "has_more": true
}

Agent

创建 Agent

POST /agents

{
  "agent_name": "research-bot",
  "agent_description": "市场研究自动化 Agent",
  "chain": "eip155:84532",
  "metadata": "{\"team\":\"growth\"}"
}

列表

GET /agents?page_num=1&page_size=20&status=active&chain=eip155:84532

详情

GET /agents/:id

更新

PUT /agents/:id

更新状态

PUT /agents/:id/status

{
  "status": "inactive"
}

Agent 事件

GET /agents/:id/events?page_num=1&page_size=20

删除

DELETE /agents/:id

交易

创建交易

POST /transactions

{
  "agent_id": "agent_uuid",
  "direction": "outbound",
  "type": "transfer",
  "from_address": "0x1234...",
  "to_address": "0xabcd...",
  "amount": "10.5",
  "token": "USDC",
  "chain": "eip155:84532",
  "memo": "service payment"
}

列表

GET /transactions?page_num=1&page_size=20&agent_id=agent_uuid&status=confirmed

详情

GET /transactions/:id

策略

POST /policies
GET  /policies
GET  /policies/:id
PUT  /policies/:id
DELETE /policies/:id

策略模板

GET /policy-templates
POST /policy-templates
GET /policy-templates/:id
PUT /policy-templates/:id
DELETE /policy-templates/:id

API Keys（JWT）

GET /api-keys
POST /api-keys
GET /api-keys/:id
DELETE /api-keys/:id

Webhooks

GET /webhooks
POST /webhooks
GET /webhooks/:id
PUT /webhooks/:id
DELETE /webhooks/:id
GET /webhooks/:id/deliveries
POST /webhooks/:id/test

Dashboard 与审计

GET /dashboard/stats
GET /audit-logs?page_num=1&page_size=20

x402 受保护端点

POST /x402/pay
POST /x402/check

POST /x402/sessions
GET  /x402/sessions
GET  /x402/sessions/:id
POST /x402/sessions/:id/pay
DELETE /x402/sessions/:id

GET  /x402/balances
POST /x402/balances/deposit-address
POST /x402/balances/withdraw

POST /x402/endpoints
GET  /x402/endpoints
GET  /x402/endpoints/:id
PUT  /x402/endpoints/:id
DELETE /x402/endpoints/:id

POST /x402/settle/trigger
GET  /x402/settle/batches
GET  /x402/settle/batches/:id
GET  /x402/ledger

示例：x402 支付

{
  "agent_id": "agent_uuid",
  "target_url": "https://paid-api.example.com/v1/data",
  "session_id": "optional_session_uuid",
  "chain": "eip155:84532"
}

x402 公共端点

POST /x402/facilitator/verify
POST /x402/facilitator/settle
GET  /x402/facilitator/supported
GET  /x402/fees/tiers
ANY  /x402/gw/:agent_id/*path

x402 费率阶梯（公开）

GET /x402/fees/tiers

{
  "tiers": [
    { "min_amount": "0", "max_amount": "10", "percentage": "2.0" },
    { "min_amount": "10", "max_amount": "100", "percentage": "1.0" },
    { "min_amount": "100", "max_amount": "1000", "percentage": "0.5" },
    { "min_amount": "1000", "max_amount": "", "percentage": "0.25" }
  ]
}

错误契约

所有错误统一返回：

{
  "code": "invalid_request",
  "type": "invalid_request_error",
  "message": "可直接展示给用户的错误信息"
}

常见错误类型：

• invalid_request_error
• authentication_error
• authorization_error
• not_found_error
• rate_limit_error
• internal_error