Ship an agent with a budget,
in three lines.

Install

 1npm install @kyvernlabs/sdk
 2# or
 3pnpm add @kyvernlabs/sdk
 4# or
 5yarn add @kyvernlabs/sdk

Node 18+ or any runtime with a global fetch. The package has zero runtime dependencies.

Quickstart

 1export KYVERN_AGENT_KEY=kv_live_...
 2# optional: route earnings to a KAST-funded card
 3export MY_KAST_ADDRESS=...

 1import { Vault, KastDestination } from "@kyvernlabs/sdk";
 2 
 3const vault = new Vault({ agentKey: process.env.KYVERN_AGENT_KEY! });
 4const myKast = KastDestination.fromAddress(process.env.MY_KAST_ADDRESS!);
 5const res = await vault.pay({ ...myKast, amount: 1.50, memo: "weekly yield share" });
 6if (res.decision !== "allowed") throw new Error(res.reason);

vault.pay()

Ask the vault to pay a merchant. Policy is enforced server-side — every call is budgeted, rate-limited, and matched against the allowlist before Squads co-signs.

 1await vault.pay({
 2  merchant: string,          // URL or host, normalized server-side
 3  recipientPubkey: string,   // Solana pubkey of the USDC recipient
 4  amount: number,            // USD (USDC mint, 6 decimals)
 5  memo?: string,             // required if vault.requireMemo === true
 6}): Promise<PayResult>

Returns { decision: "allowed" | "blocked", … }. Pass throwOnBlocked: true to the constructor if you'd rather catch KyvernPaymentBlocked.

vault.checkAllowance()

Run the same off-chain policy check that pay() runs, but without making a payment. Returns the chain's verdict ahead of time so an agent can decide whether to fire the underlying paid call.

 1await vault.checkAllowance({
 2  merchant: string,         // URL or host, normalized server-side
 3  amount: number,           // USD
 4  memo?: string,            // required if vault.requireMemo === true
 5}): Promise<{ decision: "allowed" | "blocked", reason?: string, code?: string }>

Use this when you're wrapping pay.sh, x402, or any 402-paywalled rail — the vault decides BEFORE the rail's wallet prompt fires.

vault.status()

Snapshot of the vault — budget utilization, velocity, and the most recent payments. This is what the owner dashboard uses on every poll.

 1const s = await vault.status({ vaultId: "vlt_abc", limit: 20 });
 2 
 3console.log(`${s.budget.spentToday} / ${s.budget.dailyLimitUsd} USD today`);
 4console.log(`${s.velocity.callsInWindow} calls in last ${s.velocity.velocityWindow}`);
 5for (const p of s.payments) {
 6  console.log(p.createdAt, p.merchant, p.amountUsd, p.status, p.reason ?? "");
 7}

Kill switch

Pause blocks every future payment instantly. Existing policies stay intact — resume any time. Pause/resume require the ownerWallet at construction time.

 1const owner = new Vault({
 2  agentKey: process.env.KYVERNLABS_AGENT_KEY!,
 3  ownerWallet: "5eyKt4yXtD9Wz8gPWs9fEUv9AQCoTFv9o6xAiBm1Kjv6",
 4});
 5 
 6await owner.pause({ vaultId: "vlt_abc" });   // agent is dead to the world
 7await owner.resume({ vaultId: "vlt_abc" });  // back online

Errors & decisions

Every pay() resolves with a decision. Blocks are not exceptions by default — they're data. The code is stable across versions so you can branch on it.

Auth failures throw KyvernAuthError (401). Network or 5xx errors throw KyvernError with the HTTP status attached.

Wrap pay.sh with Kyvern in 4 lines

pay.sh is the Solana Foundation's payment layer for HTTP agents. It handles 402/x402/MPP challenges and asks the local wallet to sign. Their docs say “Real payments still require local user authorization.” Kyvern is what closes that gap — the chain takes the place of the wallet approval prompt so an agent can run autonomously without compromising safety.

 1# 1. Install both tools.
 2brew install pay                 # macOS
 3# or
 4npm install -g @solana/pay       # Linux/Windows
 5npm install @kyvernlabs/sdk
 6 
 7# 2. Scaffold a Kyvern-protected agent that pays pay.sh APIs.
 8npx create-kyvern-agent my-agent
 9 
10# 3. The scaffolded agent calls pay.sh through your Kyvern vault.
11#    Every call passes through your on-chain policy. Drains, rogue
12#    endpoints, over-cap purchases — all refused before pay.sh sees them.
13cd my-agent && npm start

The architectural moment

Before invoking pay.sh, ask the vault first:

 1const allowance = await vault.checkAllowance({
 2  merchant: "api.pay.sh",
 3  amount: 0.001,
 4});
 5if (allowance.decision !== "allowed") {
 6  // Kyvern refused — pay.sh is never invoked, no wallet prompt fires.
 7  return console.warn("blocked:", allowance.reason);
 8}
 9 
10// Kyvern allowed — pay.sh executes the 402-paywalled call.
11const result = execSync(
12  `pay --sandbox curl https://pay.sh/<service-url>`,
13  { encoding: "utf-8" },
14);

Kyvern is compatible with pay.sh and any HTTP-402 payment rail. Not partnered with pay.sh. The composability is the integration.

Sending earnings to a KAST-funded card

Every KAST user has a Solana USDC deposit address. Send USDC there → it tops up their card → they spend at 150M+ merchants worldwide. Kyvern wraps that flow in a vault budget so an agent can route a share of accrued earnings to your card automatically.

 1import { Vault, KastDestination } from "@kyvernlabs/sdk";
 2 
 3const vault = new Vault({ agentKey: process.env.KYVERN_AGENT_KEY! });
 4const myKast = KastDestination.fromAddress(process.env.MY_KAST_ADDRESS!);
 5const res = await vault.pay({ ...myKast, amount: 1.50, memo: "weekly yield share" });
 6if (res.decision !== "allowed") throw new Error(res.reason);

Don't have a KAST card? Get one →

Kyvern is compatible with KAST deposit rails. Not affiliated with KAST. We don't verify the address belongs to a KAST account — the user owns the address either way.

REST API

The SDK is a thin client. Here's the raw API for polyglot teams.

 1curl -X POST https://kyvernlabs.com/api/vault/pay \
 2  -H "Authorization: Bearer kv_live_..." \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "merchant": "api.openai.com",
 6    "recipientPubkey": "5eyKt4yXtD9Wz8gPWs9fEUv9AQCoTFv9o6xAiBm1Kjv6",
 7    "amountUsd": 0.12,
 8    "memo": "forecast lookup"
 9  }'

200 = settled · 402 = policy block · 401 = bad key · 400 = validation · 502 = Squads failure

What this is, and what this isn't

What's next