mandate

What this skill does

## 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/r