Overview
The Agentic Wallet API uses API key-based authentication with scope-based access control. All requests must include a valid API key in the request headers.
Include your API key in every request:
Your API key for authentication
curl -H "x-api-key: your-api-key-here" \
http://localhost:3000/api/v1/wallets
Tenant identifier. Use * for wildcard access (if permitted by your API key).
curl -H "x-api-key: your-api-key-here" \
-H "x-tenant-id: tenant-123" \
http://localhost:3000/api/v1/wallets
Configuration
API keys are configured via environment variables:
Enable/Disable Authentication
API_GATEWAY_ENFORCE_AUTH=true # Set to false to disable auth (development only)
key:tenant:scope1,scope2,scope3
API_GATEWAY_API_KEYS="dev-api-key:*:all;prod-key:tenant-1:wallets,transactions"
key: The actual API key stringtenant: Tenant ID or * for all tenantsscopes: Comma-separated list of scopes or all for full access
Scopes
The following scopes control access to API resources:
| Scope | Description |
|---|
wallets | Create and manage wallets |
transactions | Create and manage transactions |
policies | Create and evaluate policies |
agents | Create and manage agents |
protocols | Access protocol adapters |
risk | Manage risk configurations |
strategy | Backtest and paper trading |
treasury | Treasury allocation operations |
audit | Access audit events and metrics |
mcp | MCP tool access |
all | Full access to all resources |
Development key with full access:Production key with limited scopes:prod-key-abc123:tenant-1:wallets,transactions,policies
agent-key-def456:tenant-2:wallets,transactions,agents,protocols
Example Configurations
Development Setup
API_GATEWAY_ENFORCE_AUTH=true
API_GATEWAY_API_KEYS="dev-api-key:*:all"
API_GATEWAY_RATE_LIMIT_PER_MINUTE=120
Production Multi-Tenant
API_GATEWAY_ENFORCE_AUTH=true
API_GATEWAY_API_KEYS="prod-key-1:tenant-a:wallets,transactions;prod-key-2:tenant-b:all;admin-key:*:all"
API_GATEWAY_RATE_LIMIT_PER_MINUTE=60
Rate Limiting
Rate limits are applied per API key:
API_GATEWAY_RATE_LIMIT_PER_MINUTE=120 # Default: 120 requests/minute
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1709899260
Error Responses
Missing API Key
curl http://localhost:3000/api/v1/wallets
{
"status": "failure",
"errorCode": "VALIDATION_ERROR",
"failedAt": "gateway",
"stage": "gateway",
"error": "Missing x-api-key header"
}
Invalid API Key
curl -H "x-api-key: invalid-key" \
http://localhost:3000/api/v1/wallets
{
"status": "failure",
"errorCode": "VALIDATION_ERROR",
"failedAt": "gateway",
"stage": "gateway",
"error": "Invalid API key"
}
Insufficient Scope
curl -H "x-api-key: limited-key" \
http://localhost:3000/api/v1/policies
{
"status": "failure",
"errorCode": "VALIDATION_ERROR",
"failedAt": "gateway",
"stage": "gateway",
"error": "Insufficient scope: requires 'policies'"
}
Rate Limit Exceeded
Response (429 Too Many Requests):
{
"status": "failure",
"errorCode": "VALIDATION_ERROR",
"failedAt": "gateway",
"stage": "gateway",
"error": "Rate limit exceeded"
}
Security Best Practices
Never expose API keys in client-side code, version control, or public repositories.
Use environment variables or secure secret management systems to store API keys.
- Use separate API keys for different environments (dev, staging, production)
- Apply principle of least privilege - grant only required scopes
- Rotate API keys regularly
- Monitor API key usage via audit logs
- Use tenant-specific keys for multi-tenant deployments
- Set appropriate rate limits based on usage patterns
Testing Authentication
Verify your API key works:
curl -H "x-api-key: dev-api-key" \
http://localhost:3000/health
{
"status": "ok",
"timestamp": "2026-03-08T12:00:00.000Z"
}