Authentication

Bearer Token

All Unwall API requests require a bearer token in the Authorization header. Tokens are project-scoped and prefixed with aw_live_.

curl https://api.unwall.xyz/v1/balance \
  -H "Authorization: Bearer aw_live_xxxxxxxxxxxx"

Tokens are SHA-256 hashed before storage — the plaintext value is never saved on our servers. Each token belongs to exactly one project and can be revoked instantly from the dashboard.

Permissions

Tokens carry independent permission scopes. Only grant the permissions your agent actually needs.

Permission	Grants Access To
`read`	`GET /v1/balance`, `GET /v1/transactions`, `GET /v1/stablecoin/address`
`pay`	`POST /v1/pay` (fiat + USDC rails), `POST /v1/usdc/transfer`, `POST /v1/payments`
`x402`	`POST /v1/pay` (x402 rail), `POST /v1/x402/pay`

When creating a token, select only the permissions required:

curl -X POST https://api.unwall.xyz/dashboard/projects/PROJECT_ID/tokens \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "read-only-monitor",
    "permissions": ["read"]
  }'

If a token lacks the required permission for an endpoint, the API returns 403 Forbidden with a message indicating which permission is missing.

Rate Limits

Agent API tokens are rate-limited to 100 requests per minute using a sliding window. When the limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

{
  "detail": "Rate limit exceeded. Try again in 12 seconds."
}

Error Responses

Status Code	Meaning	When It Happens
`401 Unauthorized`	Invalid or missing token	The `Authorization` header is absent, malformed, or contains a revoked/invalid token.
`403 Forbidden`	Insufficient permissions	The token is valid but does not have the required permission scope for the endpoint.
`429 Too Many Requests`	Rate limited	The token has exceeded 100 requests per minute. Check the `Retry-After` header.

Example error response

{
  "detail": "Token does not have the required permission: pay"
}

Security Best Practices

Store tokens in environment variables

Never hard-code tokens in source code or commit them to version control. Use environment variables or a secrets manager like AWS Secrets Manager, HashiCorp Vault, or your platform’s built-in secret store.

Use least-privilege permissions

Only grant the permissions your agent actually needs. A monitoring agent should have read only. A payment agent might need read + pay. Only grant x402 to agents that call x402-enabled APIs.

Rotate tokens regularly

Create new tokens and revoke old ones on a regular cadence. You can have multiple active tokens per project, making zero-downtime rotation straightforward.

Set token expiry

When creating tokens, set an expiration date for short-lived use cases. Expired tokens are automatically rejected without needing manual revocation.

Getting Started

Core Concepts

Guides

Security

Authentication

Bearer Token

Permissions

Rate Limits

Error Responses

Example error response

Security Best Practices

​Bearer Token

​Permissions

​Rate Limits

​Error Responses

​Example error response

​Security Best Practices

Bearer Token

Permissions

Rate Limits

Error Responses

Example error response

Security Best Practices