Voltage API SDK

Official TypeScript/JavaScript SDK for the Voltage Payments API. This SDK provides a type-safe and developer-friendly way to interact with the Voltage API from both browser and Node.js environments.

Features

• 🌐 Universal: Works in both browser and Node.js environments
• 📝 TypeScript: Full TypeScript support with comprehensive type definitions
• 🔒 Authentication: Supports both API key and Bearer token authentication
• 🛡️ Error Handling: Robust error handling with custom error types
• ⚡ Modern: Built with modern JavaScript/TypeScript features
• 🧪 Well Tested: Comprehensive test suite
• 📦 Tree Shakable: ES modules with tree shaking support
• 🔐 Secure: Environment variable support for sensitive credentials

Module Compatibility

This SDK supports both CommonJS and ES Modules out of the box, making it compatible with all modern JavaScript environments:

ES Modules (ESM)

import { VoltageClient } from 'voltage-api-sdk';

CommonJS (CJS)

const { VoltageClient } = require('voltage-api-sdk');

Compatibility Matrix

| Environment | Import Style | Status | | ------------------- | ------------ | ------------ | | Node.js (ESM) | import | ✅ Supported | | Node.js (CommonJS) | require | ✅ Supported | | Browser (ESM) | import | ✅ Supported | | TypeScript | import | ✅ Supported | | Webpack | Both | ✅ Supported | | Rollup | Both | ✅ Supported | | Vite | Both | ✅ Supported | | n8n Community Nodes | Both | ✅ Supported |

The package uses explicit file extensions (.cjs for CommonJS, .esm.js for ES modules) to ensure maximum compatibility across all environments.

Installation

From npm (Recommended for production)

npm install voltage-api-sdk

From GitHub (Great for development)

# Install directly from GitHub
npm install git+https://github.com/voltage-api/sdk.git

# Or install a specific branch/tag
npm install git+https://github.com/voltage-api/sdk.git#main
npm install git+https://github.com/voltage-api/sdk.git#v1.0.0

Why use GitHub installation?

• ✅ Get the latest features immediately
• ✅ No need to wait for npm publishing
• ✅ Perfect for development and testing
• ✅ Works with private repositories

Example usage in your project's package.json:

{
  "dependencies": {
    "voltage-api-sdk": "^0.1.2"
  }
}

Then install with:

npm install
# or
yarn install

Quick Start

1. Installation

Choose one of the installation methods above, then continue with the setup.

2. Environment Setup

For security, use environment variables to store your API credentials:

# Copy the example environment file
cp .env.example .env

# Edit .env with your actual credentials

Your .env file should contain:

# Your Voltage API key (starts with vltg_)
VOLTAGE_API_KEY=vltg_your_actual_api_key_here

# Your organization ID (UUID format)
VOLTAGE_ORGANIZATION_ID=your-organization-id-here

# Optional: Custom base URL (defaults to https://voltageapi.com/v1)
VOLTAGE_BASE_URL=https://voltageapi.com/v1

# Optional: Request timeout in milliseconds (defaults to 30000)
VOLTAGE_TIMEOUT=30000

3. Basic Usage

import { VoltageClient } from 'voltage-api-sdk';

// Initialize the client with environment variables
const client = new VoltageClient({
  apiKey: process.env.VOLTAGE_API_KEY,
  baseUrl: process.env.VOLTAGE_BASE_URL || 'https://voltageapi.com/v1',
  timeout: parseInt(process.env.VOLTAGE_TIMEOUT || '30000'),
});

// Get all wallets in an organization
const wallets = await client.getWallets({
  organization_id: process.env.VOLTAGE_ORGANIZATION_ID,
});

console.log('Wallets:', wallets);

4. Run Example

# Make sure you've set up your .env file first
npm run example

Authentication

The SDK supports two authentication methods:

API Key Authentication

Direct usage:

const client = new VoltageClient({
  apiKey: 'vltg_your_api_key_here',
});

Using environment variables (recommended):

const client = new VoltageClient({
  apiKey: process.env.VOLTAGE_API_KEY,
});

Bearer Token Authentication

Direct usage:

const client = new VoltageClient({
  bearerToken: 'your_jwt_token_here',
});

Using environment variables (recommended):

const client = new VoltageClient({
  bearerToken: process.env.VOLTAGE_BEARER_TOKEN,
});

Configuration Options

interface VoltageApiConfig {
  baseUrl?: string; // API base URL, defaults to 'https://voltageapi.com/v1'
  apiKey?: string; // API key for authentication
  bearerToken?: string; // Bearer token for authentication
  timeout?: number; // Request timeout in milliseconds, defaults to 30000
}

