Canopy

Connect Python

canopy-ai is the official Python client. Python 3.10+. The library passes mypy --strict and uses httpx for transport.

Fast path: after Step 1, run npx @canopy-ai/sdk connect in your project root. It opens a consent page in your browser, then writes credentials to ~/.config/canopy/credentials and merges a canopy MCP server entry into any installed Claude Code, Cursor, Claude Desktop, Windsurf, Cline, VS Code, or Zed. Skip Steps 2 and 4 below.

Step 1 — Connect your agent in the dashboard

Canopy is bring-your-own-agent. This step doesn't create the agent itself — you've already built that, or are about to. It registers a Canopy-side record that pairs your agent with a spending policy and gives you an agt_… ID to use in your code.

Sign in at trycanopy.ai and go to Agents → Connect agent. Give the agent a name and pick (or create) a policy. The policy controls the spend cap, recipient allowlist, and approval threshold every payment from this agent will be evaluated against.

Step 2 — Copy your credentials

You need two values in your code:

  • Org API key (ak_live_… or ak_test_…) — from Settings → API Keys. Copy it the moment you create it; the plaintext is shown only once.
  • Agent ID (agt_…) — from the agent's detail page in /dashboard/agents.

Step 3 — Install the package

pip install canopy-ai

Step 4 — Set your environment variables

CANOPY_API_KEY=ak_live_xxxxxxxxxxxxxxxx
CANOPY_AGENT_ID=agt_xxxxxxxx

Use a .env file locally and your platform's secret manager in production. Never commit credentials.

Step 5 — Connect in your agent code

Paste the snippet below into your existing Python agent.

# 1. Add to your .env:
# CANOPY_API_KEY=ak_live_xxxxxxxxxxxxxxxx

# 2. In your agent code:
import os
from canopy_ai import Canopy

canopy = Canopy(
    api_key=os.environ["CANOPY_API_KEY"],
    agent_id="agt_xxxxxxxx",
)

# Pay someone
result = canopy.pay(to="0x1234...", amount_usd=0.10)

if result["status"] == "allowed":
    print("tx:", result["tx_hash"])
elif result["status"] == "pending_approval":
    decided = canopy.wait_for_approval(result["approval_id"])

Step 6 — Verify the connection

Run your agent once. As soon as Canopy receives a request from it, the dashboard flips the agent to connected and shows the first event captured. If nothing happens after a minute, see Troubleshooting.

Async clients

For async frameworks (FastAPI, asyncio loops, LangGraph), import AsyncCanopy instead of Canopy:

from canopy_ai import AsyncCanopy
 
canopy = AsyncCanopy(
    api_key=os.environ["CANOPY_API_KEY"],
    agent_id=os.environ["CANOPY_AGENT_ID"],
)
 
result = await canopy.pay(to="0x...", amount_usd=0.10)

Same arguments, every method is a coroutine.

Where to go next