@apirail/payer-sdk

Payer SDK for PoAPW (Proof of API-Work) - A machine-native settlement protocol where APIs earn Cardano native tokens by delivering results.

Installation

npm install @apirail/payer-sdk

Quick Start

import { PayerSDK } from '@apirail/payer-sdk';

const payer = new PayerSDK({
  baseUrl: 'https://your-poapw-server.com',
  walletId: 'your-wallet-id',
});

// Call an API - payments are handled automatically
const result = await payer.callApi('api-route-id', { data: 'your-payload' });

if (result.success) {
  console.log('Response:', result.response);
  console.log('Response time:', result.responseTimeMs, 'ms');
}

Features

• Auto-Settle: Automatically settles on-chain when payment threshold is reached (enabled by default)
• Off-chain Accumulation: API calls accumulate off-chain until threshold, minimizing transaction costs
• Type-safe: Full TypeScript support with exported interfaces

Configuration

const payer = new PayerSDK({
  baseUrl: 'https://your-poapw-server.com',  // Required: PoAPW server URL
  walletId: 'your-wallet-id',                 // Required: Your payer wallet ID
  paymentMode: 'native',                      // Optional: 'native' or 'masumi' (default: 'native')
  autoSettle: true,                           // Optional: Auto-pay when threshold reached (default: true)
  onPaymentRequired: async (details) => {     // Optional: Custom settlement logic
    console.log('Payment required:', details.accumulatedAmount, 'tokens');
    return true; // Return true to settle, false to skip
  },
  onSettlement: (result) => {                 // Optional: Settlement callback
    console.log('Settled:', result.settledAmount, 'TX:', result.txHash);
  },
  onMasumiJob: (job) => {                     // Optional: Masumi job callback
    console.log('Masumi job started:', job.id);
  },
});

Payment Modes

The SDK supports two payment modes:

Native Mode (default)

Uses PoAPW's native token payment system with off-chain accumulation and batch settlement.

const payer = new PayerSDK({
  baseUrl: 'https://your-server.com',
  walletId: 'your-wallet-id',
  paymentMode: 'native',
});

Masumi Mode

Uses the Masumi Network protocol for AI agent payments with smart contract escrow.

const payer = new PayerSDK({
  baseUrl: 'https://your-server.com',
  walletId: 'your-wallet-id',
  paymentMode: 'masumi',
});

// Or switch modes at runtime
payer.setPaymentMode('masumi');

API Reference

callApi<T>(apiRouteId: string, payload?: unknown): Promise<ApiCallResult<T>>

Call a registered API. Handles payment flow automatically.

const result = await payer.callApi('api-id', { message: 'Hello' });
// result.success, result.response, result.httpStatus, result.responseTimeMs

getBalances(): Promise<BalanceInfo[]>

Get accumulated balances for all receivers.

const balances = await payer.getBalances();
// [{ receiverId, accumulatedAmount, paidAmount }]

settleBalance(receiverId: string): Promise<SettlementResult>

Manually trigger on-chain settlement for a receiver.

const result = await payer.settleBalance('receiver-wallet-id');
// result.success, result.txHash, result.settledAmount

getAvailableApis(): Promise<ApiRouteInfo[]>

List all available APIs on the network.

const apis = await payer.getAvailableApis();
// [{ id, name, endpoint, method, basePrice }]

getWalletInfo(): Promise<WalletInfo>

Get your wallet information including balance.

const wallet = await payer.getWalletInfo();
// { id, name, balance, cardanoAddress }

Payment Flow

1. Call API - SDK sends request to PoAPW server
2. Off-chain Accumulation - Tokens accumulate until threshold
3. 402 Response - When threshold reached, server returns 402
4. Auto-Settle - SDK automatically settles on-chain (if enabled)
5. Retry - SDK retries the API call after settlement
6. Success - API response returned to caller

License

MIT