@arbitrum-pay/core

The premier SDK for Arbitrum payments - Payment links, webhooks, live stats, and enterprise-grade infrastructure.

🚀 Quick Start

npm install @arbitrum-pay/core

import { createPaymentRequest, createPaymentLink, createLiveStats } from '@arbitrum-pay/core';

// Create a payment request
const payment = createPaymentRequest({
  receiver: '0x742d35cc6634c0532925a3b8d4b9089d4',
  amount: '0.1',
  chainId: 42161, // Arbitrum One
  label: 'Coffee Purchase',
  message: 'Thanks for your order!'
});

// Generate a shareable payment link
const link = createPaymentLink(payment, {
  expiresIn: 3600, // 1 hour
  redirectUrl: 'https://mystore.com/success'
});

// Track live ecosystem stats
const statsManager = createLiveStats();
await statsManager.start();

✨ Features

🔗 Payment Links

Create shareable payment URLs with QR codes, expiration, and completion tracking:

import { createPaymentLink, parsePaymentLink } from '@arbitrum-pay/core';

// Create payment link
const link = createPaymentLink(paymentRequest, {
  expiresIn: 3600,
  maxUses: 1,
  redirectUrl: 'https://success-page.com'
});

// Parse payment link
const parsed = parsePaymentLink(link.url);
console.log(parsed.amount, parsed.receiver);

🔔 Enterprise Webhooks

Reliable webhook delivery with retry logic and signature verification:

import { WebhookDeliveryService } from '@arbitrum-pay/core';

const webhooks = new WebhookDeliveryService({
  secret: 'your-webhook-secret',
  retryConfig: {
    maxRetries: 3,
    backoffMs: 1000
  }
});

// Send webhook with automatic retries
await webhooks.deliverWebhook('https://api.mystore.com/webhooks', {
  type: 'payment.completed',
  paymentId: 'pay_123',
  amount: '0.1',
  token: 'ETH'
});

📊 Live Stats Dashboard

Real-time ecosystem metrics and activity tracking:

import { createLiveStats, StatsFormatter } from '@arbitrum-pay/core';

const stats = createLiveStats({
  updateInterval: 30000, // 30 seconds
  enableRealTime: true
});

stats.subscribe((data) => {
  console.log('Total Volume:', StatsFormatter.formatVolume(data.totalVolume));
  console.log('Success Rate:', data.successRate.toFixed(1) + '%');
  console.log('Recent Activity:', data.recentTransactions.length);
});

await stats.start();

🎯 Enhanced Error Handling

Standardized error codes and developer-friendly messages:

import { ErrorFactory, ArbitrumPayErrorCode } from '@arbitrum-pay/core';

try {
  await processPayment(request);
} catch (error) {
  const arbError = ErrorFactory.wrapError(error);
  
  if (arbError.code === ArbitrumPayErrorCode.INSUFFICIENT_BALANCE) {
    // Handle insufficient balance specifically
    console.log('User needs more funds:', arbError.message);
  }
}

🏗️ Core Functions

Payment Request Creation

import { createPaymentRequest, validatePaymentRequest } from '@arbitrum-pay/core';

const request = createPaymentRequest({
  receiver: '0x742d35cc6634c0532925a3b8d4b9089d4',
  amount: '0.1',
  token: '0xA0b86a33E6441b33Bf93C7aa3e2E4E75b9f7B5B', // USDC
  chainId: 42161,
  reference: 'order_123',
  label: 'Coffee Purchase'
});

// Validate before processing
const validation = await validatePaymentRequest(request);
if (!validation.valid) {
  console.error('Invalid request:', validation.errors);
}

Transaction Building

import { buildTransaction, estimateGas } from '@arbitrum-pay/core';

// Build transaction for ETH payment
const ethTx = await buildTransaction({
  receiver: '0x742d35cc6634c0532925a3b8d4b9089d4',
  amount: '0.1',
  chainId: 42161
});

// Build transaction for ERC-20 token
const tokenTx = await buildTransaction({
  receiver: '0x742d35cc6634c0532925a3b8d4b9089d4',
  amount: '100',
  token: '0xA0b86a33E6441b33Bf93C7aa3e2E4E75b9f7B5B', // USDC
  chainId: 42161
});

URL Generation

import { createArbitrumPayURL, parseArbitrumPayURL } from '@arbitrum-pay/core';

// Create payment URL
const url = createArbitrumPayURL({
  receiver: '0x742d35cc6634c0532925a3b8d4b9089d4',
  amount: '0.1',
  chainId: 42161,
  label: 'Coffee Purchase'
});

// Parse payment URL
const parsed = parseArbitrumPayURL(url);
console.log(parsed.amount); // '0.1'

🌐 Supported Networks

• Arbitrum One (42161) - Production
• Arbitrum Sepolia (421614) - Testnet

🔧 Configuration

Environment Setup

import { configure } from '@arbitrum-pay/core';

configure({
  defaultChainId: 42161,
  rpcUrl: 'https://arb1.arbitrum.io/rpc',
  confirmations: 1
});

Custom Token Support

import { addCustomToken } from '@arbitrum-pay/core';

addCustomToken({
  symbol: 'MYTOKEN',
  address: '0x1234...5678',
  decimals: 18,
  chainId: 42161
});

📱 Integration Examples

E-commerce Integration

// 1. Create payment request
const payment = createPaymentRequest({
  receiver: process.env.MERCHANT_WALLET,
  amount: order.total.toString(),
  chainId: 42161,
  reference: order.id,
  label: `Order #${order.id}`,
  message: `Payment for ${order.items.length} items`
});

// 2. Generate payment link
const link = createPaymentLink(payment, {
  expiresIn: 1800, // 30 minutes
  redirectUrl: `${process.env.SITE_URL}/order/${order.id}/success`
});

// 3. Set up webhook for completion
await webhooks.deliverWebhook(process.env.WEBHOOK_URL, {
  type: 'payment.created',
  orderId: order.id,
  paymentLink: link.url
});

SaaS Subscription

// Monthly subscription payment
const subscription = createPaymentRequest({
  receiver: process.env.SUBSCRIPTION_WALLET,
  amount: plan.monthlyPrice,
  chainId: 42161,
  reference: `sub_${user.id}_${Date.now()}`,
  label: `${plan.name} Subscription`,
  message: `Monthly subscription for ${user.email}`
});

🔒 Security Best Practices

1. Validate all payment requests before processing
2. Use webhook signatures to verify authenticity
3. Set appropriate expiration times for payment links
4. Monitor for suspicious activity using live stats
5. Handle errors gracefully with proper user feedback

📚 TypeScript Support

Fully typed with comprehensive TypeScript definitions:

interface ArbitrumPayRequest {
  receiver: string;
  amount: string;
  token?: string;
  chainId: number;
  reference?: string;
  label?: string;
  message?: string;
}

interface ArbitrumPayStats {
  totalTransactions: number;
  totalVolume: string;
  last24hTransactions: number;
  successRate: number;
  recentTransactions: RecentTransaction[];
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT © Arbitrum Pay Team

🔗 Links

• Homepage
• Documentation
• GitHub
• Discord

Built with ❤️ for the Arbitrum ecosystem