Installation & Configuration

The official Node.js SDK for integrating NodeRails crypto payments. Zero runtime dependencies, full TypeScript support, and cross-runtime compatibility.

Installation

Installbash

npm install @noderails/sdk

Requirements

Node.js 18+ (uses native fetch)
Also works in Deno and Bun
TypeScript 5+ recommended (full type inference)

Configuration

Initialize the clienttypescript

import { NodeRails } from '@noderails/sdk';

const noderails = new NodeRails({
  appId: 'your-app-id',          // Required: your app UUID
  apiKey: 'nr_live_sk_...',      // Required: secret API key
  baseUrl: 'https://api.noderails.com', // Optional: override API URL
  timeout: 30000,                // Optional: request timeout in ms
  apiVersion: '2026-03-07',      // Optional: pin to a specific API version
});

Option	Type	Default	Description
`appId`	`string`		Your app UUID from the dashboard
`apiKey`	`string`		Secret API key (`nr__sk_`)
`baseUrl`	`string`	`https://api.noderails.com`	Override the API base URL
`timeout`	`number`	`30000`	Request timeout in milliseconds
`apiVersion`	`string`	Latest	Pin requests to a specific API version

⚠️

Secret keys only

The SDK requires a secret key (sk). Public keys cannot be used as they are for client-side operations only.

Common patterns

Pagination

All list endpoints return a PaginatedResult with data and pagination:

Paginated resultstypescript

const result = await noderails.paymentIntents.list({
  page: 1,
  pageSize: 50,
  status: 'CAPTURED',
});

console.log(result.data);              // PaymentIntent[]
console.log(result.pagination.total);  // Total count
console.log(result.pagination.totalPages); // Total number of pages

Idempotency keys

For safe retries, pass an idempotency key on any mutating request. If you send the same key twice, you'll get back the same response without creating a duplicate.

Idempotent requeststypescript

const intent = await noderails.paymentIntents.create(
  {
    amount: '100.00',
    currency: 'USD',
  },
  { idempotencyKey: 'order_456' },
);

Authentication header

The SDK automatically sends your API key using the x-api-key header. Manually, the headers look like:

HTTP headerstext

x-api-key: nr_live_sk_abc123...
    Content-Type: application/json

Response format

API responses use a standard envelope. The SDK unwraps this automatically so you always get the data directly:

Raw API response (unwrapped by SDK)json

{
  "success": true,
  "data": {
    "id": "abc123...",
    "status": "OPEN",
    ...
  }
}

TypeScript support

All request parameters and response types are fully typed. Import types directly from the SDK:

Type importstypescript

import type {
  CheckoutSession,
  CheckoutSessionCreateParams,
  PaymentIntent,
  PaymentIntentCreateParams,
  Invoice,
  Subscription,
  PaginatedResult,
} from '@noderails/sdk';