Quick Start

Accept your first crypto payment in under 5 minutes. This guide walks you through setting up your account, configuring your payment preferences, and processing a payment.

What you'll need

Before you start integrating, you need to set up a few things in the NodeRails Dashboard:

1. A NodeRails account with a verified email address.
2. A connected wallet where you want to receive payments. This is the wallet funds will settle to after the timelock period.
3. An App created in the dashboard. Each app gets its own API keys, webhook endpoints, and payment configuration.
4. Chains and tokens selected. You need to choose which blockchains and tokens you want to accept payments in. This is configured per app in the dashboard.

1. Create your account and app

Sign up at the NodeRails Dashboard and verify your email. Then:

1. Connect your merchant wallet (this is where your settled funds go).
2. Create a new App from the dashboard.
3. Select which chains and tokens you want to accept for this app.

2. Get your API keys

Navigate to Apps → Your App → API Keys in the dashboard. You'll need two pieces of information:

• App ID: Your app's unique identifier (UUID)
• Secret Key: Starts with nr_live_sk_ or nr_test_sk_

API Key format

API keys follow the format nr_<env>_<type>_<random>:

Chains and tokens naming

When working with the NodeRails API or SDK, chains and tokens follow a specific naming convention you should be aware of.

Chains

Chains are identified by their chain ID, the same numeric ID you use everywhere else in the blockchain ecosystem. For example:

When you pass allowedChains in the API, you pass an array of these numeric IDs.

Tokens

Tokens are identified using a token key in the format SYMBOL-chainId. This combines the token symbol with the chain it lives on. For example:

This format ensures there's no ambiguity. USDC on Ethereum and USDC on Base are different tokens at different contract addresses, so they have different token keys.

3. Install the SDK

npm install @noderails/sdk

Or with your preferred package manager:

pnpm add @noderails/sdk
# or
yarn add @noderails/sdk

4. Initialize the client

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

const noderails = new NodeRails({
  appId: process.env.NODERAILS_APP_ID!,
  apiKey: process.env.NODERAILS_SECRET_KEY!, // nr_live_sk_...
});

5. Create a checkout session

A checkout session creates a hosted payment page where your customer can select their blockchain and token, connect their wallet, and complete the payment.

// POST /api/create-checkout (your server endpoint)
const session = await noderails.checkoutSessions.create({
  successUrl: 'https://yoursite.com/success?session={CHECKOUT_SESSION_ID}',
  cancelUrl: 'https://yoursite.com/cancel',
  items: [
    {
      name: 'Pro Plan',
      amount: '29.99',
      quantity: 1,
    },
  ],
});

// Redirect customer to the hosted checkout page
return { checkoutUrl: `https://pay.noderails.com/session/${session.id}` };

By default, the checkout page shows the chains and tokens you configured for your app. You can override them for a specific session:

const session = await noderails.checkoutSessions.create({
  successUrl: 'https://yoursite.com/success',
  cancelUrl: 'https://yoursite.com/cancel',
  // Override: only accept payments on Base and Arbitrum
  allowedChains: [8453, 42161],
  // Accept USDC on any of those chains
  allowedTokens: ['USDC'],
  // Or be specific with token keys:
  // allowedTokens: ['USDC-8453', 'USDC-42161'],
  items: [
    { name: 'Enterprise License', amount: '499.00', quantity: 1 },
  ],
});

6. Handle the webhook

After the customer completes payment, NodeRails sends a payment.captured event to your webhook endpoint once funds are taken from the customer's wallet and locked in escrow on-chain. This is your signal to fulfill the order:

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

const app = express();

app.post('/webhooks/noderails', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = NodeRails.webhooks.constructEvent(
      req.body,
      req.headers['x-noderails-signature'] as string,
      req.headers['x-noderails-timestamp'] as string,
      process.env.WEBHOOK_SECRET!,
    );

    switch (event.event) {
      case 'payment.captured':
        // Payment captured, fulfill the order
        console.log('Payment captured:', event.data.id);
        break;
      case 'payment.settled':
        // Funds settled to your wallet
        console.log('Payment settled:', event.data.id);
        break;
    }

    res.sendStatus(200);
  } catch (err) {
    console.error('Webhook error:', err);
    res.sendStatus(400);
  }
});

Next steps