Neutron SDK

The official TypeScript/Node.js SDK for Neutron — Bitcoin Lightning, stablecoins, and fiat payments through a single API.

Install

npm install neutron-sdk

Prerequisites

Sign up at portal.neutron.me to get your API key and secret.

Quick Start

import { Neutron } from "neutron-sdk";

const neutron = new Neutron({
  apiKey: process.env.NEUTRON_API_KEY!,
  apiSecret: process.env.NEUTRON_API_SECRET!,
});

// Check your balances
const wallets = await neutron.account.wallets();
console.log(wallets); // [{ ccy: "BTC", availableBalance: 0.05 }, ...]

// Create a Lightning invoice
const invoice = await neutron.lightning.createInvoice({ amountSats: 10000 });
console.log(invoice.invoice); // "lnbc100u1p..."

That's it. Auth, token refresh, and retries are handled automatically.

Resources

The SDK is organized into resources, like Stripe's SDK:

neutron.account       // Account info, wallets, deposit addresses
neutron.transactions  // Create, confirm, list, track payments
neutron.lightning     // Lightning invoices, payments, utilities
neutron.webhooks      // Webhook management
neutron.rates         // Exchange rates
neutron.fiat          // Fiat payouts and bank lookups

Usage Examples

Receive Bitcoin via Lightning

const invoice = await neutron.lightning.createInvoice({
  amountSats: 50000,         // 50,000 sats
  memo: "Order #1234",       // shown to payer
  extRefId: "order-1234",    // your tracking ID
});

// Give this to your customer
console.log(invoice.invoice);    // BOLT11 string
console.log(invoice.qrPageUrl);  // hosted QR code page
console.log(invoice.txnId);      // track payment status

Send to a Lightning Address

const txn = await neutron.lightning.payAddress("[email protected]", {
  amountSats: 5000,
});
// Review the quote
console.log(txn.sourceReq.neutronpayFees); // fees in BTC

// Confirm to send
await neutron.transactions.confirm(txn.txnId);

Pay a Lightning Invoice

const txn = await neutron.lightning.payInvoice("lnbc100u1p...");
await neutron.transactions.confirm(txn.txnId);

Check Wallet Balances

const wallets = await neutron.account.wallets();
for (const w of wallets) {
  console.log(`${w.ccy}: ${w.availableBalance}`);
}

Convert BTC to USDT

const txn = await neutron.transactions.create({
  sourceReq: { ccy: "BTC", method: "neutronpay", amtRequested: 0.001, reqDetails: {} },
  destReq: { ccy: "USDT", method: "neutronpay", reqDetails: {} },
});
console.log(`Rate: ${txn.fxRate}`);
await neutron.transactions.confirm(txn.txnId);

Send Bitcoin On-Chain

const txn = await neutron.transactions.create({
  sourceReq: { ccy: "BTC", method: "neutronpay" },
  destReq: {
    ccy: "BTC",
    method: "on-chain",
    amtRequested: 0.005,
    reqDetails: { address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" },
  },
});
await neutron.transactions.confirm(txn.txnId);

Get Deposit Addresses

const btc = await neutron.account.btcAddress();
console.log(btc.address);  // "bc1q..." or "3M5A..."

const usdt = await neutron.account.usdtAddress("TRON");
console.log(usdt.address);  // "T..."

Fiat Payout (Bank Transfer)

// Look up bank codes first
const banks = await neutron.fiat.institutions("VN");

// Send VND to a bank account
const txn = await neutron.fiat.payout({
  sourceCcy: "BTC",
  sourceAmount: 0.001,
  destCcy: "VND",
  destMethod: "vnd-instant",
  bankAcctNum: "0123456789",
  institutionCode: "970422",
  recipientName: "LE VAN A",
  countryCode: "VN",
});
await neutron.transactions.confirm(txn.txnId);

Exchange Rates

const rates = await neutron.rates.get();
console.log(rates); // { BTCUSD: 97500, BTCVND: 2437500000, ... }

Webhooks

// Create
const webhook = await neutron.webhooks.create({
  callback: "https://myapp.com/webhooks/neutron",
  secret: "my-webhook-secret",
});

// List
const hooks = await neutron.webhooks.list();

// Update
await neutron.webhooks.update(webhook.id, { callback: "https://myapp.com/v2/webhooks" });

// Delete
await neutron.webhooks.delete(webhook.id);

Verify Webhook Signatures

One-liner verification — no client instance needed:

import { Neutron } from "neutron-sdk";

// Express example
app.post("/webhooks/neutron", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = Neutron.verifyWebhook(
      req.body,
      req.headers["x-neutronpay-signature"],
      "my-webhook-secret"
    );
    res.status(200).send("OK");

    // Event is verified — safe to use
    if (event.txnState === "completed") {
      fulfillOrder(event.extRefId);
    }
  } catch (err) {
    res.status(401).send("Invalid signature");
  }
});

