mandate-api

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: openclaw plugins install @mandate.md/mandate-openclaw-plugin (preferred, has hooks) Claude Code: claude --plugin-dir ./packages/claude-mandate-plugin (has hooks) Other frameworks: 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.
4. You MUST display validation results to the user before any wallet call. See 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.1.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": "..." }