x402charity

Add micro-donations to any product with a single line of code. Powered by the x402 protocol — every user action triggers a USDC donation on Base.

Live Demo | GitHub | Deploy Your Own Server

Install

npm install x402charity

Quick Start

Express Middleware

import { x402charity } from 'x402charity/express';

app.use('/api', x402charity({
  privateKey: process.env.DONATION_PRIVATE_KEY,
  donateEndpoint: 'https://your-charity-server.com/donate',
  charity: {
    id: 'my-charity',
    name: 'My Charity',
    walletAddress: '0x...',
    chain: 'base-sepolia',
    description: 'My charity description',
    verified: false,
    x402Endpoint: 'https://your-charity-server.com/donate',
  },
  amount: '$0.001',
  shouldDonate: (req) => req.method === 'POST',
}));

Next.js Middleware

// middleware.ts
import { x402charity } from 'x402charity/next';

export default x402charity({
  privateKey: process.env.DONATION_PRIVATE_KEY,
  donateEndpoint: 'https://your-charity-server.com/donate',
  charity: {
    id: 'my-charity',
    name: 'My Charity',
    walletAddress: '0x...',
    chain: 'base-sepolia',
    description: 'My charity description',
    verified: false,
    x402Endpoint: 'https://your-charity-server.com/donate',
  },
  amount: '$0.001',
  matcher: '/api/*',
});

Programmatic Client

import { X402CharityClient } from 'x402charity';

const client = new X402CharityClient({
  privateKey: process.env.DONATION_PRIVATE_KEY,
  donateEndpoint: 'https://your-charity-server.com/donate',
  charity: {
    id: 'my-charity',
    name: 'My Charity',
    walletAddress: '0x...',
    chain: 'base-sepolia',
    description: 'My charity description',
    verified: false,
    x402Endpoint: 'https://your-charity-server.com/donate',
  },
});

const receipt = await client.donate('$0.001');
console.log(receipt.txHash); // on-chain proof

CLI

npx x402charity donate testing-charity '$0.001' --network base-sepolia

How It Works

1. Your server calls a deployed x402 charity server's POST /donate endpoint
2. The charity server uses the x402 protocol to sign a USDC payment
3. The x402 facilitator (operated by Coinbase) settles the payment on Base
4. Your server gets back a receipt with the on-chain transaction hash

Users never need a wallet or any crypto knowledge. Your company funds donations from a single pre-funded wallet.

API

X402CharityClient

new X402CharityClient(options: ClientOptions)

| Option | Type | Required | Description | |--------|------|----------|-------------| | privateKey | string | Yes | Private key of the wallet funding donations | | donateEndpoint | string | Yes | URL of the x402-gated donation endpoint | | charity | Charity | Yes | Charity receiving donations | | network | 'base' \| 'base-sepolia' | No | Network to use (default: base-sepolia) |

client.donate(amount?: string): Promise<DonationReceipt>

Triggers a donation. Default amount is $0.001.

Express Middleware Options

All ClientOptions plus:

| Option | Type | Default | Description | |--------|------|---------|-------------| | amount | string | '$0.001' | Donation amount per request | | silent | boolean | true | Suppress error logs | | shouldDonate | (req) => boolean | — | Filter which requests trigger donations |

Next.js Middleware Options

All ClientOptions plus:

| Option | Type | Default | Description | |--------|------|---------|-------------| | amount | string | '$0.001' | Donation amount per request | | silent | boolean | true | Suppress error logs | | matcher | string \| string[] | — | URL patterns to match (e.g. '/api/*') |

Server Setup

This package is the client SDK. You also need a running x402 charity server to receive donations. See the GitHub repo for server setup, or deploy one instantly:

License

MIT