Skip to main content

​
Prerequisites

Before installing the SDK, ensure you have:
  • Node.js 20 or later
  • A package manager (npm, yarn, or pnpm)
  • viem for blockchain interactions

​
Install Packages

Install only the packages you need for your use case: 
npm install @x402r/client @x402r/core viem

​
Setup viem Clients

All SDK classes require viem clients for blockchain interaction: 
import { createPublicClient, createWalletClient, http } from 'viem';
import { baseSepolia } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

// Public client for reading contract state
const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http(),
});

// Wallet client for write operations (requires private key)
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const walletClient = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(),
});

​
Contract Addresses

Get the deployed contract addresses from the network config: 
import { getNetworkConfig } from '@x402r/core';

const config = getNetworkConfig('eip155:84532'); // Base Sepolia

console.log(config.authCaptureEscrow); // Escrow contract
console.log(config.refundRequest);     // RefundRequest contract
console.log(config.arbiterRegistry);   // ArbiterRegistry contract
console.log(config.usdc);             // USDC token address
Network identifiers use the EIP-155 format: eip155:<chainId>. For Base Sepolia, use 'eip155:84532'. For Base Mainnet, use 'eip155:8453'.
Never commit private keys to version control. Use environment variables or a secrets manager.

​
Quick Verification

Verify your setup by querying refund status for a payment: 
import { X402rClient } from '@x402r/client';

const client = new X402rClient({
  publicClient,
  operatorAddress: '0x...', // Your PaymentOperator address
  refundRequestAddress: config.refundRequest,
});

// Check if a refund request exists for a payment
const hasRequest = await client.hasRefundRequest(paymentInfo, 0n);
console.log('Has refund request:', hasRequest);

​
Next Steps

Core Concepts

Learn about payment states, escrow, and the refund lifecycle.

Client Quickstart

Start building as a payer/client.

Merchant Quickstart

Integrate refunds into your server.

Arbiter Quickstart

Build a dispute resolution system.