REST API Reference

HTTP endpoints for custom integrations with AgentWallex

Base URL

Sandbox:    https://api-sandbox.agentwallex.com/api/v1
Production: https://api.agentwallex.com/api/v1

Authentication

AgentWallex currently supports two auth modes:

X-API-Key (SDK/server integrations)
Authorization: Bearer <access_token> (Web app and OAuth sessions)

# API key mode
X-API-Key: awx_your_api_key
 
# JWT mode
Authorization: Bearer eyJhbGciOi...

OAuth Endpoints

Start Google OAuth (server-side flow)

GET /auth/google/redirect

OAuth Callback

GET /auth/google/callback

Exchange One-Time Code for Tokens

POST /auth/exchange

{
  "exchange_code": "one_time_code"
}

Refresh Token

POST /auth/refresh

{
  "refresh_token": "..."
}

Logout (JWT)

POST /auth/logout

Pagination Contract

All list endpoints use:

page_num (default 1)
page_size (default 20, max 100)

Response format:

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

Agents

Create Agent

POST /agents

{
  "agent_name": "research-bot",
  "agent_description": "Market research automation agent",
  "chain": "eip155:84532",
  "metadata": "{\"team\":\"growth\"}"
}

List Agents

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

Get Agent

GET /agents/:id

Update Agent

PUT /agents/:id

Update Agent Status

PUT /agents/:id/status

{
  "status": "inactive"
}

List Agent Events

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

Delete Agent

DELETE /agents/:id

Transactions

Create Transaction

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"
}

List Transactions

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

Get Transaction

GET /transactions/:id

Policies

Create Policy

POST /policies

List Policies

GET /policies?page_num=1&page_size=20&agent_id=agent_uuid

Get/Update/Delete Policy

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

Policy Templates

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 & Audit

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

x402 Protected Endpoints

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

Example: x402 Pay

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

x402 Public Endpoints

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

x402 Fee Tiers (Public)

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" }
  ]
}

Error Contract

All errors follow:

{
  "code": "invalid_request",
  "type": "invalid_request_error",
  "message": "human readable error"
}

Common error types:

invalid_request_error
authentication_error
authorization_error
not_found_error
rate_limit_error
internal_error