Canopy#

Canopy is a treasury wallet + per-agent policy gate. An org funds a treasury once, attaches a policy to each agent (spend cap, allowlist, approval threshold), and gives the agent the canopy_* MCP tools below. Canopy enforces the policy on every payment.

Setup#

After installing this skill, register the Canopy MCP server with OpenClaw. Replace the placeholders with your own values from the Canopy dashboard (Connect agent → Credentials):

bash

openclaw mcp set canopy '{
  "url": "https://mcp.trycanopy.ai/mcp",
  "transport": "streamable-http",
  "headers": {
    "Authorization": "Bearer YOUR_CANOPY_API_KEY",
    "X-Canopy-Agent-Id": "YOUR_CANOPY_AGENT_ID"
  }
}'

Or edit openclaw.json directly:

json

{
  "mcpServers": {
    "canopy": {
      "url": "https://mcp.trycanopy.ai/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_CANOPY_API_KEY",
        "X-Canopy-Agent-Id": "YOUR_CANOPY_AGENT_ID"
      }
    }
  }
}

Restart OpenClaw. The canopy_* tools become available immediately.

Verify with canopy_ping — it returns the resolved agent + org and a latency number.

Triggers#

Use Canopy when the user mentions:

• "pay", "transfer", "send $X to "
• "approve" / "deny" a pending payment
• "budget", "spend cap", "remaining budget"
• "paid API", "x402", "402 paywall"
• "find a paid service for …", "discover services"
• "agent wallet", "treasury"

Available tools#

ToolPurposecanopy_paySend a USD payment to an address. Subject to policy. Returns one of three outcomes (see below).canopy_previewDry-run policy evaluation without signing or charging. Same shape as canopy_pay plus dryRun: true.canopy_check_urlProbe an x402 / MPP URL and return the parsed offer plus a policy verdict. Cached 60s per (org, url).canopy_discover_servicesList paid services the agent can call. Filter by category and query.canopy_get_approval_statusPoll the current state of a pending approval.canopy_wait_for_approvalBlock until an approval is decided, max 60s. Use polling for longer waits.canopy_approveMark a pending approval as approved. Use only when the user has explicitly said yes in chat.canopy_denyMark a pending approval as denied. Use only when the user has explicitly said no in chat.canopy_get_budgetCap snapshot for the current rolling period ( capUsd, spentUsd, remainingUsd, periodResetsAt).canopy_pingVerify the API key + agent. Returns agent and org details plus latency.

Outcome model — canopy_pay, canopy_preview, canopy_check_url#

These tools never throw on policy. They always return a structured value with one of three status values:

allowed#

Payment went through (or would go through, for _preview / _check_url). Surface txHash (Base block-explorer hash) and costUsd to the user.

pending_approval#

Payment exceeded the agent's approval threshold. Fields you should use:

• approvalId — pass to canopy_approve / canopy_deny / canopy_wait_for_approval / canopy_get_approval_status.
• recipientName, recipientAddress, amountUsd, agentName, expiresAt — render these to the user when asking.
• chatApprovalEnabled — if false, calling canopy_approve / canopy_deny will fail. Tell the user to approve in the dashboard, optionally canopy_wait_for_approval to block.

If chatApprovalEnabled === true: ask the user "Approve $X to RecipientName?" then call canopy_approve(approval_id) or canopy_deny(approval_id) based on their reply.

denied#

Policy blocked it (cap exceeded, recipient/service not on allowlist, etc.). Surface the reason to the user. Do NOT retry with smaller amounts to evade the cap.

HTTP and network failures still throw normally — wrap calls in try/except as you would any tool call.

Safety rules#

• Always show the user recipientName + amountUsd before calling canopy_approve. Approvals exist precisely so a human sees the transaction details before money moves. Echoing them back confirms intent.
• Default to canopy_preview when the amount is dynamic or untrusted. Same shape as canopy_pay, no funds move. Use the verdict to decide whether to proceed.
• Never auto-approve. canopy_approve and canopy_deny are for handling explicit user replies in chat, not for the LLM to bypass the human-in-the-loop.
• Don't chunk a denied payment into smaller payments. If a denied outcome cites the spend cap, surface the cap to the user; suggest they raise it in the dashboard rather than working around it.
• Don't reference txHash until status === "allowed". It's null in other outcomes.
• Don't tight-loop canopy_get_approval_status. Use canopy_wait_for_approval (60s max) or accept that the dashboard owns the decision.

Quick examples#

User: "Pay 50 cents to 0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97" → canopy_pay({ to: "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97", amountUsd: 0.50 }). Surface txHash if allowed.

User: "How much do I have left to spend today?" → canopy_get_budget(). Render remainingUsd and periodResetsAt.

User: "Find paid orderbook data feeds" → canopy_discover_services({ category: "data", query: "orderbook" }). List services with policyAllowed: true first; mention any with policyAllowed: false only if the user asks why.

User: "Is paying https://feed.example/depth allowed?" → canopy_check_url({ url: "https://feed.example/depth" }). Return the verdict + amount + recipient name.

User (after a previous pending_approval): "Yes, approve it" → Confirm the recipient and amount you previously surfaced. Then canopy_approve({ approval_id: <approvalId> }).

Resources#

• Canopy dashboard
• MCP tools reference
• Payment outcomes
• Policies
• x402 protocol
• Connect MCP hosts