npm package: @kaushtubh/x402-payment-sdk
Description: TypeScript SDK for x402 HTTP 402 Payment Required protocol on Solana blockchain - Enable micropayments for digital content
Author: Autonome
Latest version: 1.0.0

# @autonome/x402-payment-sdk

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

## Installation

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

## Quick Start

```typescript
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

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

### Initialize Payment System (One-time)

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

### Create Payment

```typescript
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

```typescript
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

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

### Get Configuration

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

## Utility Functions

```typescript
// 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

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

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

## Types

### PaymentConfig

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

### Receipt

```typescript
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

```typescript
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

```bash
# 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.