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. NodeRails supports EVM wallets (0x…) and Solana wallets (base58 public key). Use the merchant dashboard to connect and verify the address for each network. Funds settle here 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(s): EVM receiving/payout wallets and, if you enable Solana, your Solana settlement address.
2. Create a new App from the dashboard.
3. Select which chains and tokens you want to accept for this app.

Once your app is created, you will see the dashboard overview with your App ID, payment stats, configured wallets, and network breakdown:

Go to Settings to configure which blockchain networks your app accepts. Toggle the chains you want to enable:

2. Get your API keys

Navigate to Settings → API Keys tab in the dashboard. You'll need two pieces of information:

• App ID — Your app's unique identifier (UUID), visible at the top of your dashboard.
• 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 a numeric chain ID. EVM networks use the same IDs as elsewhere (e.g. Ethereum 1, Base 8453). Solana uses NodeRails cluster IDs: mainnet-beta 103, testnet 101, devnet 102 (enabled per deployment).

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

Tokens

Tokens use the same token key format on every chain: SYMBOL-chainId. On Solana, contractAddress in the API is the SPL mint (base58); on EVM it is the token contract (0x…).

This format ensures there's no ambiguity. USDC on Ethereum and USDC on Base (or USDC on Solana) are different tokens, so they have different token keys.

3. Install the SDK

npm install @noderails/sdk

pnpm add @noderails/sdk

yarn add @noderails/sdk

4. Initialize the client

Create a NodeRails client instance on your server. Pass your App ID and secret key from environment variables:

import { NodeRails } from "@noderails/sdk"

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

export default noderails

5. Create a checkout session

A checkout session generates a hosted payment page where your customer can select their blockchain and token, connect a wallet (WalletConnect on EVM or Solana wallet adapters), and complete the payment.

Call checkoutSessions.create from your server-side API route and redirect the customer to the returned checkout URL:

import noderails from "@/lib/noderails"

export async function POST(req: Request) {
  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,
      },
    ],
  })

  const checkoutUrl = `https://pay.noderails.com/session/${session.id}`
  return Response.json({ checkoutUrl })
}

Your customer will see the hosted checkout page where they can review the payment, check their wallet balance, and authorize the transaction:

By default, the checkout page shows the chains and tokens you configured for your app. You can restrict them for a specific session by passing allowedChains and allowedTokens:

const session = await noderails.checkoutSessions.create({
  successUrl: "https://yoursite.com/success",
  cancelUrl: "https://yoursite.com/cancel",
  allowedChains: [8453, 42161, 103],
  allowedTokens: ["USDC", "SOL"],
  items: [
    { name: "Enterprise License", amount: "499.00", quantity: 1 },
  ],
})

In this example, checkout can offer USDC on Base (8453), Arbitrum (42161), and Solana mainnet (103), plus SOL on Solana when enabled for your app. You can also pass specific token keys like USDC-8453 or USDC-103 instead of just the symbol.

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.

Verify the webhook signature using the SDK, then handle the event based on its type:

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":
          console.log("Payment captured:", event.data.id)
          break

        case "payment.settled":
          console.log("Payment settled:", event.data.id)
          break
      }

      res.sendStatus(200)
    } catch (err) {
      console.error("Webhook signature verification failed:", err)
      res.sendStatus(400)
    }
  },
)

payment.captured means funds have been authorized and locked in escrow. This is when you should fulfill the order. payment.settled means funds have been released from escrow and deposited to your wallet.

7. Track payments

Once payments start coming in, you can track them in real time from the Payments page in your dashboard. Each payment shows the amount, customer, network, status, and on-chain transaction hash:

Next steps