Quickstart

This guide takes you from zero to a first policy-gated USDC payment in about five minutes. You bring your own agent — built in any framework — and Canopy adds the policy, treasury, and visibility layer around it.

Already running an MCP-aware agent? If your agent runs in Claude Agent SDK, Claude Desktop, Cursor, Cline, or Windsurf, skip the SDK install and follow the MCP setup instead — one config block, zero code. Steps 1–3 below still apply.

1. Sign up and fund your treasury

Create an account at trycanopy.ai. Once your org is provisioned, the dashboard shows your treasury address — the same address on Base and Tempo. Fund it with USDC on Base (for x402 paywalls) or USDC.e on Tempo (for MPP paywalls) from any wallet or exchange.

Canopy supports USDC on Base and USDC.e on Tempo. Other tokens or networks are not usable.

2. Connect your agent in the dashboard

This step is where you tell Canopy about the agent you've already built (or are about to build). It doesn't replace your agent — it creates a Canopy-side record that pairs your agent with a spending policy and a credential.

In the dashboard, go to Agents → Connect agent. Give it a name. Pick (or create) a policy with a spend cap, optional recipient allowlist, and approval threshold. Click Create agent.

The dashboard shows you an install modal with framework-specific snippets. Keep it open — you'll come back to verify the connection once your agent code is wired up.

3. Copy your credentials

The fastest path is the Canopy CLI — it walks you through browser-based consent and writes credentials + MCP client configs in one shot:

npx @canopy-ai/sdk connect

Opens your browser, you pick an agent, and the CLI writes ~/.config/canopy/credentials plus merges a canopy MCP server entry into any installed clients (Claude Code, Cursor, Claude Desktop, Windsurf, Cline, VS Code, Zed). Pass --no-write to see what it'd do without writing anything.

If you'd rather paste manually, you need two things:

• Org API key (ak_live_…) — from Settings → API Keys. Click Create, copy the key once. Test mode keys (ak_test_…) are safe for development.
• Agent ID (agt_…) — visible on the agent's detail page or in the install modal you just opened.

Store both as environment variables:

CANOPY_API_KEY=ak_live_xxxxxxxxxxxxxxxx
CANOPY_AGENT_ID=agt_xxxxxxxx

4. Install the SDK

Pick your language:

npm install @canopy-ai/sdk

pip install canopy-ai

5. Make a payment

import { Canopy } from "@canopy-ai/sdk";
 
const canopy = new Canopy({
  apiKey: process.env.CANOPY_API_KEY!,
  agentId: process.env.CANOPY_AGENT_ID!,
});
 
const result = await canopy.pay({
  to: "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97", // any 0x… recipient
  amountUsd: 0.10,
});
 
switch (result.status) {
  case "allowed":
    console.log("paid:", result.txHash);
    break;
  case "pending_approval":
    const decided = await canopy.waitForApproval(result.approvalId);
    console.log("decision:", decided.status);
    break;
  case "denied":
    console.log("denied:", result.reason);
    break;
}

import os
from canopy_ai import Canopy
 
canopy = Canopy(
    api_key=os.environ["CANOPY_API_KEY"],
    agent_id=os.environ["CANOPY_AGENT_ID"],
)
 
result = canopy.pay(to="0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97", amount_usd=0.10)
 
if result["status"] == "allowed":
    print("paid:", result["tx_hash"])
elif result["status"] == "pending_approval":
    decided = canopy.wait_for_approval(result["approval_id"])
elif result["status"] == "denied":
    print("denied:", result["reason"])

pay() returns a discriminated union — never throws on a policy outcome. HTTP and network failures still throw so your agent can distinguish infrastructure problems from policy decisions.

6. Confirm the connection

Run your code once. The dashboard's install modal switches to agent connected as soon as Canopy receives your first request. You can also call canopy.ping() on startup to verify your credentials before any payments fire.

Where to go next

• Connect your agent — framework-specific snippets (Claude Agent SDK, Vercel AI, LangGraph, Anthropic, OpenAI Agents, MCP, ...)
• Payment outcomes — what allowed, pending_approval, and denied mean and how to handle each
• Policies — caps, allowlists, approval thresholds