Available Methods

Wallets

getWallets(params)

Get all wallets in an organization.

const wallets = await client.getWallets({
  organization_id: 'your-organization-id',
});

getWallet(params)

Get a specific wallet by ID.

const wallet = await client.getWallet({
  organization_id: 'your-organization-id',
  wallet_id: 'your-wallet-id',
});

createWallet(params)

Create a new wallet.

await client.createWallet({
  organization_id: 'your-organization-id',
  wallet: {
    id: 'new-wallet-id',
    environment_id: 'your-environment-id',
    line_of_credit_id: 'your-line-of-credit-id',
    name: 'My New Wallet',
    network: 'mutinynet',
    limit: 100000000,
    metadata: {
      description: 'A test wallet',
    },
  },
});

deleteWallet(params)

Delete a wallet.

await client.deleteWallet({
  organization_id: 'your-organization-id',
  wallet_id: 'wallet-to-delete',
});

Payment Requests

createPaymentRequest(params, pollingConfig?)

Create a new payment request (invoice) and wait for it to be ready. Payment IDs are automatically generated if not provided. This method automatically handles the polling logic to wait for the payment to be generated.

Lightning Payment Request:

const lightningPayment = await client.createPaymentRequest({
  organization_id: 'your-organization-id',
  environment_id: 'your-environment-id',
  payment: {
    // id is optional - will be auto-generated if not provided
    wallet_id: 'your-wallet-id',
    currency: 'btc',
    amount_msats: 150000, // 150 sats = 150,000 millisats
    payment_kind: 'bolt11',
    description: 'Payment for coffee',
  },
});

console.log('Payment request:', lightningPayment.data.payment_request);

On-chain Payment Request:

const onchainPayment = await client.createPaymentRequest({
  organization_id: 'your-organization-id',
  environment_id: 'your-environment-id',
  payment: {
    // id: "custom-payment-id", // Optional - auto-generated if not provided
    wallet_id: 'your-wallet-id',
    currency: 'btc',
    amount_msats: 1500000, // 1500 sats
    payment_kind: 'onchain',
    description: 'On-chain payment for services',
  },
});

console.log('Bitcoin address:', onchainPayment.data.address);

BIP21 Payment Request (Lightning + On-chain):

const bip21Payment = await client.createPaymentRequest({
  organization_id: 'your-organization-id',
  environment_id: 'your-environment-id',
  payment: {
    // id: "custom-payment-id", // Optional - auto-generated if not provided
    wallet_id: 'your-wallet-id',
    currency: 'btc',
    amount_msats: 250000, // 250 sats
    payment_kind: 'bip21',
    description: 'Flexible payment (Lightning or On-chain)',
  },
});

console.log('Lightning request:', bip21Payment.data.payment_request);
console.log('Bitcoin address:', bip21Payment.data.address);

Any Amount Invoice:

const anyAmountPayment = await client.createPaymentRequest({
  organization_id: 'your-organization-id',
  environment_id: 'your-environment-id',
  payment: {
    // id: "custom-payment-id", // Optional - auto-generated if not provided
    wallet_id: 'your-wallet-id',
    currency: 'btc',
    amount_msats: null, // "any amount" invoice
    payment_kind: 'bolt11',
    description: 'Any amount Lightning payment',
  },
});

Custom Polling Configuration:

const payment = await client.createPaymentRequest(
  {
    organization_id: 'your-organization-id',
    environment_id: 'your-environment-id',
    payment: {
      // id: "custom-payment-id", // Optional - auto-generated if not provided
      wallet_id: 'your-wallet-id',
      currency: 'btc',
      amount_msats: 150000,
      payment_kind: 'bolt11',
      description: 'Payment with custom polling',
    },
  },
  {
    maxAttempts: 20, // Maximum polling attempts (default: 30)
    intervalMs: 500, // Poll every 500ms (default: 1000ms)
    timeoutMs: 10000, // Timeout after 10 seconds (default: 30000ms)
  }
);

getPayment(params)

Get an existing payment by ID.

const payment = await client.getPayment({
  organization_id: 'your-organization-id',
  environment_id: 'your-environment-id',
  payment_id: 'your-payment-id',
});

console.log('Payment status:', payment.status);

Error Handling

The SDK includes a custom VoltageApiError class that provides detailed error information:

import { VoltageApiError } from 'voltage-api-sdk';

