Guides

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:

BitKeyLabel
1inferenceAI Inference
2market_dataMarket Data
4researchPrivate Research
8executionExecution & Routing
16storageEncrypted 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

  1. Open Authority Mandates.
  2. Select a funded PrivacyRing and click Issue mandate.
  3. 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.
  4. Sign issue_mandate with the Ring owner wallet.

Via the REST API

ts
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 PDA

Validation rules enforced both by the API and on-chain in issue_mandate:

  • perCallCap > 0 and epochBudget >= perCallCap
  • epochDurationSec >= 60 (API cap: 2,592,000 seconds / 30 days)
  • categoryMask between 1 and 31
  • expiresAt strictly 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:

  1. In Authority Mandates, click Revoke mandate on the active row, or call POST /v1/mandates/:address/revoke/build:
ts
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

ErrorHTTP / Program codeCause
InvalidMandateBounds400 / 6004per_call_cap == 0, epoch_budget < per_call_cap, epoch_duration_sec < 60, or category_mask == 0
MandateRevoked403 / 6005Mandate was already revoked
MandateExpired403 / 6006clock.unix_timestamp >= expires_at
CategoryForbidden403 / 6010(mandate.category_mask & enclave.service_category) == 0
CapExceeded403 / 6011amount > 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.

Confidential commerce infrastructure for autonomous software.

Shielded treasuries, scoped mandates, and receipt-bound HTTP 402 settlement on Solana L1.

Open consoleRead the docs