@dcentralab/d402-client

D402 Payment Protocol Client for TypeScript/JavaScript

Implementation of the D402 payment protocol for HTTP 402 (Payment Required) responses. Works in any JavaScript environment (React, Next.js, Vue, Node.js, etc.) with automatic payment signing and retry.

Part of the iatp-js monorepo. Built by Dcentralab.

🚀 Quick Start

Installation

npm install @dcentralab/d402-client viem wagmi

Requirements: React/Next.js app with viem ^2.21.0 and wagmi for wallet connection.

Your First Payment

import { D402Client, createIATPWallet, getWalletsByOwner } from '@dcentralab/d402-client'
import { useWalletClient } from 'wagmi'

// In your React component
const { data: walletClient } = useWalletClient()

// 1. Check if user has an IATP wallet
const existingWallets = await getWalletsByOwner({
  ownerAddress: walletClient.account.address,
  network: 'sepolia'
})

// 2. Create wallet if needed (one-time)
const walletAddress = existingWallets.length === 0
  ? (await createIATPWallet({ ownerAccount: walletClient.account })).walletAddress
  : existingWallets[0]

// 3. Create D402 client
const client = new D402Client({
  operatorAccount: walletClient.account,
  iatpWalletAddress: walletAddress,
  maxValue: 1000000n  // 1 USDC max
})

// 4. Call 402-protected API (automatic payment handling!)
const response = await client.fetch('https://paid-api.com/analyze', {
  method: 'POST',
  body: JSON.stringify({ text: 'Bitcoin looks bullish' })
})

That's it! The client automatically handles 402 responses, payment signing, and retry.

📖 Documentation

• Getting Started Guide - Installation, setup, and first payment
• API Reference - Complete API documentation
• Wallet Management - Creating and managing IATP wallets
• Usage Patterns - Frontend vs backend patterns
• Examples - Complete code examples
• Security Guide - Best practices and security considerations

🏗️ Key Features

• ✅ Automatic 402 handling - Detects, signs, and retries with payment
• ✅ EIP-712 signatures - Secure, typed message signing
• ✅ Universal - Works in browsers and Node.js
• ✅ Type-safe - Full TypeScript support
• ✅ Well-tested - 166 tests covering all functionality

🌐 Supported Networks

IATP contracts are currently deployed on:

| Network | Chain ID | USDC Address | |----------------------|------------|----------------------------------------------| | Sepolia Testnet | 11155111 | 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 |

Additional networks (mainnet, Base, Polygon, etc.) will be supported once IATP contracts are deployed.

🧪 Testing

# Run all tests
pnpm test

# Run with coverage
pnpm test --coverage

# Type check
pnpm typecheck

Test Coverage: 166 tests covering client, wallet, payment, settlement, and integration scenarios.

📦 Package Exports

// Main client
import { D402Client } from '@dcentralab/d402-client'

// Wallet management
import { createIATPWallet, getWalletsByOwner, getAvailableBalance } from '@dcentralab/d402-client'

// Payment functions
import { signD402Payment, encodePayment, parsePaymentRequirement } from '@dcentralab/d402-client'

// All exports documented in API Reference

🤝 Contributing

We welcome contributions! See the main Contributing Guide.

📄 License

MIT License - see LICENSE file.

💬 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📚 Docs: Complete Documentation

Made with ❤️ by the DcentraLab Team