try {
  const wallets = await client.getWallets({ organization_id: 'invalid-id' });
} catch (error) {
  if (error instanceof VoltageApiError) {
    console.error('API Error:', error.message);
    console.error('Status Code:', error.status);
    console.error('Error Code:', error.code);
    console.error('Details:', error.details);
  } else {
    console.error('Unexpected error:', error);
  }
}

Environment Compatibility

Node.js

The SDK works with Node.js 16+ and automatically uses the built-in fetch API in Node.js 18+. For Node.js 16-17, it will fallback to the cross-fetch polyfill.

Browser

The SDK works in all modern browsers that support the fetch API. For older browsers, you may need to include a fetch polyfill.

TypeScript Support

The SDK is written in TypeScript and includes comprehensive type definitions. All API responses and request parameters are fully typed:

import type { Wallet, VoltageApiConfig, VoltageApiError } from 'voltage-api-sdk';

// Full type safety
const config: VoltageApiConfig = {
  apiKey: 'your-key',
  timeout: 10000,
};

const client = new VoltageClient(config);
const wallets: Wallet[] = await client.getWallets({ organization_id: 'id' });

Development

Setup

# Install dependencies
npm install

# Copy environment template and configure your credentials
cp .env.example .env
# Edit .env with your actual API credentials

Development Dependencies Added:

• dotenv - For loading environment variables
• tsx - For running TypeScript files directly

Note on dist folder: The dist folder is committed to enable direct GitHub installations. The prepare script automatically rebuilds the project when needed.

Building

npm run build

Testing

npm test

Running Examples

npm run example

Linting and Formatting

npm run lint
npm run format

Examples

See the examples directory for more usage examples:

• Basic Usage - Complete example with environment variables
• Payment Requests - Complete examples for creating payment requests

Taproot Assets (Generic)

The API supports Taproot Assets on supported networks (e.g., mutinynet). The SDK works with any Taproot Asset by using the asset group key string in the asset: currency format.

Receive a Taproot Asset payment (generic):

import { VoltageClient } from 'voltage-api-sdk';

const client = new VoltageClient({ apiKey: process.env.VOLTAGE_API_KEY });

// Replace with the asset group key you want to receive
const ASSET = 'asset:034d8de991e76a6994753ddb4505d354873f96a1aa400a82eac1ee4fd443cfd62e';

const payment = await client.createPaymentRequest({
  organization_id: process.env.VOLTAGE_ORGANIZATION_ID!,
  environment_id: process.env.VOLTAGE_ENVIRONMENT_ID!,
  payment: {
    // id is optional; auto-generated if omitted
    wallet_id: process.env.VOLTAGE_WALLET_ID!,
    payment_kind: 'taprootasset',
    // For Taproot Assets, specify the Amount with currency as the asset group key
    amount: { currency: ASSET, amount: 1_000_000, unit: 'base units' },
    description: 'Receive Taproot Asset',
  },
});

// payment.type === 'taprootasset'
console.log('Taproot Asset invoice:', payment.data.payment_request);

Send a Taproot Asset payment (generic):

import { VoltageClient } from 'voltage-api-sdk';

const client = new VoltageClient({ apiKey: process.env.VOLTAGE_API_KEY });
const ASSET = 'asset:034d8de991e76a6994753ddb4505d354873f96a1aa400a82eac1ee4fd443cfd62e';

const result = await client.sendPayment({
  organization_id: process.env.VOLTAGE_ORGANIZATION_ID!,
  environment_id: process.env.VOLTAGE_ENVIRONMENT_ID!,
  payment: {
    // id is optional; auto-generated if omitted
    wallet_id: process.env.VOLTAGE_WALLET_ID!,
    currency: ASSET,
    type: 'taprootasset',
    data: {
      payment_request: '<taproot-asset-invoice>',
      asset: '034d8de991e76a6994753ddb4505d354873f96a1aa400a82eac1ee4fd443cfd62e', // group key without `asset:` prefix
      amount: { currency: ASSET, amount: 1_000_000, unit: 'base units' },
      // max_fee can be in BTC msats or asset base units depending on route
      max_fee: { currency: 'btc', amount: 10_000 },
    },
  },
});

console.log('Send status:', result.status);

Note on statuses: the API may return a transient approved state before generation or completion. The SDK automatically treats approved as a loading state during polling.

Security Best Practices

• ✅ Use environment variables for API keys and sensitive data
• ✅ Never commit .env files to version control
• ✅ Use .env.example to document required environment variables
• ✅ Validate environment variables before using them

API Reference

For complete API documentation, refer to the Voltage Payments API documentation.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Run the test suite
6. Submit a pull request

License

MIT License. See LICENSE for details.

Support

For support, please visit the Voltage documentation or contact support through the official channels.