@autonome/x402-payment-sdk

TypeScript SDK for interacting with the x402-payment Solana program.

Installation

npm install @autonome/x402-payment-sdk
# or
yarn add @autonome/x402-payment-sdk

Quick Start

import { X402PaymentSDK, Connection, Keypair, PublicKey } from "@autonome/x402-payment-sdk";

// Connect to Solana
const connection = new Connection("http://localhost:8899", "confirmed");
const sdk = new X402PaymentSDK(connection);

// Create a payment
const payer = Keypair.generate(); // Your payer keypair
const payee = new PublicKey("..."); // Payee address

const { signature, receiptAddress } = await sdk.createPayment(payer, {
  payee,
  amount: X402PaymentSDK.solToLamports(1), // 1 SOL
  resourceId: "article-123",
  memo: "Payment for premium article",
});

console.log("Payment signature:", signature);
console.log("Receipt address:", receiptAddress.toString());

Features

• ✅ Create payments with automatic fee distribution
• ✅ Verify payments via on-chain receipts
• ✅ PDA (Program Derived Address) derivation
• ✅ Typed interfaces for all program accounts
• ✅ Helper functions for common operations

API Reference

Constructor

new X402PaymentSDK(connection: Connection, programId?: PublicKey)

Initialize Payment System (One-time)

await sdk.initialize(authority, {
  facilitator: facilitatorPublicKey,
  feeBasisPoints: 500, // 5%
});

Create Payment

const result = await sdk.createPayment(payer, {
  payee: payeePublicKey,
  amount: 1_000_000_000, // 1 SOL in lamports
  resourceId: "unique-resource-id",
  memo: "Optional memo",
});

Verify Payment

const { verified, receipt } = await sdk.verifyPayment(
  payerPublicKey,
  "unique-resource-id",
);

if (verified) {
  console.log("Payment confirmed!");
  console.log("Amount paid:", receipt.amount.toNumber());
  console.log("Fee:", receipt.fee.toNumber());
}

Check if Receipt Exists

const hasPaid = await sdk.hasReceipt(payerPublicKey, "resource-id");

Get Configuration

const config = await sdk.getConfig();
console.log("Facilitator:", config.facilitator.toString());
console.log("Fee:", config.feeBasisPoints / 100, "%");

Utility Functions

// Convert SOL to lamports
const lamports = X402PaymentSDK.solToLamports(1.5); // 1.5 SOL

// Convert lamports to SOL
const sol = X402PaymentSDK.lamportsToSol(1_500_000_000); // 1.5

// Calculate fee
const fee = X402PaymentSDK.calculateFee(1_000_000_000, 500); // 50_000_000 (5%)

PDA Derivation

// Derive config address
const [configAddress, configBump] = sdk.deriveConfigAddress();

// Derive receipt address
const [receiptAddress, receiptBump] = sdk.deriveReceiptAddress(
  payerPublicKey,
  "resource-id",
);

Types

PaymentConfig

interface PaymentConfig {
  authority: PublicKey;
  facilitator: PublicKey;
  feeBasisPoints: number; // 100 = 1%, max 1000 = 10%
  version: number;
  paused: boolean;
  bump: number;
}

Receipt

interface Receipt {
  payer: PublicKey;
  payee: PublicKey;
  amount: anchor.BN;
  fee: anchor.BN;
  timestamp: anchor.BN;
  resourceId: string;
  memo: string;
  isTokenPayment: boolean;
  tokenMint: PublicKey | null;
  signature: number[];
  bump: number;
}

Example: Full Payment Flow

import {
  X402PaymentSDK,
  Connection,
  Keypair,
  PublicKey,
} from "@autonome/x402-payment-sdk";

async function payForContent() {
  // Setup
  const connection = new Connection("http://localhost:8899");
  const sdk = new X402PaymentSDK(connection);
  const payer = Keypair.generate(); // Load from file in production
  const payee = new PublicKey("ContentCreatorAddress...");

  // 1. Check if already paid
  const alreadyPaid = await sdk.hasReceipt(payer.publicKey, "article-123");
  if (alreadyPaid) {
    console.log("Already paid for this content!");
    return;
  }

  // 2. Create payment
  console.log("Creating payment...");
  const { signature, receiptAddress } = await sdk.createPayment(payer, {
    payee,
    amount: X402PaymentSDK.solToLamports(0.1), // 0.1 SOL
    resourceId: "article-123",
    memo: "Premium article access",
  });

  console.log("Payment successful!");
  console.log("Transaction:", signature);
  console.log("Receipt:", receiptAddress.toString());

  // 3. Verify payment
  const { verified, receipt } = await sdk.verifyPayment(
    payer.publicKey,
    "article-123",
  );

  if (verified) {
    console.log("Payment verified on-chain");
    console.log("Amount:", X402PaymentSDK.lamportsToSol(receipt.amount));
    console.log("Fee:", X402PaymentSDK.lamportsToSol(receipt.fee));
  }
}

Development

# Build
npm run build

# Test
npm test

# Lint
npm run lint

# Format
npm run format

License

Apache-2.0

Contributing

Contributions welcome! Please open an issue or PR.