Skip to main content

​
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.
PermissionGrants Access To
readGET /v1/balance, GET /v1/transactions, GET /v1/stablecoin/address
payPOST /v1/pay (fiat + USDC rails), POST /v1/usdc/transfer, POST /v1/payments
x402POST /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 CodeMeaningWhen It Happens
401 UnauthorizedInvalid or missing tokenThe Authorization header is absent, malformed, or contains a revoked/invalid token.
403 ForbiddenInsufficient permissionsThe token is valid but does not have the required permission scope for the endpoint.
429 Too Many RequestsRate limitedThe 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

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.
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.
Create new tokens and revoke old ones on a regular cadence. You can have multiple active tokens per project, making zero-downtime rotation straightforward.
When creating tokens, set an expiration date for short-lived use cases. Expired tokens are automatically rejected without needing manual revocation.