UPS x402 SDK

TypeScript SDK for the x402 Universal Payments Protocol — enabling seamless blockchain payments with Smart Accounts.

Features

• 🔐 Smart Account Management — Create and manage EIP-4337 compatible accounts
• 💸 x402 Payments — EIP-3009 transfer authorizations with typed signatures
• ⚛️ React Hooks — First-class React integration with TanStack Query
• 🔄 Multi-Chain — TAU, Base, Base Sepolia, and Ethereum Mainnet support
• 📦 Dual Build — ESM and CommonJS compatible

Installation

# Using pnpm (recommended)
pnpm add @gatewayfm/ups-sdk

# For React projects
pnpm add @gatewayfm/ups-sdk @gatewayfm/ups-react

Quick Start

Node.js / Vanilla TypeScript

import { UPSClient } from '@gatewayfm/ups-sdk';

const client = new UPSClient({
    baseUrl: 'https://api.ups.example.com',
    network: 'eip155:737998412', // TAU Testnet
});

// Connect wallet (EIP-1193 provider)
await client.connect(window.ethereum);

// Authenticate with the UPS backend
await client.authenticate();

// Create a Smart Account
const { account, txHash } = await client.account.create({
    ownerAddress: client.wallet.getAddress()!,
    salt: '0x' + crypto.randomUUID().replace(/-/g, '').padEnd(64, '0'),
});

console.log('Account created:', account.walletAddress);

React

import { UPSProvider, useWallet, useAccount, usePayment } from '@gatewayfm/ups-react';

function App() {
    return (
        <UPSProvider config={{ baseUrl: '...', network: 'eip155:737998412' }}>
            <PaymentFlow />
        </UPSProvider>
    );
}

function PaymentFlow() {
    const { connect, isConnected, address } = useWallet();
    const { createAccount } = useAccount();
    const { pay, isPaying } = usePayment();

    return (
        <div>
            {!isConnected ? (
                <button onClick={() => connect(window.ethereum)}>
                    Connect Wallet
                </button>
            ) : (
                <p>Connected: {address}</p>
            )}
        </div>
    );
}

Packages

Package	Description	Docs
@gatewayfm/ups-sdk	Core SDK — wallet, account, and payment modules	README
@gatewayfm/ups-react	React hooks and context provider	README
@gatewayfm/test-utils	Testing utilities and mocks	—

Examples

See the examples/ directory:

• Basic Node.js — Standalone TypeScript example
• Basic Node.js — Standalone TypeScript example
• React + Vite — Full React application
• React Invoice — Invoice Management application
• React Escrow — Escrow Payment application

# Run the basic example
cd examples/basic
pnpm install
pnpm start

Documentation

SDK Modules

client.wallet — Wallet connection and signing

await client.connect(provider);          // Connect EIP-1193 wallet
await client.wallet.signMessage(msg);    // Sign personal message
await client.wallet.signTypedData(data); // Sign EIP-712 typed data
client.wallet.getAddress();              // Get connected address

client.account — Smart Account management

await client.account.list();             // List user's accounts
await client.account.create(params);     // Create new account
await client.account.predictAddress(p);  // Predict future address

client.payment — x402 payment flow

await client.payment.pay({ requirements, from });  // Full payment flow
await client.payment.verify(signed, requirements); // Verify before settling
await client.payment.settle(signed, requirements); // Settle on-chain
await client.payment.payInvoice(invoice, { amount, asset, network });

client.invoice — Invoice operations

await client.invoice.create({ amount, due_date, ... });
await client.invoice.list({ merchant: '0x...' });

React Hooks

Hook	Purpose
useWallet()	Wallet connection, address, chain ID
useAuth()	Authentication state and actions
useAccount()	Account CRUD with query caching
useAccount()	Account CRUD with query caching
usePayment()	Payment execution with loading states
useInvoice()	Invoice management hooks
useUPSClient()	Direct SDK client access

Development

Prerequisites

• Node.js >= 18
• pnpm >= 9

Setup

git clone https://github.com/gateway-fm/ups-typescript.git
cd ups-typescript
pnpm install
pnpm build

Commands

Command	Description
pnpm build	Build all packages
pnpm test	Run unit tests
pnpm test:coverage	Run tests with coverage
pnpm lint	Lint all packages
pnpm typecheck	TypeScript type checking
pnpm dev	Watch mode

Configuration

Create a .env file:

API_BASE_URL=https://api.ups.example.com
BLOCKCHAIN_RPC_URL=https://sepolia.base.org
BLOCKCHAIN_CHAIN_ID=84532

See SECRETS.md for handling sensitive keys.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

License

MIT © Gateway.fm

---

Built with ❤️ for the x402 ecosystem