Skip to main content

​
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:
PermissionDescription
readRead balances, transactions, and deposit addresses
paySend payments via USDC, fiat, or unified pay
x402Make x402 protocol payments to URLs
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.

​
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.
CurrencyUnitExample
USDCents5000 = $50.00
USDCMicro-USDC1000000 = 1.00 USDC

​
Pagination

List endpoints support pagination with limit and offset parameters.
​
limit
integer
default:"50"
Number of results to return. Min 1, max 200.
​
offset
integer
default:"0"
Number of results to skip before returning.
Paginated responses include:
​
has_more
boolean
Whether there are more results beyond the current page.
​
total_count
integer
Total number of matching results.

​
Idempotency

To safely retry requests without duplicating side effects, include an idempotency_key in the request body of any write operation.
​
idempotency_key
string
A unique key to prevent duplicate operations. Alphanumeric characters plus _, -, :, and . are allowed. Max 255 characters.
If a request with the same idempotency key has already been processed, the original response is returned.
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).

​
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: 
{
  "detail": "Human-readable error message"
}

​
Status Codes

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