Blockia Pay SDK

A TypeScript SDK for interacting with the Blockia Pay payment protocol, supporting ERC-3009 token transfers with EIP-712 signatures.

Installation

npm install @blockia-pay/sdk

Quick Start

import { BlockiaAgent } from '@blockia-pay/sdk';

// Initialize the agent
const agent = new BlockiaAgent({
  apiUrl: 'https://api.blockia.pay',
  privateKey: '0x...', // Your private key
  chainId: 84532, // Base Sepolia (default)
});

// Get payment requirements for a payment
const requirements = await agent.getPaymentRecordInfo('recordId');

// Select preferred payment option (auto-prefers Base + USDC)
const requirement = await agent.selectPaymentRequirement(requirements);

// Make payment
const result = await agent.makePayment(requirement);
console.log('Payment successful:', result.txHash);

Examples

The examples/ directory contains runnable scripts demonstrating different usage patterns:

Simple Payment Script

cd examples
node simple-payment.ts <private-key> <payment-id>

Demonstrates the convenience makePayment() method that handles the entire payment flow automatically.

Fetch with Payment Script

cd examples
node fetch-with-payment.ts <private-key> <protected-url>

Demonstrates the fetchWithPayment() method that automatically handles X402 payment requirements when making HTTP requests to protected resources.

Create Payment Payload Script

cd examples
node create-payment-payload.ts <private-key> <payment-id>

Demonstrates how to create a base64url-encoded X402 payment payload for use in X-PAYMENT headers.

Core Features

• Payment Flow

  • Fetch Requirements: Get available payment options for a payment
  • Select Option: Choose preferred network/asset (auto-prefers Base + USDC)
  • Check Balance: Verify sufficient funds
  • Sign & Submit: Create EIP-712 signature and submit payment

• Supported Networks

  • Ethereum: Mainnet, Sepolia
  • Polygon: Mainnet, Amoy
  • Arbitrum: Mainnet, Sepolia
  • Optimism: Mainnet, Sepolia
  • Base: Mainnet, Sepolia (default)
  • BSC: Mainnet, Testnet

• ERC-3009 Support

  • EIP-712 typed data signing
  • 1-hour validity window
  • Secure nonce generation
  • Batched contract calls for efficiency

API Reference

Constructor

new BlockiaAgent(config: BlockiaAgentConfig)

Key Methods

• getBalance(tokenAddress, ownerAddress) – Check token balance
• getPaymentRecordInfo(recordId) – Fetch payment requirements
• makePayment(requirement) – Complete payment in one call

Convenience Methods

• selectPaymentRequirement(requirements, options?) – Filter and sort payment options
• selectByNetwork() – Filter by network (Base, Ethereum, etc.)
• selectByScheme() – Filter by payment scheme
• selectByAsset() – Filter by token address

Error Handling

import { NetworkError, ValidationError } from '@blockia-pay/sdk';

try {
  await agent.makePayment(requirement);
} catch (error) {
  if (error instanceof ValidationError) {
    // Handle validation issues
  } else if (error instanceof NetworkError) {
    // Handle API/network issues
  }
}

Advanced Usage

For more control, use the individual methods:

// Manual payment flow
const payload = await agent.createPaymentPayload(requirement);
const result = await agent.submitPayment(requirement, payload);

// Custom requirement selection
const requirement = await agent.selectPaymentRequirement(requirements, {
  network: 'base',
  asset: 'USDC',
});

Requirements

• Node.js 18+
• TypeScript 5.0+
• EVM-compatible wallet with USDC balance

Security

• Private keys never leave the client
• All signatures generated locally
• Secure nonce generation using crypto.getRandomValues
• Input validation for all addresses and parameters