nexflow-sdk

Official TypeScript SDK for NexFlow - metered API endpoints with built-in usage tracking and billing.

Installation

npm install nexflow-sdk

Quick Start

import { NexFlow } from 'nexflow-sdk';

const nf = new NexFlow({
  apiKey: process.env.NEXFLOW_API_KEY!
});

// Create a metered endpoint
const { endpoint } = await nf.endpoints.create({
  name: 'My API',
  upstreamUrl: 'https://api.example.com/v1/data',
  pricePerCall: '0.001', // USDC per call
  recipientAddress: '0xYourWallet...'
});

// Run a metered call
const result = await nf.run(endpoint.id, { query: 'hello' });
console.log(result.data);
console.log(`Charged: $${result.billing.pricePerCall} USDC`);

API Reference

new NexFlow(config)

Create a new NexFlow client.

const nf = new NexFlow({
  apiKey: 'nf_live_xxx',        // Required: Your API key
  baseUrl: 'https://...',       // Optional: Custom API URL
  timeout: 30000,               // Optional: Request timeout (ms)
});

nf.endpoints.create(request)

Create a new metered endpoint.

const { endpoint } = await nf.endpoints.create({
  name: 'OpenAI Proxy',
  upstreamUrl: 'https://api.openai.com/v1/chat/completions',
  pricePerCall: '0.01',         // USDC
  platformFeeBps: 200,          // 2% platform fee (optional)
  recipientAddress: '0x...',
  network: 'base',              // Optional, defaults to 'base'
});

nf.endpoints.list()

List all endpoints for your account.

const { endpoints } = await nf.endpoints.list();
for (const ep of endpoints) {
  console.log(ep.name, ep.pricePerCall);
}

nf.endpoints.summary(endpointId)

Get billing summary for an endpoint.

const summary = await nf.endpoints.summary('ep_xxx');
console.log(`Calls this month: ${summary.thisMonth.calls}`);
console.log(`Revenue: $${summary.thisMonth.creatorNet} USDC`);

nf.run(endpointId, payload, options?)

Execute a metered call through your endpoint.

const result = await nf.run('ep_xxx', { 
  prompt: 'Hello world' 
});

console.log(result.data);              // Upstream response
console.log(result.billing.pricePerCall); // "0.001"
console.log(result.usage.daily);       // 42 calls today

With upstream authentication:

const result = await nf.run('ep_xxx', payload, {
  upstreamAuth: 'Bearer sk-xxx'
});

nf.usage.summary()

Get usage summary for your account.

const usage = await nf.usage.summary();
console.log(`Plan: ${usage.plan.name}`);
console.log(`Today: ${usage.today.used}/${usage.plan.dailyLimit}`);
console.log(`Month: ${usage.month.used}/${usage.plan.monthlyLimit}`);

Error Handling

The SDK throws typed errors for different scenarios:

import { 
  NexFlow, 
  QuotaExceededError, 
  AuthenticationError,
  NotFoundError 
} from 'nexflow-sdk';

try {
  await nf.run('ep_xxx', payload);
} catch (error) {
  if (error instanceof QuotaExceededError) {
    console.log('Quota exceeded!');
    console.log(`Daily: ${error.usage.daily}/${error.limits.dailyLimit}`);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.log('Endpoint not found');
  }
}

Response Types

RunResponse

interface RunResponse<T> {
  success: boolean;
  data: T;                    // Upstream response
  billing: {
    pricePerCall: string;     // "0.001"
    platformCut: string;      // "0.00002"
    creatorNet: string;       // "0.00098"
  };
  usage: {
    daily: number;
    monthly: number;
    dailyLimit: number;
    monthlyLimit: number;
  };
  meta: {
    endpointId: string;
    endpointName: string;
    upstreamStatus: number;
    responseTimeMs: number;
  };
}

UsageSummary

interface UsageSummary {
  plan: {
    name: string;
    dailyLimit: number;
    monthlyLimit: number;
  };
  today: { used: number; remaining: number };
  month: { used: number; remaining: number };
  topEndpoints?: Array<{
    endpointId: string;
    name: string;
    calls: number;
  }>;
}

Plans & Limits

| Plan | Daily Limit | Monthly Limit | |------|-------------|---------------| | Free | 1,000 | 10,000 | | Starter | 5,000 | 50,000 | | Pro | 25,000 | 250,000 | | Enterprise | 100,000 | 1,000,000 |

License

MIT