CLPAY Documentation

Complete guide to integrating autonomous Solana payments into your Claude workflows. From installation to production deployment.

Installation

Install CLPAY via npm:

npm install @clpay/core @clpay/validator

Or with yarn:

yarn add @clpay/core @clpay/validator

Requirements

• Node.js 18+ or Bun 1.0+
• Solana CLI tools (optional, for key management)
• A funded Solana wallet (devnet for testing)

Quick Start

Get up and running in under 5 minutes:

import { CLPay } from '@clpay/core';

const clpay = new CLPay({
  network: 'devnet',
  wallet: './keys/dev-wallet.json',
  limits: { perTransaction: 0.1, daily: 1.0 },
  riskThreshold: 0.5,
});

// Make a payment
const result = await clpay.pay({
  to: 'merchant-address.sol',
  amount: 0.01,
  reason: 'API access for data analysis',
  taskContext: 'User requested market data aggregation',
});

console.log(result);
// {
//   status: 'approved',
//   txHash: '4xK2...9mPq',
//   riskScore: 0.08,
//   necessity: 'high',
//   simulation: { success: true, balanceChange: -0.01 }
// }

Configuration

Full configuration reference for the CLPay constructor:

API Reference

clpay.pay(options)

Initiate a payment through the full validation pipeline.

const result = await clpay.pay({
  to: string,          // Recipient address or .sol domain
  amount: number,      // Amount in SOL
  token?: string,      // SPL token mint (default: native SOL)
  reason: string,      // Why this payment is needed
  taskContext: string,  // Current task description for necessity eval
  priority?: 'low' | 'medium' | 'high',  // Transaction priority
  memo?: string,       // On-chain memo
});

Returns a PaymentResult object:

{
  status: 'approved' | 'rejected' | 'pending',
  txHash?: string,           // Solana transaction signature
  riskScore: number,         // 0–1 risk assessment
  necessity: 'high' | 'medium' | 'low' | 'none',
  simulation: {
    success: boolean,
    balanceChange: number,
    logs: string[],
  },
  rejection?: {
    reason: string,          // Human-readable rejection reason
    code: string,            // Machine-readable code
    details: object,         // Additional context
  }
}

clpay.simulate(options)

Simulate a transaction without executing it. Same parameters as pay().

const sim = await clpay.simulate({
  to: 'merchant.sol',
  amount: 0.05,
  reason: 'Testing simulation',
});
// sim.balanceChange, sim.logs, sim.success

clpay.getBalance()

Get current wallet balance.

const balance = await clpay.getBalance();
// { sol: 2.45, tokens: [{ mint: '...', amount: 100, symbol: 'USDC' }] }

clpay.getHistory(options?)

Retrieve transaction history with filtering.

const history = await clpay.getHistory({
  limit: 20,
  status: 'approved',    // 'approved' | 'rejected' | 'all'
  from: new Date('2026-01-01'),
  to: new Date(),
});

Validator Agent

The validator is a side-agent that runs before every transaction. It operates as an independent decision-maker with its own evaluation pipeline.

Pipeline Stages

• SimulationStage — Executes a dry-run of the transaction on Solana, capturing all state changes, token movements, and compute units consumed.
• SecurityStage — Checks the recipient address against known scam databases, verifies contract source code (if available), and analyzes transaction patterns.
• NecessityStage — Uses the current task context to evaluate whether the purchase is essential. Considers alternative free resources and cost-benefit ratio.
• LimitStage — Enforces per-transaction and daily spending limits. Cannot be overridden by the AI.

Custom Stages

You can add custom validation stages:

import { CLPay, ValidationStage } from '@clpay/core';

class ApprovalStage extends ValidationStage {
  async validate(tx) {
    if (tx.amount > 0.1) {
      // Require human approval for large transactions
      const approved = await this.requestHumanApproval(tx);
      return approved
        ? { pass: true }
        : { pass: false, reason: 'Human rejected the transaction' };
    }
    return { pass: true };
  }
}

const clpay = new CLPay({
  // ...config
  validator: {
    customStages: [new ApprovalStage()],
  },
});

Risk Engine

The risk engine produces a score from 0 (safe) to 1 (dangerous) based on multiple signals:

Security Model

Key Management

Private keys are never exposed to the AI agent. The wallet module handles all cryptographic operations in an isolated context:

• Keys encrypted at rest with AES-256-GCM
• Decryption requires validator pipeline approval
• Memory is zeroed after signing operations
• Optional HSM support for enterprise deployments

Threat Model

• AI prompt injection attempting unauthorized payments → blocked by independent validator agent
• Malicious merchant addresses → caught by security stage and blocklist
• Excessive spending → hard limits enforced at wallet level, not overridable by AI
• Transaction manipulation → simulation detects unexpected state changes

Events & Hooks

CLPAY emits events at every stage of the payment lifecycle:

clpay.on('payment:initiated', (tx) => { /* ... */ });
clpay.on('validation:stage', (stage, result) => { /* ... */ });
clpay.on('payment:approved', (tx, result) => { /* ... */ });
clpay.on('payment:rejected', (tx, reason) => { /* ... */ });
clpay.on('payment:executed', (tx, signature) => { /* ... */ });
clpay.on('limit:warning', (usage) => { /* 80% of daily limit */ });
clpay.on('limit:reached', (usage) => { /* daily limit hit */ });

CLI

CLPAY includes a CLI for wallet management and monitoring:

# Check wallet balance
npx clpay balance

# View transaction history
npx clpay history --limit 10

# Test a payment (simulation only)
npx clpay simulate --to merchant.sol --amount 0.01

# Export audit log
npx clpay audit --format json --output audit.json

# Manage allowlist
npx clpay allow add openai.merchant.sol
npx clpay allow list
npx clpay allow remove openai.merchant.sol