Wait for Transaction Completion

const txn = await neutron.lightning.payInvoice("lnbc...");
await neutron.transactions.confirm(txn.txnId);

// Poll until done (with state change callbacks)
const result = await neutron.transactions.waitForCompletion(txn.txnId, {
  intervalMs: 2000,
  timeoutMs: 60000,
  onStateChange: (state) => console.log("State:", state),
});
console.log(result.txnState); // "completed"

Utility Helpers

import { satsToBtc, btcToSats, formatSats, formatBtc } from "neutron-sdk";

satsToBtc(10000);      // 0.0001
btcToSats(0.0001);     // 10000
formatSats(1500000);   // "1,500,000 sats"
formatBtc(0.00015);    // "0.00015000 BTC"

Constants

import { Currency, PaymentMethod, TransactionStates, Chain } from "neutron-sdk";

// Use in transaction creation for type safety
const txn = await neutron.transactions.create({
  sourceReq: { ccy: Currency.BTC, method: PaymentMethod.NEUTRON, amtRequested: 0.001, reqDetails: {} },
  destReq: { ccy: Currency.USDT, method: PaymentMethod.NEUTRON, reqDetails: {} },
});

// Check states
if (txn.txnState === TransactionStates.COMPLETED) { ... }

// USDT chains
const { address } = await neutron.account.usdtAddress(Chain.TRON);

Error Handling

import { NeutronApiError, NeutronAuthError, NeutronValidationError } from "neutron-sdk";

try {
  await neutron.lightning.createInvoice({ amountSats: 10000 });
} catch (err) {
  if (err instanceof NeutronApiError) {
    console.log(err.status);       // 400, 401, 429, etc.
    console.log(err.code);         // Neutron error code
    console.log(err.message);      // Human-readable message
    console.log(err.isRetryable);  // true for 5xx/429
    console.log(err.isRateLimited); // true for 429
  } else if (err instanceof NeutronAuthError) {
    console.log("Check your API credentials");
  } else if (err instanceof NeutronValidationError) {
    console.log("Invalid parameters:", err.message);
  }
}

Configuration

const neutron = new Neutron({
  apiKey: "your-api-key",       // Required
  apiSecret: "your-api-secret", // Required
  baseUrl: "https://api.neutron.me",  // Custom API URL (default: api.neutron.me)
  timeout: 15000,               // Request timeout in ms (default: 30000)
  maxRetries: 3,                // Retry attempts for 5xx/429 (default: 2)
  debug: true,                  // Log requests to stderr
});

Key Concepts

• Amounts are in BTC, not satoshis. 0.0001 BTC = 10,000 sats.
• Two-step flow: .create() returns a quote → .confirm() executes it.
• Set amount on one side only — sourceReq OR destReq, not both.
• createInvoice() auto-confirms — no second step needed for receiving.
• KYC only for fiat payouts. Bitcoin (Lightning + on-chain), stablecoins (USDT on TRON/ETH), and swaps require no KYC.
• Token management is automatic — the SDK authenticates on first request and refreshes as needed.

Supported Payment Methods

| Type | Methods | |------|---------| | Bitcoin Lightning | Bolt11 invoices, Lightning Addresses, LNURL | | Bitcoin On-Chain | Standard BTC transactions | | Stablecoins | USDT on TRON (TRC-20) and Ethereum (ERC-20) | | Fiat Payouts | Bank transfers (VND, USD, etc.) | | Internal | Wallet-to-wallet swaps (BTC ↔ USDT ↔ fiat) |

Links

• Documentation: docs.neutron.me
• API Reference: docs.neutron.me/reference
• MCP Server: neutron-mcp (for AI agents)
• Contact: [email protected]

License

MIT