# Owner Controls for Agent Wallets: Approve, Deny, Suspend — Never Sign

## Summary

AgentBadge owner controls gate whether a payment broadcast is honored as paid — they never sign or broadcast on the agent's behalf. Four controls sit on top of the spending envelope: velocity caps, an approval threshold that parks payments for a human signature, a suspend/resume kill-switch evaluated before every other check, and a per-kind allowlist. Proven live on Arc testnet October 5, 2026 (velocity deny → hold → approve → settle → suspend → resume → kind deny, full audit trail).

## The Four Controls

- **Velocity** — `maxTxPerHour` / `maxAmountPerHour` rolling windows → `402 velocity_tx | velocity_amount` with `used`, `limit`, `resetAt`, `windowSec`
- **Approval hold** — spend above `approvalAboveUsd` parks the intent → `402 approval_required` (`approvalId`, `expiresAt`); signed `approve` mints a single-use permit matched on amount + kind + endpoint; retry settles
- **Kill-switch** — `POST suspend` runs before all other checks → every payment returns `spend_suspended`; `resume` restores
- **Allow-kinds** — `allowedKinds` allowlist; off-list kinds get `kind_not_allowed` with attempted kind + allowlist echoed

## Owner Control API

| Action | Endpoint |
|--------|----------|
| Set/replace envelope | `PATCH /api/wallets/:address/envelope` (full-object replace, not merge) |
| List pending approvals | `GET /api/wallets/:address/approvals?status=pending` |
| Approve / reject parked intent | `POST /api/wallets/:address/approvals/:id/approve` / `.../reject` |
| Suspend / resume | `POST /api/wallets/:address/suspend` / `.../resume` |
| Signed audit feed | `GET /api/wallets/:address/audit` |

Control calls use EIP-191 signed headers: `x-wallet`, `x-sig`, `x-timestamp` over a pathname-only challenge (`wallet|method|path|timestamp`).

## Deny Codes

`velocity_amount`, `velocity_tx`, `approval_required`, `approval_queue_full`, `spend_suspended`, `kind_not_allowed`, `spend_cap` — all 402s carry a machine-readable `denied` field the agent can act on.

## Key Facts (dogfood-verified 2026-10-05)

- **Custody boundary:** control plane admits/denies settlement; agent wallet keeps the key — worst-case breach is denial of service, not spend
- **Permit is single-shot:** approve → one settlement of that exact payment, then consumed
- **Queue bounded:** overflow → `approval_queue_full`; approvals expire on their own (`expiresAt` ~1h)
- **PATCH replaces:** sending a partial envelope silently drops `approvalAboveUsd` — always send the full object
- **Case-insensitive wallets:** parked approvals are stored lowercase; lookups must `COLLATE NOCASE` (fixed during this dogfood)
- **Audit complete:** `spend.velocity_denied`, `approval.requested`/`decided`/`consumed`, `wallet.suspended`/`suspended_deny`/`resumed`, `spend.kind_denied`
- **Repro:** `scripts/agent-wallet-controls-dogfood.mts` — self-registers, walks all four controls, verifies audit

## Links

- Blog article: https://agentbadge.xyz/blog/arc-c13-owner-controls
- Wallets console: https://agentbadge.xyz/wallets
- Arc testnet explorer: https://testnet.arcscan.app



    <section class="mt-8 rounded-xl border border-emerald-800/30 bg-slate-900/50 p-6">
      <h3 class="text-lg font-bold text-slate-100">Relevant Engineering Capabilities</h3>
      <p class="mt-1 text-sm text-slate-400">The AgentBadge team can help with what you're reading about.</p>
      <div class="mt-4 grid gap-3">
        
        <div class="rounded-lg border border-slate-700 bg-slate-800/50 p-4">
          <div class="flex items-center justify-between">
            <h4 class="text-sm font-semibold text-emerald-400">AI Agent Architecture</h4>
            <span class="text-xs text-slate-400">Confidence: 0.93</span>
          </div>
          <p class="mt-1 text-xs text-slate-400">Design and implementation of AI agent infrastructure, agent APIs, machine-readable interfaces, and agent tooling.
</p>
          <div class="mt-2 flex items-center gap-3 text-xs text-slate-500">
            <span>People: Paul</span>
            <span>Status: VERIFIED</span>
          </div>
        </div>
        <div class="rounded-lg border border-slate-700 bg-slate-800/50 p-4">
          <div class="flex items-center justify-between">
            <h4 class="text-sm font-semibold text-emerald-400">Backend Development</h4>
            <span class="text-xs text-slate-400">Confidence: 0.92</span>
          </div>
          <p class="mt-1 text-xs text-slate-400">Node.js, NestJS, PostgreSQL, Redis, REST APIs, and event-driven systems.
</p>
          <div class="mt-2 flex items-center gap-3 text-xs text-slate-500">
            <span>People: Paul</span>
            <span>Status: VERIFIED</span>
          </div>
        </div>
      </div>
      
        <div class="mt-3">
          <p class="text-xs text-slate-500 mb-1">Related services:</p>
          <div class="flex flex-wrap gap-2">
            <span class="text-xs rounded-full bg-slate-700 px-2 py-1 text-slate-300">AI Agent Consulting</span>
          </div>
        </div>
      <div class="mt-4">
        <a href="/agent-guide/team/capabilities" class="inline-flex items-center text-sm font-medium text-emerald-400 hover:text-emerald-300">
          View all capabilities →
        </a>
      </div>
    </section>