Official NexFlow SDK for metered API endpoints
npm install nexflow-sdkbash
npm install nexflow-sdk
`
Quick Start
`typescript
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
$3
Create a new NexFlow client.
`typescript
const nf = new NexFlow({
apiKey: 'nf_live_xxx', // Required: Your API key
baseUrl: 'https://...', // Optional: Custom API URL
timeout: 30000, // Optional: Request timeout (ms)
});
`
$3
Create a new metered endpoint.
`typescript
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'
});
`
$3
List all endpoints for your account.
`typescript
const { endpoints } = await nf.endpoints.list();
for (const ep of endpoints) {
console.log(ep.name, ep.pricePerCall);
}
`
$3
Get billing summary for an endpoint.
`typescript
const summary = await nf.endpoints.summary('ep_xxx');
console.log(Calls this month: ${summary.thisMonth.calls});
console.log(Revenue: $${summary.thisMonth.creatorNet} USDC);
`
$3
Execute a metered call through your endpoint.
`typescript
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:
`typescript
const result = await nf.run('ep_xxx', payload, {
upstreamAuth: 'Bearer sk-xxx'
});
`
$3
Get usage summary for your account.
`typescript
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:
`typescript
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
$3
`typescript
interface RunResponse {
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;
};
}
`
$3
`typescript
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;
}>;
}
``