x402-starknet

Pure library for implementing the x402 payment protocol on Starknet

A TypeScript library providing core functions for building x402-compatible payment systems on Starknet. Designed as a foundation library with a minimal, stable API surface.

Installation

npm install x402-starknet starknet
# or
bun add x402-starknet starknet

Quick Start

import {
  createPaymentPayload,
  verifyPayment,
  settlePayment,
  buildUSDCPayment,
  createProvider,
  createSettlementOptions,
} from 'x402-starknet';

// Server: Build payment requirements
const requirements = buildUSDCPayment({
  network: 'starknet:mainnet',
  amount: 1.5, // $1.50 USDC
  payTo: '0x1234...',
});

// Client: Create signed payment
const payload = await createPaymentPayload(account, 2, requirements, {
  endpoint: 'https://starknet.paymaster.avnu.fi',
  network: 'starknet:mainnet',
});

// Server: Verify and settle
const provider = createProvider('starknet:mainnet');
const verification = await verifyPayment(provider, payload, requirements);

if (verification.valid) {
  const options = createSettlementOptions('starknet:mainnet', {
    apiKey: process.env.PAYMASTER_API_KEY,
  });
  const result = await settlePayment(provider, payload, requirements, options);
}

Features

• 100 Named Exports - Complete, batteries-included API
• Type Safe - Full TypeScript support with Zod validation schemas
• Starknet Native - Built for account abstraction with paymaster support
• Multi-Network - Mainnet, Sepolia, and devnet (CAIP-2 format)
• Tree-Shakeable - sideEffects: false, import only what you need
• Spec Compliant - Full x402 v2 protocol compliance

Network Support

| Network | Identifier | Status | | ------- | ------------------ | --------- | | Mainnet | starknet:mainnet | Supported | | Sepolia | starknet:sepolia | Supported | | Devnet | starknet:devnet | Supported |

Documentation

| Document | Description | | ------------------------------------------------------- | ------------------------------------ | | Usage Examples | Practical integration examples | | API Reference | Complete API documentation | | API Surface | Public exports and design principles | | Paymaster Setup | Paymaster configuration guide | | Scheme Specification | x402 exact scheme for Starknet |

Development

git clone https://github.com/aspect-build/x402-starknet.git
cd x402-starknet
bun install
bun run build    # Build TypeScript
bun run test     # Run tests (541 tests)
bun run lint     # Lint code
bun run check    # Run all checks

License

Apache License 2.0 - see LICENSE for details.

Version: 1.0.0 | Protocol: x402 v2 | Tests: 541 passing