proviso-sdk

proviso-sdk

Give your AI agent a spending policy it cannot break.

Proviso is a payment layer an agent spends through. Every spend is bounded by an on-chain policy the owner sets - budget cap, per-transaction max, velocity limit, allowed merchants, kill switch - enforced on Stellar so the agent physically cannot spend outside it.

This package is the client. It is non-custodial by construction: the only way it can turn an unsigned transaction into a spendable one is ProvisoClient.cosign(), which asks the co-signer service to check the policy and add Proviso's signature. The service holds Proviso's key; this client never does. Proviso's signature is weight 1 against a threshold of 2, so even a co-signature cannot move funds without the agent's own signature. Neither side spends alone.

Install

npm install proviso-sdk

Use

import { ProvisoClient, purchase } from "proviso-sdk";
import { Keypair, Networks } from "@stellar/stellar-sdk";

const client = new ProvisoClient({
  baseUrl: process.env.PROVISO_COSIGNER_URL!,
  token: process.env.PROVISO_AGENT_TOKEN!,
});

// See the room before spending.
const policy = await client.policy();

// Pay a quote (from a site skill). Dry run by default; arm to actually pay.
const result = await purchase({
  client,
  quote,                                  // { destination, memo, memoType, amountStroops, network, ... }
  agentKp: Keypair.fromSecret(process.env.PROVISO_AGENT_SECRET!),
  sourceAccountId: process.env.PROVISO_ACCOUNT_ID!,
  horizonUrl: "https://horizon-testnet.stellar.org",
  networkPassphrase: Networks.TESTNET,
  maxAmountStroops: 20_0000000n,
  expectedMemoType: "text",
  arm: false,                             // true to actually pay
});

If the co-signer refuses, result is { ok: false, reason } with the policy reason (over budget cap, over per-transaction max, over velocity limit, destination not allowed, policy paused). A refusal is the policy working; do not retry to sneak under a limit.

MCP

The package ships an MCP server so any MCP-speaking agent (Claude Code, Cursor, ...) can use Proviso as tools (proviso_policy, proviso_purchase). Configure it from the environment:

{
  "mcpServers": {
    "proviso": {
      "command": "proviso-mcp",
      "env": {
        "PROVISO_COSIGNER_URL": "http://localhost:8787",
        "PROVISO_AGENT_TOKEN": "...",
        "PROVISO_AGENT_SECRET": "S...",
        "PROVISO_ACCOUNT_ID": "G...",
        "PROVISO_NETWORK": "testnet"
      }
    }
  }
}

Config comes from the environment, never from tool arguments, so an agent cannot point itself at a different co-signer or swap its signing key mid-conversation.

Networks

Defaults to Stellar testnet. Mainnet is opt-in via PROVISO_NETWORK=public.