Authentication
All policy endpoints require admin authentication via the x-admin-key header.
curl -H "x-admin-key: your-admin-key" https://api.example.com/admin/policy
Admin endpoints use a dedicated rate limiter: 30 requests per minute per IP.
Get All Agent Policies
curl -X GET https://api.example.com/admin/policy \
-H "x-admin-key: your-admin-key"
{
"success": true,
"policies": [
{
"agentId": "oracle",
"frozen": false,
"dailyLimitUsd": 1.0,
"perCallLimitUsd": 0.05,
"allowedEndpoints": ["/api/x402/oracle/"],
"allowedPayTo": ["0x1234..."],
"updatedAt": "2026-03-03T10:30:00.000Z",
"updatedBy": "[email protected]"
}
]
}
Whether the request succeeded
Array of agent policy objects
Agent identifier (oracle, scout, news, yield, tokenomics, nft, perp)
If true, agent is frozen and cannot accept requests
Maximum USD that can be spent on this agent per day
Maximum USD that can be spent per individual call
Endpoint path prefixes that are allowed for this agent
Allowlisted payment recipient addresses
ISO 8601 timestamp of last policy update
Admin user who last updated the policy
Get Single Agent Policy
curl -X GET https://api.example.com/admin/policy/oracle \
-H "x-admin-key: your-admin-key"
Agent ID (oracle, scout, news, yield, tokenomics, nft, perp)
{
"success": true,
"policy": {
"agentId": "oracle",
"frozen": false,
"dailyLimitUsd": 1.0,
"perCallLimitUsd": 0.05,
"allowedEndpoints": ["/api/x402/oracle/"],
"allowedPayTo": ["0x1234..."],
"updatedAt": "2026-03-03T10:30:00.000Z",
"updatedBy": "[email protected]"
}
}
Freeze/Unfreeze Agent
curl -X POST https://api.example.com/admin/policy/oracle/freeze \
-H "x-admin-key: your-admin-key" \
-H "x-admin-user: [email protected]" \
-H "Content-Type: application/json" \
-d '{
"frozen": true
}'
Agent ID to freeze/unfreeze
Admin API key for authentication
Optional admin user identifier for audit logging
Set to true to freeze the agent, false to unfreeze
Optional admin identifier (alternative to x-admin-user header)
{
"success": true,
"policy": {
"agentId": "oracle",
"frozen": true,
"dailyLimitUsd": 1.0,
"perCallLimitUsd": 0.05,
"allowedEndpoints": ["/api/x402/oracle/"],
"allowedPayTo": ["0x1234..."],
"updatedAt": "2026-03-03T10:35:00.000Z",
"updatedBy": "[email protected]"
}
}
When an agent is frozen, all incoming requests return HTTP 423 (Locked) with the message ” is frozen by policy”.
Update Agent Policy
curl -X PATCH https://api.example.com/admin/policy/oracle \
-H "x-admin-key: your-admin-key" \
-H "x-admin-user: [email protected]" \
-H "Content-Type: application/json" \
-d '{
"dailyLimitUsd": 5.0,
"perCallLimitUsd": 0.1,
"allowedEndpoints": ["/api/x402/oracle/price", "/api/x402/oracle/prices"],
"allowedPayTo": ["0x1234...", "0x5678..."]
}'
Optional admin user for audit trail
Freeze or unfreeze the agent
Maximum daily spend limit in USD. Must be >= 0.
Maximum per-call spend limit in USD. Must be >= 0.
Array of allowed endpoint path prefixes. Empty array blocks all endpoints.
Array of allowed payment recipient addresses (case-insensitive).
Admin identifier for audit logging (alternative to header)
{
"success": true,
"policy": {
"agentId": "oracle",
"frozen": false,
"dailyLimitUsd": 5.0,
"perCallLimitUsd": 0.1,
"allowedEndpoints": ["/api/x402/oracle/price", "/api/x402/oracle/prices"],
"allowedPayTo": ["0x1234...", "0x5678..."],
"updatedAt": "2026-03-03T10:40:00.000Z",
"updatedBy": "[email protected]"
}
}
Error Responses
{
"success": false,
"error": "Unauthorized"
}
{
"success": false,
"error": "Unsupported agentId: invalid-agent"
}
{
"success": false,
"error": "Database connection failed"
}
Policy Enforcement
Policies are enforced in the following order:
- Frozen check - If agent is frozen, return 423 immediately
- Endpoint allowlist - Request path must match an allowed prefix
- Per-call limit - Quoted price must not exceed perCallLimitUsd
- PayTo allowlist - Payment recipient must be in allowedPayTo array
- Daily limit - Total daily spend + reserved budget must not exceed dailyLimitUsd
Policy updates take effect immediately. Frozen agents will reject all in-flight requests.
Default Policies
When an agent is first initialized, it receives these default values:
- frozen:
false
- dailyLimitUsd:
1.0 (from X402_POLICY_DAILY_LIMIT_USD env var)
- perCallLimitUsd:
0.05 (from X402_POLICY_PER_CALL_LIMIT_USD env var)
- allowedEndpoints: Agent-specific route prefixes (e.g.,
/api/x402/oracle/)
- allowedPayTo: Agent’s seller address from configuration
- updatedBy:
"system-default"