@kova402/sdk

TypeScript SDK for integrating x402 payments with KOVA - Multi-chain payment facilitator

What is x402?

x402 is a protocol for HTTP-based payments that enables developers to accept payments via cryptographically signed payloads. Instead of traditional payment processing, users sign transactions with their crypto wallet and include them in HTTP headers.

KOVA is a complete x402 payment facilitator supporting Solana, BASE, BSC, and Bitcoin that verifies and settles payments on-chain.

Features

✅ Client-Side Integration - Automatic 402 payment handling in browser/Node.js
✅ Server-Side Middleware - Express/Connect middleware for payment-gated APIs
✅ Solana Wallet Support - Works with any Solana wallet adapter
✅ Type-Safe - Full TypeScript support with detailed types
✅ Zero Configuration - Sensible defaults, minimal setup required

Installation

npm install @kova402/sdk

Peer Dependencies

npm install @solana/web3.js @solana/spl-token zod

Quick Start

Client-Side (Browser/Frontend)

Use the KOVA client to automatically handle 402 payment responses:

import { createKovaClient } from '@kova402/sdk/client';

// Initialize client with wallet adapter
const kova = createKovaClient({
  facilitatorUrl: 'https://kova402.com/api/v1',
  network: 'solana-devnet',
  wallet: myWalletAdapter, // Any Solana wallet adapter
  maxPaymentAmount: BigInt('1000000000'), // Optional: max 1 SOL
});

// Automatically handles 402 payments
const response = await kova.fetch('https://api.example.com/premium-data', {
  method: 'POST',
  body: JSON.stringify({ query: 'something' }),
});

const data = await response.json();
console.log('Got data:', data);

What happens:

1. First request gets 402 Payment Required
2. SDK automatically creates and signs payment
3. SDK retries request with payment header
4. Payment is verified and settled by KOVA
5. Your app gets the response seamlessly

Server-Side (Node.js/Express)

Protect your API endpoints with payment requirements:

import express from 'express';
import { KovaPaymentHandler } from '@kova402/sdk/server';

const app = express();

const kova = new KovaPaymentHandler({
  facilitatorUrl: 'https://kova402.com/api/v1',
  network: 'solana-devnet',
  treasuryAddress: process.env.TREASURY_WALLET!,
});

// Payment-gated endpoint using middleware
app.get('/api/premium-data',
  kova.middleware({
    amount: '1000000000', // 1 SOL in lamports
    onPaymentVerified: (payment) => {
      console.log('Payment received:', payment);
    },
  }),
  (req, res) => {
    res.json({ data: 'Premium content!' });
  }
);

