@useagentpay/sdk

Secure payments infrastructure for AI agents. Local-first SDK and CLI that lets agents purchase things on the web without ever seeing a user's credit card.

Credentials are encrypted locally, purchases require human approval with Ed25519 signatures, and checkout happens via headless browser with placeholder injection — real values exist in the DOM for milliseconds.

Install

npm install @useagentpay/sdk

Quick Start

Human — set up credentials:

agentpay setup       # encrypt & store billing credentials locally
agentpay budget --set 200

Agent — propose & execute:

import { AgentPay } from '@useagentpay/sdk';
const ap = new AgentPay();

const tx = await ap.transactions.propose({
  merchant: 'amazon.com',
  amount: 29.99,
  description: 'Wireless mouse',
  url: 'https://amazon.com/dp/B09ABC1234',
});

const result = await ap.transactions.waitForApproval(tx.id);

if (result.status === 'approved') {
  const receipt = await ap.transactions.execute(tx.id);
}

Human — approve:

agentpay approve tx_a1b2c3

CLI Commands

SDK API

import { AgentPay } from '@useagentpay/sdk';

const ap = new AgentPay({
  passphrase: 'your-passphrase',      // optional
  home: '/custom/data/dir',           // optional, default ~/.agentpay
  executor: {
    provider: myCustomProvider,       // optional, defaults to local Chromium
    modelApiKey: process.env.ANTHROPIC_API_KEY,
  },
});

Methods

Custom Browser Provider

By default, PurchaseExecutor runs local Chromium via Playwright + Stagehand. Implement the BrowserProvider interface to use a different backend:

import { AgentPay, type BrowserProvider } from '@useagentpay/sdk';
import { Stagehand } from '@browserbasehq/stagehand';

const myProvider: BrowserProvider = {
  createStagehand(modelApiKey?: string) {
    return new Stagehand({ env: 'LOCAL', /* ... */ });
  },
  async close() {},
};

const ap = new AgentPay({
  executor: { provider: myProvider },
});

Security Model

• AES-256-GCM vault — credentials encrypted with PBKDF2 (SHA-512, 100k iterations), random salt + IV per encryption
• Placeholder injection — forms filled with {{card_number}} placeholders; real values swapped via atomic page.evaluate() at submission time
• Ed25519 signed mandates — every purchase requires a cryptographic human approval
• Browser security boundary — sensitive operations (setup, approval) open an ephemeral localhost browser window; credentials never pass through the terminal

Transaction States

pending → approved → executing → completed
       ↘ rejected             ↘ failed

Environment Variables

Data Directory (~/.agentpay/)

License

MIT