Canopy

Connect Node.js / TypeScript

The TypeScript SDK works in any Node 18+ environment — plain scripts, Express, Fastify, Cloudflare Workers, etc. It ships ESM and CJS bundles with zero runtime dependencies.

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

npm install @canopy-ai/sdk

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 Node.js agent.

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

// 2. In your agent code:
import { Canopy } from '@canopy-ai/sdk';

const canopy = new Canopy({
  apiKey: process.env.CANOPY_API_KEY,
  agentId: 'agt_xxxxxxxx',
});

// Pay someone
const result = await canopy.pay({
  to: '0x1234...',
  amountUsd: 0.10,
});

if (result.status === 'allowed') {
  console.log('tx:', result.txHash);
} else if (result.status === 'pending_approval') {
  // Either ask the user (LLM calls canopy.approve / .deny when they reply)
  // or block until the dashboard / chat decides:
  const decided = await canopy.waitForApproval(result.approvalId);
}

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.

Notes for Node.js

  • pay() returns a discriminated union — never throws on a policy outcome. Switch on result.status.
  • Use idempotencyKey whenever a call might retry (webhook handlers, framework retries). A second call with the same (agentId, idempotencyKey) returns the cached decision without re-charging.
  • canopy.fetch(url, init?) is a drop-in for global fetch that auto-pays HTTP 402 paywalled APIs (x402).

Where to go next