Issuing Agent Mandates
Configure per-call ceilings, epoch budgets, category masks, and 1-slot revocation for autonomous agents.
Why mandates replace hot wallets
Instead of funding an agent's own wallet, the Ring sponsor mints an on-chain AuthorityMandate PDA bound to (privacy_ring, agent_pubkey, version). The agent signs lock_sealed_402 with its delegated Ed25519 key while kalo_protocol enforces spending bounds, category permissions, expiry, and revocation on every call.
Service category bitmask
Each registered provider declares a single service_category bit. A mandate's category_mask is the bitwise OR of every category the agent is allowed to pay:
| Bit | Key | Label |
|---|---|---|
1 | inference | AI Inference |
2 | market_data | Market Data |
4 | research | Private Research |
8 | execution | Execution & Routing |
16 | storage | Encrypted Storage |
For example, categoryMask: 3 (1 | 2) allows AI Inference and Market Data while rejecting Private Research, Execution, and Storage. The maximum combined mask is 31.
Step 1: Issue a mandate
In the web console
- Open Authority Mandates.
- Select a funded
PrivacyRingand click Issue mandate. - Enter the agent's Ed25519 public key, a human-readable label (1 to 64 characters),
perCallCap,epochBudget,epochDurationSec(60 seconds to 30 days), allowed service categories, and an expiry date. - Sign
issue_mandatewith the Ring owner wallet.
Via the REST API
const res = await fetch('http://127.0.0.1:41202/v1/mandates/build', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
owner: sponsorPubkey,
ringAddress,
agentPubkey,
label: 'Alpha Research Bot',
perCallCap: '250000', // 0.25 USDC (6 decimals)
epochBudget: '50000000', // 50.00 USDC per epoch
epochDurationSec: 86_400, // 24 hours
categoryMask: 3, // AI Inference (1) + Market Data (2)
expiresAt: new Date(Date.now() + 7 * 86_400_000).toISOString(),
}),
})
const built = await res.json()
// built.derivedAddresses.mandateAddress -> AuthorityMandate PDAValidation rules enforced both by the API and on-chain in issue_mandate:
perCallCap > 0andepochBudget >= perCallCapepochDurationSec >= 60(API cap:2,592,000seconds / 30 days)categoryMaskbetween1and31expiresAtstrictly in the future (expires_at > clock.unix_timestamp)
Step 2: Inspect active mandates and epoch usage
Query GET /v1/mandates?ring=<ringAddress>&status=active to inspect epochSpent, epochBudget, epochDurationSec, version, and revoked.
When an agent calls lock_sealed_402 after epoch_start_ts + epoch_duration_sec, the on-chain program automatically resets epoch_spent = 0 and advances epoch_start_ts = clock.unix_timestamp before checking epoch_spent + amount <= epoch_budget.
Step 3: Rotate or revoke in one slot
Mandates are versioned by (privacy_ring, agent_pubkey, version). To tighten or expand bounds, issue a new version (the API increments version automatically) and revoke the old one.
To revoke immediately:
- In Authority Mandates, click Revoke mandate on the active row, or call
POST /v1/mandates/:address/revoke/build:
const res = await fetch(`http://127.0.0.1:41202/v1/mandates/${mandateAddress}/revoke/build`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ owner: sponsorPubkey }),
})Once revoke_mandate confirms, mandate.revoked is true permanently. Any lock_sealed_402 referencing that PDA reverts immediately with MandateRevoked (6005).
Common failures
| Error | HTTP / Program code | Cause |
|---|---|---|
InvalidMandateBounds | 400 / 6004 | per_call_cap == 0, epoch_budget < per_call_cap, epoch_duration_sec < 60, or category_mask == 0 |
MandateRevoked | 403 / 6005 | Mandate was already revoked |
MandateExpired | 403 / 6006 | clock.unix_timestamp >= expires_at |
CategoryForbidden | 403 / 6010 | (mandate.category_mask & enclave.service_category) == 0 |
CapExceeded | 403 / 6011 | amount > per_call_cap or epoch_spent + amount > epoch_budget |
Next step
Use your active mandate to settle an attested HTTP 402 call in Sealed 402 Console or read Gating an API with HTTP 402 if you operate a provider endpoint.