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

Documentation

• Architecture & State Machine
• Smart Accounts (FAQ)
• Error Handling

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 Overview for more details.

• 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:

UPSConfig Options

Option	Type	Default	Description
baseUrl	string	Required	The UPS Backend API URL.
network	string	Required	The target blockchain network (e.g., eip155:737998412).
timeout	number	30000	Request timeout in milliseconds.
retryAttempts	number	3	Number of retries for failed idempotent requests.
refreshInterval	number	60000	Auth token auto-refresh interval (ms).

Warning

Safety Warning: Ensure your network configuration matches the environment you are connecting to (Testnet vs Mainnet). Mismatched configurations can lead to stuck transactions or loss of funds if signed on the wrong chain.

Infrastructure Interoperability

The SDK is designed to be agnostic of the underlying RPC provider for signing, but relies on the UPS Backend for reading and relaying.

• Signing: Uses the standard EIP-1193 provider (e.g., window.ethereum) injected by wallets like MetaMask or Coinbase Wallet. You can bring any supported wallet.
• Relaying: All transactions are relayed via the UPS Backend to ensure gas abstraction and x402 protocol compliance. You do not need your own RPC node for transaction submission.

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