// Manual payment handling
app.post('/api/custom', async (req, res) => {
  const payment = kova.extractPayment(req.headers);

  if (!payment) {
    const requirements = await kova.createPaymentRequirements({
      amount: '500000000', // 0.5 SOL
      resource: '/api/custom',
      description: 'Custom API access',
    });
    const response = kova.create402Response(requirements);
    return res.status(response.status).json(response.body);
  }

  // Verify payment
  const requirements = await kova.createPaymentRequirements({
    amount: '500000000',
    resource: '/api/custom',
  });

  const isValid = await kova.verifyPayment(payment, requirements);
  if (!isValid) {
    return res.status(402).json({ error: 'Invalid payment' });
  }

  // Settle payment (async, don't wait)
  kova.settlePayment(payment, requirements).catch(console.error);

  res.json({ success: true, data: 'Your data' });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

API Reference

Client API

createXchangeX402Client(config)

Creates a XchangeX402 client for handling payments.

Parameters:

• facilitatorUrl (string) - XchangeX402 facilitator URL
• network ('solana-mainnet' | 'solana-devnet') - Solana network
• wallet (WalletAdapter) - Solana wallet adapter for signing
• maxPaymentAmount (bigint, optional) - Maximum payment amount in lamports

Returns: XchangeX402Client with methods:

• fetch(url, options) - Enhanced fetch with automatic 402 handling
• getHealth() - Get facilitator health status
• getSupported() - Get supported networks and assets

Server API

new XchangeX402PaymentHandler(config)

Creates a payment handler for server-side verification.

Parameters:

• facilitatorUrl (string) - XchangeX402 facilitator URL
• network ('solana-mainnet' | 'solana-devnet') - Solana network
• treasuryAddress (string) - Your Solana wallet address for receiving payments

Methods:

• extractPayment(headers) - Extract payment from request headers
• createPaymentRequirements(config) - Create payment requirements object
• verifyPayment(payment, requirements) - Verify payment with facilitator
• settlePayment(payment, requirements) - Settle payment on-chain
• create402Response(requirements) - Create 402 response object
• middleware(config) - Express/Connect middleware

Examples

React + Phantom Wallet

import { useWallet } from '@solana/wallet-adapter-react';
import { createXchangeX402Client } from '@xchangex402/sdk/client';

function MyComponent() {
  const wallet = useWallet();

  const fetchPremiumData = async () => {
    const xchangex402 = createXchangeX402Client({
      facilitatorUrl: 'https://xchangeswap.com/api/v1',
      network: 'solana-devnet',
      wallet: wallet,
    });

    const response = await xchangex402.fetch('/api/premium-data');
    const data = await response.json();
    console.log(data);
  };

  return (
    <button onClick={fetchPremiumData}>
      Get Premium Data
    </button>
  );
}

Next.js API Route

import { XchangeX402PaymentHandler } from '@xchangex402/sdk/server';
import type { NextApiRequest, NextApiResponse } from 'next';

const xchangex402 = new XchangeX402PaymentHandler({
  facilitatorUrl: process.env.XCHANGEX402_URL!,
  network: 'solana-mainnet',
  treasuryAddress: process.env.TREASURY_WALLET!,
});

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const payment = xchangex402.extractPayment(req.headers);

  if (!payment) {
    const requirements = await xchangex402.createPaymentRequirements({
      amount: '1000000000', // 1 SOL
      resource: '/api/premium',
    });
    const response = xchangex402.create402Response(requirements);
    return res.status(response.status).json(response.body);
  }

  const requirements = await xchangex402.createPaymentRequirements({
    amount: '1000000000',
    resource: '/api/premium',
  });

  const isValid = await xchangex402.verifyPayment(payment, requirements);
  if (!isValid) {
    return res.status(402).json({ error: 'Invalid payment' });
  }

  // Settlement happens async
  xchangex402.settlePayment(payment, requirements).catch(console.error);

  res.json({ data: 'Premium content' });
}

Networks & Assets

Supported Networks

• Solana Mainnet (chainId: 101)
• Solana Devnet (chainId: 102)

Supported Assets

• SOL (9 decimals)
• USDC (SPL Token, 6 decimals)
• USDT (SPL Token, 6 decimals)

Payment Amounts

All amounts are in the smallest unit (lamports for SOL):

• 1 SOL = 1,000,000,000 lamports
• 1 USDC = 1,000,000 (6 decimals)

// 1 SOL payment
amount: '1000000000'

// 0.1 SOL payment
amount: '100000000'

// 10 USDC payment
amount: '10000000'

Environment Variables

Client-Side

No environment variables needed - configuration is passed to the client.

Server-Side

XCHANGEX402_URL=https://xchangeswap.com/api/v1
TREASURY_WALLET=YourSolanaWalletAddress...

Testing

Use Solana devnet for testing:

// Client
const xchangex402 = createXchangeX402Client({
  facilitatorUrl: 'https://xchangeswap.com/api/v1',
  network: 'solana-devnet',
  wallet: testWallet,
});

// Server
const xchangex402 = new XchangeX402PaymentHandler({
  facilitatorUrl: 'https://xchangeswap.com/api/v1',
  network: 'solana-devnet',
  treasuryAddress: testWalletAddress,
});

Get devnet SOL from the Solana Faucet.

Error Handling

try {
  const response = await xchangex402.fetch('/api/endpoint');
  const data = await response.json();
} catch (error) {
  if (error.message.includes('Payment amount')) {
    console.error('Payment exceeds maximum allowed');
  } else {
    console.error('Request failed:', error);
  }
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  PaymentPayload,
  PaymentRequirements,
  VerifyResponse,
  SettleResponse,
  XchangeX402Config,
} from '@kova402/sdk';

Resources

• Documentation: https://kova402.com
• GitHub: https://github.com/Iamthetachi/Kova402
• NPM: https://www.npmjs.com/package/@kova402/sdk
• x402 Protocol: https://x402.org
• Support: [email protected]

License

MIT © XchangeX402

Built with ❤️ for the Solana ecosystem