@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

| Command | Description | |---------|-------------| | agentpay setup | One-time interactive setup — passphrase, card details, billing/shipping address | | agentpay budget | View/set spending limits (--set <amount>, --limit-per-tx <amount>) | | agentpay propose | Create a pending transaction (--merchant, --amount, --description, --url) | | agentpay pending | List pending purchase proposals | | agentpay approve <txId> | Approve a purchase (signs an Ed25519 mandate) | | agentpay reject <txId> | Reject a purchase (--reason optional) | | agentpay status | Wallet balance, budget, limits, recent transactions | | agentpay history | Full transaction history | | agentpay qr | QR code for web-based setup (--budget, --message) | | agentpay dashboard | Browser-based GUI (--port, default 3141) | | agentpay mcp | Start MCP server (--http for HTTP transport) | | agentpay reset | Delete all AgentPay data |

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

| Method | Description | |--------|-------------| | ap.status() | Overall system status | | ap.wallet.getBalance() | Current balance and budget | | ap.wallet.getHistory() | Transaction history | | ap.wallet.getLimits() | Budget and per-tx limits | | ap.wallet.generateFundingQR(options?) | QR code for setup | | ap.transactions.propose(options) | Create a pending transaction | | ap.transactions.get(txId) | Get transaction details | | ap.transactions.waitForApproval(txId, options?) | Long-poll for approval | | ap.transactions.requestApproval(txId) | Open browser approval UI | | ap.transactions.execute(txId) | Execute an approved purchase | | ap.transactions.getReceipt(txId) | Get receipt for completed purchase | | ap.audit.getLog() | Audit log entries |

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

| Variable | Purpose | Default | |----------|---------|---------| | ANTHROPIC_API_KEY | LLM API key for browser navigation | — | | AGENTPAY_HOME | Override data directory | ~/.agentpay | | AGENTPAY_WEB_URL | Base URL for QR codes | http://localhost:3000 |

Data Directory (~/.agentpay/)

| File | Purpose | |------|---------| | credentials.enc | AES-256-GCM encrypted billing credentials | | keys/private.pem | Ed25519 private key (passphrase-protected) | | keys/public.pem | Ed25519 public key | | wallet.json | Budget, balance, per-tx limit, spent total | | transactions.json | All transactions | | audit.log | Append-only action log |

License

MIT