@waterfall-finance/sdk

Waterfall TypeScript SDK

TypeScript SDK for x402 payments with OpenRouter. This is a 1:1 port of the Python waterfall SDK.

Installation

npm install @waterfall-finance/sdk

Quick Start

import { WaterfallClient, createClient } from "@waterfall-finance/sdk";

// Option 1: Use the convenience function
const client = await createClient("wf_your_api_key");

// Option 2: Manual initialization
const client = new WaterfallClient({
  apiKey: "wf_your_api_key",
});
await client.configureWallet(); // Uses default wallet

// Make a chat completion request
const response = await client.chat.send({
  model: "openai/gpt-3.5-turbo",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);

Features

• Automatic x402 Payment Handling: The SDK automatically handles 402 Payment Required responses
• OpenRouter Integration: Full access to OpenRouter's model catalog
• Wallet Management: Create, list, and manage wallets
• Streaming Support: Stream chat completions for real-time responses
• TypeScript First: Full type definitions included

API Reference

WaterfallClient

The main client class for interacting with Waterfall.

const client = new WaterfallClient({
  apiKey: "wf_...", // Your Waterfall API key
  walletId: "...", // Optional: specific wallet ID
  backendUrl: "...", // Optional: custom backend URL
  proxyUrl: "...", // Optional: custom x402 proxy URL
});

Client Methods

configureWallet(options?)

Configure which wallet to use for payments.

// Use default wallet
await client.configureWallet();

// Use wallet by name
await client.configureWallet({ walletName: "My Wallet" });

// Use wallet by ID
await client.configureWallet({ walletId: "wallet_123" });

listWallets()

List all wallets associated with your API key.

const wallets = await client.listWallets();
console.log(wallets);
// [{ id: "...", name: "...", address: "0x...", network: "base-mainnet" }, ...]

createWallet(options)

Create a new wallet.

const wallet = await client.createWallet({
  name: "My New Wallet",
  useTestnet: false, // Optional: use Base Sepolia testnet
  teamId: "...", // Optional: team ID
});

Chat API

chat.send(options)

Send a chat completion request.

const response = await client.chat.send({
  model: "openai/gpt-4",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is the capital of France?" },
  ],
  temperature: 0.7,
  maxTokens: 1000,
});

chat.stream(options)

Stream a chat completion response.

const stream = await client.chat.stream({
  model: "openai/gpt-3.5-turbo",
  messages: [{ role: "user", content: "Tell me a story" }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Supported Models

Any model available on OpenRouter can be used:

• openai/gpt-4
• openai/gpt-3.5-turbo
• anthropic/claude-3-opus
• anthropic/claude-3-sonnet
• google/gemini-pro
• meta-llama/llama-3-70b-instruct
• And many more...

How It Works

• Initial Request: Client sends request to the x402 proxy
• 402 Response: Proxy returns 402 Payment Required with payment details
• Payment Signing: SDK automatically signs the payment via Coinbase CDP wallet
• Retry: SDK retries the request with the payment signature
• Success: Proxy verifies signature and forwards to OpenRouter

Your Code
    ↓
WaterfallClient.chat.send()
    ↓
x402 Proxy
    ↓
[402 Payment Required]
    ↓
Waterfall Backend (signs payment)
    ↓
[Payment Signature]
    ↓
Retry with signature
    ↓
OpenRouter API
    ↓
AI Model Response

Configuration

Environment Variables

You can also set the API key via environment variable:

export WATERFALL_API_KEY=wf_your_api_key

const client = new WaterfallClient({
  apiKey: process.env.WATERFALL_API_KEY,
});

Custom URLs

Override default URLs if needed:

const client = new WaterfallClient({
  apiKey: "wf_...",
  backendUrl: "https://your-custom-backend.convex.site",
  proxyUrl: "https://your-custom-proxy.com",
});

Error Handling

try {
  const response = await client.chat.send({
    model: "openai/gpt-4",
    messages: [{ role: "user", content: "Hello!" }],
  });
} catch (error) {
  if (error.message.includes("Invalid or missing Waterfall API key")) {
    console.error("Check your API key");
  } else if (error.message.includes("Payment failed")) {
    console.error("Payment signing failed - check wallet balance");
  } else {
    console.error("Unexpected error:", error);
  }
}

License

MIT