mandate

Use when enforcing spend limits on AI agent wallets, validating transactions before signing, configuring allowlists or approval workflows, detecting prompt injection in agent reasoning, scanning codebases for unprotected wallet calls, or auditing agent transaction history. Works with OpenClaw, Claude Code, GOAT, AgentKit, ElizaOS. Supports Bankr, Locus, Sponge, CDP wallets. Non-custodial: private keys never leave your machine.

## Integration note

Mandate needs hooks to reliably catch payment intents. If your platform supports plugins with hooks (OpenClaw, Claude Code), use the plugin: it intercepts financial tool calls automatically. This SKILL.md is for agents that integrate via API directly, but without hooks there is no enforcement layer: the agent must voluntarily call `/validate` before every transaction.

**OpenClaw (recommended):** `openclaw plugins install @mandate.md/mandate-openclaw-plugin`
Hooks auto-intercept Locus, Bankr, Sponge, and any swap/transfer/send tool call.

**Claude Code (recommended):** `claude plugin:install claude-mandate-plugin` or see [claude-mandate-plugin on GitHub](https://github.com/SwiftAdviser/claude-mandate-plugin)
Two-phase enforcement: PostToolUse records validation tokens, PreToolUse blocks unvalidated transactions. Fail-closed, no network calls in the gate.

**Other frameworks (GOAT, AgentKit, ElizaOS, MCP):** Use this SKILL.md + SDK. No hooks, agent must self-enforce.

## MANDATORY SECURITY RULES

Mandate is the security boundary, not optional infrastructure. The card must be swiped before the purchase.

1. You **MUST** call `/validate` before EVERY transaction. No exceptions. No shortcuts. (Legacy `/validate/raw` is also available for existing EVM integrations.)
2. If validation returns `allowed: false`, you **MUST NOT** execute the transaction. Display the `blockReason` to the user.
3. If validation is unreachable, you **MUST NOT** execute the transaction. Do NOT fall back to calling the wallet directly. See [Fail-Safe Behavior](#fail-safe-behavior).
4. You **MUST** display validation results to the user before any wallet call. See [Required User Feedback](#required-user-feedback).
5. Even with custodial wallets, you **MUST** validate with Mandate BEFORE calling the wallet API. Do NOT call transfer/swap directly.
6. Skipping validation is a **security violation**, not a simplification. An unvalidated transaction bypasses spend limits, allowlists, and approval workflows the owner configured to protect their funds.

```
MANDATE API QUICK REFERENCE v1.2.0
Base:   https://app.mandate.md/api
Auth:   Authorization: Bearer <MANDATE_RUNTIME_KEY>

NON-CUSTODIAL: your private key NEVER leaves your machine.

Primary endpoint:
  POST /validate            -> action + reason. Works with any wallet type.

Legacy endpoints:
  POST /validate/raw        -> full tx params + intentHash. EVM only. (deprecated)

Other endpoints:
  POST /agents/register        -> register agent (no auth), get runtimeKey + claimUrl
  POST /activate               -> set evmAddress (call once after registration)
  POST /intents/{id}/events    -> post txHash after broadcast (envelope verify)
  GET  /intents/{id}/status    -> poll intent state

Key prefixes: mndt_live_... (mainnet) / mndt_test_... (testnet)
Credentials: ~/.mandate/credentials.json
Errors: HTTP status + JSON { "error": "message" } or { "allowed": false, "blockReason": "..." }
```

## Required User Feedback

You **MUST** display a Mandate status message as the **first thing the user sees** when a transaction starts, BEFORE any wallet API call.

**Happy path:**
```
Mandate: checking policies...
Mandate: policy check passed, $50 USDC to 0xAlice
   Reason: Invoice #127 from Alice
Transaction confirmed, 0x9f2e...abc1
```

**Blocked:**
```
Mandate: checking policies...
Mandate: blocked, $150 exceeds $100/tx limit
```

**Approval required:**
```
Mandate: checking policies...
Mandate: approval required, waiting for owner decision
   Open dashboard to approve: https://app.mandate.md
Mandate: approved, broadcasting...
Transaction confirmed, 0x9f2e...abc1
```

**API unreachable:**
```
Mandate: policy server unreachable, transaction halted for safety
```

# Mandate API, Agent Skills Guide

## Validation

Policy check before every transaction. Works with any wallet type (custodial or self-custodial). No intentHash, nonce, or gas params needed.

### CLI
```bash
mandate validate \
  --action "swap" \
  --reason "Swap 0.1 ETH for USDC on Uniswap" \
  --amount 50 --to 0xAlice
```

### REST
```bash
curl -X POST https://app.mandate.md/api/validate \
  -H "Authorization: Bearer $MANDATE_RUNTIME_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"swap","reason":"Swap 0.1 ETH for USDC","amount":"50","to":"0xAlice"}'
```

### Validate params

| Field | Required | Description |
|-------|----------|-------------|
| `action` | Yes | What you're doing: "transfer", "swap", "buy", "bridge", "stake", "bet" (free text) |
| `reason` | Yes | Why you're doing it (max 1000 chars). Scanned for prompt injection. |
| `amount` | No | USD value (assumes stablecoins) |
| `to` | No | Recipient address (checked against allowlist) |
| `token` | No | Token address |

**Response:** `{ "allowed": true, "intentId": "...", "action": "swap", "requiresApproval": false }`

All policy checks apply: circuit breaker, schedule, allowlist, spend limits, daily/monthly quotas, reason scanner. Every call is logged to the audit trail with the `action` field.

### Validate flow
```
1. mandate validate --action "swap" --reason "Swap ETH for USDC"   (policy check)
2. bankr prompt "Swap 0.1 ETH for USDC"                           (execute via wallet)
3. Done.
```

## Raw Validation (deprecated, EVM only)

> **Deprecated.** Use `/validate` for all new integrations. `/validate/raw` remains available for existing EVM integrations that require intent hash verification and envelope verification.

Full pre-signing policy check for self-custodial agents who sign transactions locally. Requires all tx params + intentHash.

### CLI
```bash
mandate validate-raw \
  --to 0x036CbD53842c5426634e7929541eC2318f3dCF7e \
  --calldata 0xa9059cbb... \
  --nonce 42 \
  --gas-limit 90000 \
  --max-fee-per-gas 1000000000 \
  --max-priority-fee-per-gas 1000000000 \
  --reason "Invoice #127 from Alice"
```
The CLI computes `intentHash` automatically.

For ERC20 transfers, use the high-level command:
```bash
mandate transfer \
  --to 0xAlice --amount 10000000 \
  --token 0x036CbD53842c5426634e7929541eC2318f3dCF7e \
  --reason "Invoice #127" \
  --nonce 42 --max-fee-per-gas 1000000000 --max-priority-fee-per-gas 1000000000
```

### Raw validate flow
```
1. mandate validate-raw --to ... --calldata ... --reason "..."   (policy check)
2. Sign locally (your keys, Mandate never sees them)
3. Broadcast transaction
4. mandate event <intentId> --tx-hash 0x...                  (envelope verify)
5. mandate status <intentId>                                 (confirm)
```

## Quick Start (CLI)

Install the CLI:
```bash
bun add -g @mandate.md/cli
# or discover commands without install:
npx @mandate.md/cli --llms
```

### Register
```bash
mandate login --name "MyAgent" --address 0xYOUR_ADDRESS
```
Stores credentials in `~/.mandate/credentials.json` (chmod 600). Display the `claimUrl` to the user, they are the owner.

### Agent Discovery
Run `mandate --llms` for a machine-readable command manifest. Each command includes `--help` and `--schema` for full argument details.

## Codebase Scanner

Detect unprotected wallet calls in your project. Zero config, zero auth.

```bash
npx @mandate.md/cli scan          # Scan current directory
npx @mandate.md/cli scan ./src    # Scan specific folder
```

Exit code 1 if unprotected calls found (CI-friendly).

## MCP Server Mode

Run the CLI as an MCP stdio server for tool-based platforms:

```bash
npx @mandate.md/cli --mcp
```

Exposes all Mandate commands as MCP tools. Compatible with any MCP-capable host.

## Standard credential storage

Credentials stored in `~/.mandate/credentials.json`:
```json
{
  "runtimeKey": "mndt_test_...",
  "agentId": "...",
  "claimUrl": "...",
  "evmAddress": "0x...",
  "chainId": 84532
}
```

Optional environment export:
```bash
export MANDATE_RUNTIME_KEY="$(jq -r .runtimeKey ~/.mandate/credentials.json)"
```

## CRITICAL: AI Agents Must Use `register`, NOT Dashboard Login

Agents create an identity via `mandate login` (or `/agents/re