@payweave/core

Core SDK for PayWeave - the payment layer for AI agents. Accept per-request USD micropayments via the Machine Payment Protocol (MPP).

Install

npm install @payweave/core

Most users should install a framework adapter instead (@payweave/express, @payweave/hono, @payweave/next, or @payweave/fastify). The core package is used directly only for custom integrations.

Usage

import { PayWeave } from '@payweave/core';

const payweave = new PayWeave({
  appId: 'app_xxxxxxxxxxxx',
  appSecret: process.env.PAYWEAVE_APP_SECRET!,
});

// Initialize and fetch app config
const config = await payweave.initialize();
console.log(config.mode);    // 'test' or 'live'
console.log(config.wallet);  // your wallet address
console.log(config.network); // 'tempo'

// Record a settlement event
await payweave.recordSettlement({
  transactionHash: '0x...',
  payerAddress: '0x...',
  amount: '0.001',
  network: 'tempo',
  httpMethod: 'GET',
  httpPath: '/api/weather',
});

API

new PayWeave(config)

| Parameter | Type | Description | |-----------|------|-------------| | config.appId | string | Your app key ID | | config.appSecret | string | Your app secret (sk_test_ or sk_live_ prefix) | | config.baseUrl | string? | API base URL (defaults to https://api.payweave.app) |

payweave.initialize()

Fetches and caches your app configuration. Returns MppInitResponse:

{
  mode: 'test' | 'live';
  wallet: string | null;
  currency: string;
  network: string;
  discoverable: boolean;
  quota: { used: number; limit: number; exceeded: boolean };
}

payweave.recordSettlement(event)

Records a payment settlement event.

payweave.config

Returns the cached config (or null before initialize()).

payweave.secret

Returns the app secret key.

payweave.mode

Returns 'test' or 'live' based on the secret prefix.

PayweaveBase

The base class for building custom framework adapters. All official adapters (@payweave/express, @payweave/hono, etc.) extend this class.

import { PayweaveBase } from '@payweave/core';

class MyAdapter extends PayweaveBase {
  charge(options) {
    return async (req, res) => {
      const result = await this.processCharge(
        env,
        options.price,
        options.description,
        req.method,
        req.path,
        paymentCredential,
        options.meta
      );

      if (result.status === 402) {
        // Return 402 with challenge headers
      }
      // Continue with Payment-Receipt header
    };
  }
}

Payment Flow

1. Agent calls your API without a payment header
2. Your middleware responds with 402 Payment Required and a WWW-Authenticate header
3. Agent submits payment on Tempo and retries with the payment credential
4. PayWeave verifies the payment, returns a Payment-Receipt header
5. Your handler executes and returns the response

Error Classes

• PayWeaveError - Base error
• PayWeaveConfigError - Invalid configuration
• PayWeaveQuotaExceededError - Quota exceeded
• PayWeaveSettlementError - Settlement failed
• PayWeaveVerificationError - Payment verification failed
• PayWeaveNetworkError - Network error
• PayWeaveEventError - Event recording error
• PayweaveChargeError - Charge processing error

License

MIT