> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentwallex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 参考概览

> AgentWallex REST API 的基础 URL、认证、分页和错误约定。

## 基础 URL

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

<Note>
  开发和测试时使用沙盒 URL。仅在准备好使用真实资金交易时切换到生产环境。
</Note>

## 认证

所有 API 请求必须包含以下认证头部之一：

| 方式         | 头部              | 示例                                    |
| ---------- | --------------- | ------------------------------------- |
| API 密钥     | `X-API-Key`     | `X-API-Key: awx_your_api_key`         |
| JWT Bearer | `Authorization` | `Authorization: Bearer eyJhbGciOi...` |

```bash theme={null}
# API key authentication
curl -X GET https://api.agentwallex.com/api/v1/agents \
  -H "X-API-Key: awx_your_api_key"

# JWT authentication
curl -X GET https://api.agentwallex.com/api/v1/agents \
  -H "Authorization: Bearer eyJhbGciOi..."
```

请参阅[身份认证](/zh/introduction/authentication)了解获取和管理凭证的完整详情。

## 分页

所有列表端点支持以下查询参数进行分页：

| 参数          | 默认值 | 最大值 | 说明         |
| ----------- | --- | --- | ---------- |
| `page_num`  | 1   | --  | 页码（从 1 开始） |
| `page_size` | 20  | 100 | 每页条目数      |

响应格式：

```json theme={null}
{
  "data": [],
  "total": 42,
  "has_more": true
}
```

## 错误约定

所有错误遵循一致的格式：

```json theme={null}
{
  "code": "invalid_request",
  "type": "invalid_request_error",
  "message": "human readable error description"
}
```

### 错误类型

| 类型                      | HTTP 状态码 | 说明       |
| ----------------------- | -------- | -------- |
| `invalid_request_error` | 400      | 请求体或参数无效 |
| `authentication_error`  | 401      | 凭证缺失或无效  |
| `authorization_error`   | 403      | 权限不足     |
| `not_found_error`       | 404      | 资源不存在    |
| `rate_limit_error`      | 429      | 超过速率限制   |
| `internal_error`        | 500      | 服务器端错误   |

请参阅[错误处理](/zh/guides/error-handling)了解详细的错误处理指南。

## API 分区

<CardGroup cols={2}>
  <Card title="代理" icon="robot" href="/zh/api-reference/agents-create">
    创建和管理 AI 代理钱包。
  </Card>

  <Card title="交易" icon="arrow-right-arrow-left" href="/zh/api-reference/transactions-create">
    发送支付和查询交易历史。
  </Card>

  <Card title="策略" icon="shield-check" href="/zh/api-reference/policies">
    配置消费限额和访问控制。
  </Card>

  <Card title="Webhooks" icon="bell" href="/zh/api-reference/webhooks">
    注册和管理 Webhook 端点。
  </Card>

  <Card title="x402 支付" icon="credit-card" href="/zh/api-reference/x402-pay">
    触发 x402 微支付协商。
  </Card>

  <Card title="x402 会话" icon="clock" href="/zh/api-reference/x402-sessions">
    管理 x402 会话预算。
  </Card>
</CardGroup>