Unifold Node.js API Client

The official Node.js library for the Unifold API.

Installation

npm install @unifold/node

Usage

The package needs to be configured with your API key, which is available in the Unifold Dashboard.

import Unifold from '@unifold/node';

const unifold = new Unifold('sk_test_...');

List users

const users = await unifold.users.list({ limit: 10 });

Payment intents

// Create a payment intent
const paymentIntent = await unifold.paymentIntents.create({
  amount: '10000000',           // 10 USDC (6 decimals)
  currency: 'usdc',
  destination_network: 'base',
  recipient_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0aB12',
  external_user_id: 'user_abc',
  metadata: { order_id: 'order_123' },
});
console.log(paymentIntent.client_secret);

// List payment intents with filters
const intents = await unifold.paymentIntents.list({
  limit: 25,
  user_id: 'user_2Qz9K5YX8r5C8jZ1bXZ8kQd7W5M',
});

// Retrieve a single payment intent
const intent = await unifold.paymentIntents.retrieve('pi_2Qz9K5YX8r5C8jZ1bXZ8kQd7W5M');

Auto-pagination

List methods support auto-pagination via for await...of, autoPagingEach, and autoPagingToArray:

// Async iterator
for await (const user of unifold.users.list({ limit: 100 })) {
  console.log(user.id);
}

// Collect into array
const allUsers = await unifold.users.list().autoPagingToArray({ limit: 1000 });

Configuration

The client accepts an optional configuration object:

const unifold = new Unifold('sk_test_...', {
  apiVersion: '2025-04-01',
  maxNetworkRetries: 3,
  timeout: 30000,         // 30 seconds
  host: 'api.unifold.io', // default
});

Per-request options

Most methods accept an optional RequestOptions object as the last argument:

const users = await unifold.users.list({ limit: 10 }, {
  apiKey: 'sk_test_other_key',  // override API key
  timeout: 5000,                // per-request timeout
  maxNetworkRetries: 0,         // disable retries
});

Events

unifold.on('request', (event) => {
  console.log('Request:', event.method, event.path);
});

unifold.on('response', (event) => {
  console.log('Response:', event.status, event.elapsed + 'ms');
});

Error handling

Errors from the API are thrown as typed UnifoldError subclasses:

import Unifold, {
  UnifoldError,
  UnifoldInvalidRequestError,
  UnifoldAuthenticationError,
  UnifoldRateLimitError,
} from '@unifold/node';

try {
  await unifold.treasury.accounts.create({ chain_type: 'ethereum' });
} catch (err) {
  if (err instanceof UnifoldInvalidRequestError) {
    console.log('Invalid request:', err.message);
    console.log('Param:', err.param);
  } else if (err instanceof UnifoldAuthenticationError) {
    console.log('Check your API key');
  } else if (err instanceof UnifoldRateLimitError) {
    console.log('Too many requests, slow down');
  } else if (err instanceof UnifoldError) {
    console.log('API error:', err.statusCode, err.message);
  } else {
    throw err;
  }
}

TypeScript

This library is written in TypeScript. All resource types are available on the Unifold namespace:

import Unifold from '@unifold/node';

const params: Unifold.UserListParams = {
  limit: 10,
  starting_after: 'usr_1234567890',
};

Requirements

The following runtimes are supported:

• Node.js 20 LTS or later (non-EOL) versions
• Deno v1.28.0 or higher
• Bun 1.0 or later
• Cloudflare Workers
• Vercel Edge Runtime
• Nitro v2.6 or greater

TypeScript 4.9+ is supported.