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

# API Overview

> Base URL, authentication, error handling, and conventions for the Unwall API.

## Base URL

All API requests are made to:

```
https://api.unwall.xyz
```

## Authentication

Authenticate every request by including your API token in the `Authorization` header:

```
Authorization: Bearer aw_live_xxxxxxxxxxxx
```

Tokens are scoped with granular permissions:

| Permission | Description                                        |
| ---------- | -------------------------------------------------- |
| `read`     | Read balances, transactions, and deposit addresses |
| `pay`      | Send payments via USDC, fiat, or unified pay       |
| `x402`     | Make x402 protocol payments to URLs                |

<Warning>
  Keep your API tokens secret. Do not expose them in client-side code or public repositories.
  If a token is compromised, rotate it immediately from the dashboard.
</Warning>

## Content Type

All requests and responses use JSON:

```
Content-Type: application/json
```

## Monetary Values

Unwall uses integer representations for all monetary values to avoid floating-point precision issues.

| Currency | Unit       | Example               |
| -------- | ---------- | --------------------- |
| USD      | Cents      | `5000` = \$50.00      |
| USDC     | Micro-USDC | `1000000` = 1.00 USDC |

## Pagination

List endpoints support pagination with `limit` and `offset` parameters.

<ParamField query="limit" type="integer" default="50">
  Number of results to return. Min 1, max 200.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip before returning.
</ParamField>

Paginated responses include:

<ResponseField name="has_more" type="boolean">
  Whether there are more results beyond the current page.
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of matching results.
</ResponseField>

## Idempotency

To safely retry requests without duplicating side effects, include an `idempotency_key` in the request body of any write operation.

<ParamField body="idempotency_key" type="string">
  A unique key to prevent duplicate operations. Alphanumeric characters plus `_`, `-`, `:`, and `.` are allowed. Max 255 characters.
</ParamField>

If a request with the same idempotency key has already been processed, the original response is returned.

<Tip>
  Always include an idempotency key when sending payments from automated systems. Use a deterministic key derived from your application state (e.g., invoice number, order ID).
</Tip>

## Rate Limits

API requests are rate-limited to **100 requests per minute** per token.

When the rate limit is exceeded, the API returns HTTP `429 Too Many Requests` with a `Retry-After` header indicating how many seconds to wait before retrying.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 12
```

## Error Format

All errors return a JSON object with a `detail` field containing a human-readable error message:

```json theme={null}
{
  "detail": "Human-readable error message"
}
```

## Status Codes

| Code  | Description                                                  |
| ----- | ------------------------------------------------------------ |
| `200` | OK -- Request succeeded                                      |
| `201` | Created -- Resource created successfully                     |
| `400` | Bad Request -- Invalid parameters or missing required fields |
| `401` | Unauthorized -- Missing or invalid API token                 |
| `403` | Forbidden -- Token lacks the required permission             |
| `404` | Not Found -- Resource does not exist                         |
| `429` | Too Many Requests -- Rate limit exceeded                     |
| `502` | Bad Gateway -- Upstream service error (retry with backoff)   |