# Neutron — AI Agent Knowledge Base

> Complete reference for AI agents integrating with Neutron's Bitcoin Lightning wallet API.
> Last updated: 2026-03-06 | Version: v2.2.6
> API: https://api.neutron.me | Portal: https://portal.neutron.me | Docs: https://docs.neutron.me

---

## Getting Started


Build global payment infrastructure with Bitcoin Lightning, stablecoins, and fiat -- all through a single, unified API.

## What is Neutron?

Neutron is a payment infrastructure API that lets you:

- **Accept and send Bitcoin** -- Lightning Network (instant) and on-chain
- **Move stablecoins** -- USDT on TRON and Ethereum
- **Pay out in fiat** -- Bank transfers and mobile money
- **Convert currencies** -- BTC, USDT, and fiat seamlessly
- **Stay compliant** -- Built-in KYC/KYB for regulated use cases

Whether you're building a wallet, payment gateway, remittance service, or treasury tool -- Neutron provides the rails.

## Why Neutron?

| Feature | Benefit |
|---------|---------|
| **Instant settlement** | Lightning payments settle in seconds, not days |
| **Global reach** | Send to 180+ countries via Lightning, USDT, or fiat rails |
| **Single integration** | One API for Bitcoin, stablecoins, and fiat |
| **Developer-first** | Clear docs, typed responses, MCP integration for AI agents |
| **Compliance-ready** | Optional KYC/KYB for regulated flows |

## Quick Example

Receive a Lightning payment in one API call:

```bash
curl -X POST https://api.neutron.me/api/v2/transaction/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceReq": {"ccy": "BTC", "method": "lightning", "reqDetails": {}},
    "destReq": {"ccy": "BTC", "method": "neutronpay", "amtRequested": 0.0001, "reqDetails": {}}
  }'
```

Returns a Lightning invoice your customer can pay instantly.

## Use Cases

### Accept Payments
E-commerce, SaaS, donations -- accept Bitcoin and USDT from anywhere in the world.

### Cross-Border Remittances
Send money globally via Lightning (instant, near-zero fees) or fiat rails (same-day).

### Treasury Management
Convert between BTC, USDT, and fiat. Manage multi-currency balances through a single dashboard.

### Payment Infrastructure
Build wallets, exchanges, or payment processors on Neutron's rails.

### AI Agent Payments
Give your AI agents the ability to send and receive Bitcoin via [Neutron MCP](/reference/mcp-overview).

## Getting Started

1. **[Quick Start](/docs/quick-start-guide)** -- Your first API call in 5 minutes
2. **[Authentication](/docs/authentication-guide)** -- API keys and signatures
3. **[API Reference](/reference/overview)** -- Full endpoint documentation

## Support

- **Docs:** [docs.neutron.me](https://docs.neutron.me)
- **Email:** [support@neutron.me](mailto:support@neutron.me)
- **Contact:** [neutron.me/contact](https://neutron.me/contact)

## AI Agent Resources

Building with an AI agent? Neutron is fully accessible programmatically via MCP, SDK, and CLI.

| Resource | URL | Description |
|---|---|---|
| **llms.md** | [llms.neutron.me](https://llms.neutron.me) | Complete knowledge base for AI agents — one file, everything you need |
| **MCP Server** | `npx neutron-mcp` | Model Context Protocol server for Claude, Cursor, Windsurf, VS Code |
| **CLI** | `npm install -g neutron-cli` | Command-line tool with `--json` mode for agent workflows |
| **SDK** | `npm install neutron-sdk` | Node.js SDK |

> **For AI agents:** Fetch [https://llms.neutron.me](https://llms.neutron.me) to get the complete Neutron reference in a single markdown file — no JS rendering, no pagination, instant context.


Get your first Neutron integration working in under 5 minutes. Choose the path that fits your stack.

## Prerequisites

- Neutron account with API credentials ([Sign up](https://portal.neutron.me))
- Your **API Key** and **API Secret** from the dashboard

---

## Path 1 — MCP (AI Agents & Claude) ⚡ Fastest

Add Bitcoin Lightning payments to any MCP-compatible AI tool in 2 minutes.

```json
{
  "mcpServers": {
    "neutron": {
      "command": "npx",
      "args": ["-y", "neutron-mcp"],
      "env": {
        "NEUTRON_API_KEY": "your_api_key",
        "NEUTRON_API_SECRET": "your_api_secret"
      }
    }
  }
}
```

Paste into your tool's MCP config, restart, then ask:

> "Check my Neutron wallet balances"

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

| Tool | Config Location |
|------|----------------|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Code | `~/.claude.json` or `.mcp.json` in your project |
| Cursor | `.cursor/mcp.json` |
| Windsurf | Windsurf MCP settings |

---

## Path 2 — SDK (Node.js / TypeScript)

```bash
npm install neutron-sdk
```

```typescript
import { Neutron } from "neutron-sdk";

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

// Check balances
const wallets = await neutron.account.wallets();

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

Auth is handled automatically — no HMAC code needed.

---

## Path 3 — CLI (Terminal / Shell Scripts)

```bash
npm install -g neutron-cli
neutron-cli auth        # one-time setup
neutron-cli balance     # check wallets
neutron-cli send        # send payments
```

Use `--json` for scripting and AI agent environments:

```bash
neutron-cli balance --json
```

---

## Path 4 — REST API (Direct)

Authentication uses HMAC-SHA256 signature exchange. Full details in the [Authentication Guide](/docs/authentication-guide).

**Step 1: Get an access token**

```bash
API_KEY="your_api_key"
API_SECRET="your_api_secret"
PAYLOAD='{"test":"auth"}'
STRING_TO_SIGN="${API_KEY}&payload=${PAYLOAD}"
SIGNATURE=$(echo -n "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$API_SECRET" | cut -d' ' -f2)

curl -X POST https://api.neutron.me/api/v2/authentication/token-signature \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Signature: $SIGNATURE" \
  -d "$PAYLOAD"
```

Response includes `accessToken` and `accountId` — save both.

**Step 2: Make API calls**

```bash
curl https://api.neutron.me/api/v2/account/YOUR_ACCOUNT_ID/wallet/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Step 3: Create a Lightning invoice**

```bash
curl -X POST https://api.neutron.me/api/v2/transaction/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "sourceReq": {"ccy": "BTC", "method": "lightning", "reqDetails": {}},
    "destReq": {"ccy": "BTC", "method": "neutronpay", "amtRequested": 0.0001, "reqDetails": {}}
  }'
```

**Step 4: Confirm the transaction**

```bash
curl -X PUT https://api.neutron.me/api/v2/transaction/TXN_ID/confirm \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

> **Key concepts:** Amounts are in BTC (`0.0001` = 10,000 sats). Transactions are two-step: Create → Confirm. Set amount on source OR destination, not both.

---

## Next Steps

- [Authentication Guide](/docs/authentication-guide) — HMAC signature in Node.js, Python, Go, Java, C#
- [Receive Lightning Payments](/docs/receive-lightning-guide)
- [Send Lightning Payments](/docs/send-lightning-guide)
- [Webhooks](/docs/webhooks-guide) — Real-time payment notifications


All Neutron API requests require authentication. This guide covers how to generate signatures, get access tokens, and use them securely.

## How It Works

1. **Generate a signature** using your API Key and Secret (HMAC-SHA256)
2. **Exchange for an access token** via the authentication endpoint
3. **Use the token** as a Bearer token in all API calls

## Signature Formula

```
stringToSign = "{apiKey}&payload={jsonPayload}"
signature    = HMAC-SHA256(apiSecret, stringToSign) -> hex
```

The payload can be any valid JSON (e.g., `{"test":"auth"}`). The same JSON is sent as the request body.

## Code Examples

### Node.js

```javascript
const crypto = require('crypto');

function authenticate(apiKey, apiSecret) {
  const payload = JSON.stringify({ test: 'auth' });
  const stringToSign = `${apiKey}&payload=${payload}`;
  const signature = crypto
    .createHmac('sha256', apiSecret)
    .update(stringToSign)
    .digest('hex');

  return fetch('https://api.neutron.me/api/v2/authentication/token-signature', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': apiKey,
      'X-Api-Signature': signature,
    },
    body: payload,
  }).then(res => res.json());
}

const { accessToken, accountId } = await authenticate('your-api-key', 'your-api-secret');
```

### Python

```python
import hmac
import hashlib
import json
import requests

def authenticate(api_key, api_secret):
    payload = json.dumps({"test": "auth"})
    string_to_sign = f"{api_key}&payload={payload}"
    signature = hmac.new(
        api_secret.encode(),
        string_to_sign.encode(),
        hashlib.sha256
    ).hexdigest()

    response = requests.post(
        'https://api.neutron.me/api/v2/authentication/token-signature',
        headers={
            'Content-Type': 'application/json',
            'X-Api-Key': api_key,
            'X-Api-Signature': signature,
        },
        data=payload,
    )
    return response.json()

result = authenticate('your-api-key', 'your-api-secret')
access_token = result['accessToken']
```

### Go

```go
func authenticate(apiKey, apiSecret string) (string, error) {
    payload := `{"test":"auth"}`
    stringToSign := apiKey + "&payload=" + payload
    h := hmac.New(sha256.New, []byte(apiSecret))
    h.Write([]byte(stringToSign))
    signature := hex.EncodeToString(h.Sum(nil))

    req, _ := http.NewRequest("POST",
        "https://api.neutron.me/api/v2/authentication/token-signature",
        strings.NewReader(payload))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-Api-Key", apiKey)
    req.Header.Set("X-Api-Signature", signature)

    resp, err := http.DefaultClient.Do(req)
    // ... parse response for accessToken
}
```

### PHP

```php
function authenticate($apiKey, $apiSecret) {
    $payload = json_encode(['test' => 'auth']);
    $stringToSign = "{$apiKey}&payload={$payload}";
    $signature = hash_hmac('sha256', $stringToSign, $apiSecret);

    $ch = curl_init('https://api.neutron.me/api/v2/authentication/token-signature');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        "X-Api-Key: {$apiKey}",
        "X-Api-Signature: {$signature}",
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    return json_decode(curl_exec($ch), true);
}
```

### cURL / Bash

```bash
API_KEY="your-api-key"
API_SECRET="your-api-secret"
PAYLOAD='{"test":"auth"}'
STRING_TO_SIGN="${API_KEY}&payload=${PAYLOAD}"
SIGNATURE=$(echo -n "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$API_SECRET" | cut -d' ' -f2)

curl -X POST https://api.neutron.me/api/v2/authentication/token-signature \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Signature: $SIGNATURE" \
  -d "$PAYLOAD"
```

## Response

```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiredAt": 1770428400000,
  "accountId": "ne01-abc123def456"
}
```

## Using the Token

Include the token in the `Authorization` header for all API calls:

```bash
curl https://api.neutron.me/api/v2/account/YOUR_ACCOUNT_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Token Management

- Tokens have a **limited validity period** -- check `expiredAt`
- Using an expired token returns **401 Unauthorized**
- No refresh token flow -- simply re-authenticate when expired

### Auto-Refresh Pattern

```javascript
class NeutronClient {
  constructor(apiKey, apiSecret) {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.token = null;
    this.tokenExpiry = null;
  }

  async getToken() {
    if (!this.token || Date.now() > this.tokenExpiry - 300000) {
      const result = await authenticate(this.apiKey, this.apiSecret);
      this.token = result.accessToken;
      this.tokenExpiry = result.expiredAt;
    }
    return this.token;
  }
}
```

## Security Best Practices

**Do:** Store secrets in env vars or secret managers. Rotate keys periodically. Restrict key permissions to what's needed.

**Don't:** Expose secrets in client-side code. Commit secrets to git. Share secrets over chat.


Security is foundational to Neutron. This guide covers best practices for keeping your integration secure.

## Core Principles

1. **Authenticated access** -- All endpoints require HMAC-SHA256 signature authentication
2. **Minimal data exposure** -- We don't store what we don't need
3. **Auditability** -- Every action is logged and traceable
4. **HTTPS only** -- All API endpoints enforce TLS encryption

## Protect Your Secrets

| Do | Don't |
|----|-------|
| Store secrets in environment variables | Hardcode secrets in source code |
| Use secret managers (AWS Secrets, Vault) | Commit secrets to git |
| Rotate API keys periodically | Share secrets over chat or email |
| Restrict key permissions to what's needed | Use the same key everywhere |

## Verify Webhook Signatures

Always verify the `X-Neutronpay-Signature` header before processing webhook events:

```javascript
const crypto = require('crypto');

function verifyWebhook(requestBody, signatureHeader, webhookSecret) {
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(requestBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}
```

Never process unverified webhooks -- an attacker could send fake payment confirmations.

## Handle Tokens Properly

Access tokens expire. Implement automatic refresh:

```javascript
class NeutronClient {
  async getToken() {
    if (!this.token || Date.now() > this.tokenExpiry - 300000) {
      await this.refreshToken();
    }
    return this.token;
  }
}
```

## Rate Limits

| Tier | Requests/min | Requests/day |
|------|-------------|--------------|
| Standard | 60 | 10,000 |
| Business | 300 | 50,000 |
| Enterprise | Custom | Custom |

Implement exponential backoff when rate limited (HTTP 429):

```javascript
async function requestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
      } else throw err;
    }
  }
}
```

## Data Handling

**What Neutron stores:** Transaction records, wallet addresses and balances, API access logs.

**What Neutron does NOT store:** Full KYC documents (processed, not retained), your API secret (only the key), customer PII beyond compliance requirements.

## Production Security Checklist

- API secrets in environment variables or secret manager
- Webhook signatures verified on every callback
- Token refresh logic implemented
- Rate limit handling with exponential backoff
- Error logging without exposing secrets
- HTTPS enforced everywhere
- API key rotation scheduled periodically

## Report a Vulnerability

Found a security issue? Email [security@neutron.me](mailto:security@neutron.me) with a description, steps to reproduce, and potential impact. We respond within 48 hours.


---

## Core Concepts


---

## Integration Guides


Webhooks are the recommended way to track transaction status in Neutron. This guide explains why webhooks outperform polling, how to set them up, and how to handle edge cases.

## Prerequisites

Before using any Neutron integration (API, SDK, or MCP), you need an API key. **You get this from the dashboard at [portal.neutron.me](https://portal.neutron.me).**

1. Sign up at [portal.neutron.me](https://portal.neutron.me)
2. Access your dashboard
3. Generate your API key and secret

Everything can be configured, but the API key is the final piece — without it, wallet services won't function.

> **Note:** Keep your API secret secure. Never commit it to version control or expose it in client-side code.

## Why Webhooks Over Polling?

| | Webhooks | Polling |
|---|---|---|
| **Latency** | Sub-second | 1–30s depending on interval |
| **Rate limits** | Not affected | Consumes your quota |
| **Reliability** | Push delivery with retries | You manage retry logic |
| **Complexity** | One-time setup | Ongoing loop to maintain |

Polling the `/api/v2/transaction/{txnId}` endpoint works, but burns through your rate limit allowance quickly — especially for high-volume integrations. A busy integration polling every 2 seconds for 10 concurrent transactions makes 300 requests per minute. Webhooks deliver the same information in a single push.

### Rate Limit Reference

| Endpoint | Limit |
|----------|-------|
| `GET /api/v2/transaction/:id` | 60 req/min per API key |
| `GET /api/v2/transaction` | 30 req/min per API key |
| `POST /api/v2/webhook` | 10 req/min per API key |

Once you hit the limit, you'll receive `429 Too Many Requests` responses until the window resets.

---

## Setting Up Webhooks

### Via the API

```bash
curl -X POST https://api.neutron.me/api/v2/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "callback": "https://yourapp.com/webhooks/neutron",
    "secret": "your-webhook-secret"
  }'
```

Store the webhook `secret` securely — you'll use it to verify incoming payloads.

### Via the SDK

```javascript
const { Neutron } = require('neutron-sdk');

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

const webhook = await neutron.webhooks.create({
  callback: 'https://yourapp.com/webhooks/neutron',
  secret: process.env.WEBHOOK_SECRET,
});

console.log('Webhook created:', webhook.webhookId);
```

### Via the MCP Tool (AI Agents)

```
Use the neutron_create_webhook tool:
  callback: "https://yourapp.com/webhooks/neutron"
  secret: "your-webhook-secret"
```

---

## Webhook Payload

When a transaction status changes, Neutron POSTs to your callback URL:

```json
{
  "txnId": "41866d80-a46a-4845-a205-5cffc881cad3",
  "extRefId": "order-abc1234",
  "txnState": "completed",
  "msg": "",
  "updatedAt": 1676030467492
}
```

**Transaction states:**
- `quoted` — Created, awaiting confirmation
- `processing` — Confirmed, payment in flight
- `completed` — Payment successful
- `failed` — Payment failed
- `expired` — Invoice or transaction timed out

---

## Verifying Webhook Signatures

**Always verify the signature.** Without verification, anyone can POST fake events to your endpoint.

Neutron signs every webhook payload with HMAC-SHA256 using your webhook secret. The signature is sent in the `X-Neutronpay-Signature` header.

### Node.js

```javascript
const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/webhooks/neutron', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-neutronpay-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  // Compute expected signature
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body) // raw body bytes, not parsed JSON
    .digest('hex');

  // Timing-safe comparison
  const valid = crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );

  if (!valid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  console.log('Verified event:', event.txnId, event.txnState);

  // Handle the event
  if (event.txnState === 'completed') {
    // Fulfill order, release funds, etc.
  }

  res.status(200).json({ received: true });
});
```

### Python

```python
import hmac
import hashlib
import json
from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/webhooks/neutron', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Neutronpay-Signature', '')
    secret = os.environ['WEBHOOK_SECRET'].encode()

    expected = hmac.new(secret, request.data, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401)

    event = request.json
    print(f"Event: {event['txnId']} → {event['txnState']}")

    return {'received': True}, 200
```

### Via the SDK

```javascript
const { Neutron } = require('neutron-sdk');

// In your webhook handler:
app.post('/webhooks/neutron', express.raw({ type: 'application/json' }), (req, res) => {
  const isValid = Neutron.webhooks.verify(
    req.body,                                    // raw body
    req.headers['x-neutronpay-signature'],          // signature header
    process.env.WEBHOOK_SECRET                   // your secret
  );

  if (!isValid) return res.status(401).end();

  const event = JSON.parse(req.body);
  // handle event...
  res.status(200).json({ received: true });
});
```

---

## Responding to Webhooks

Your endpoint must:
1. **Return `200 OK`** within 10 seconds
2. **Process asynchronously** — queue the event and return immediately if processing takes time
3. **Be idempotent** — you may receive the same event more than once

```javascript
app.post('/webhooks/neutron', async (req, res) => {
  // Respond immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  const event = JSON.parse(req.body);
  await queue.push(event); // handle in background
});
```

If your endpoint returns a non-200 status or times out, Neutron will retry delivery with exponential backoff.

---

## Fallback: SSE for Ephemeral Agents

Some AI agents and serverless functions don't have a public URL to receive webhook POSTs. For these cases, use **Server-Sent Events (SSE)** to stream status updates directly.

### Via the MCP Tool

```
Use neutron_subscribe_status:
  transactionId: "txn-abc123"
  timeoutSeconds: 60
```

The tool connects to the Neutron SSE stream and returns when the transaction reaches a terminal state (completed, failed, expired).

### Via the SDK

```javascript
// Stream status updates until terminal state
for await (const event of neutron.transactions.subscribe('txn-abc123')) {
  console.log('Status update:', event.status);

  if (['completed', 'failed', 'expired'].includes(event.status)) {
    break;
  }
}
```

### When to Use SSE vs Webhooks

| Scenario | Recommended |
|----------|-------------|
| Long-running server | Webhooks |
| Serverless / Lambda | Webhooks (with public URL) |
| Ephemeral AI agent | SSE |
| Local development / testing | SSE |
| High volume (>100 tx/min) | Webhooks |

---

## Checklist

- [ ] API key obtained from [portal.neutron.me](https://portal.neutron.me)
- [ ] Webhook endpoint returns `200` within 10 seconds
- [ ] Signature verification implemented with `timingSafeEqual`
- [ ] Raw request body used for signature (not re-serialized JSON)
- [ ] Idempotency handled (same event may arrive twice)
- [ ] Webhook secret stored in env var, not hardcoded
- [ ] Fallback to SSE for agents without public endpoints


---

## Lightning Concepts


---

## Neutron MCP Reference


**Neutron MCP** is a [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents and coding assistants direct access to the Neutron API. Build Bitcoin Lightning payment flows with natural language — no REST calls needed.

## What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI models call external tools. Instead of writing API integration code, you describe what you want and the AI handles it:

```
You: "Create a Lightning invoice for 1000 sats"

AI: [calls neutron_create_lightning_invoice with amount 0.00001]
    → Here's your invoice: lnbc100n1p...
    → QR code: https://pay.neutron.me/...
```

## Who is it for?

| Audience | Use case |
|----------|----------|
| **Vibe coders** | Build payment features by describing what you want in Cursor, Windsurf, or Claude |
| **AI agents** | Autonomous agents that can send/receive Bitcoin, check balances, manage webhooks |
| **Prototypers** | Test Neutron API flows interactively without writing integration code |
| **Developers** | Explore the API in Claude Desktop before writing production code |

## Supported Clients

Neutron MCP works with any MCP-compatible client:

- **Claude Desktop** — Anthropic's desktop app
- **Claude Code** — CLI coding agent
- **Cursor** — AI-powered code editor
- **Windsurf** — AI-powered code editor
- **VS Code + Copilot** — via MCP extension
- **OpenClaw** — AI agent framework
- Any client implementing the [MCP specification](https://modelcontextprotocol.io)

## What Can It Do?

| Category | Tools | Description |
|----------|-------|-------------|
| **Account** | `authenticate`, `get_account`, `get_wallets`, `get_wallet` | Check credentials, view balances |
| **Transactions** | `create_transaction`, `confirm_transaction`, `get_transaction`, `list_transactions` | Full transaction lifecycle |
| **Lightning** | `create_lightning_invoice` | Generate invoices with QR codes |
| **Webhooks** | `create_webhook`, `list_webhooks`, `update_webhook`, `delete_webhook` | Manage event notifications |
| **Rates** | `get_rate` | Current exchange rates (28+ currencies) |

14 tools covering the complete Neutron API surface.

## Quick Example

Once configured, you can do things like:

- *"Check my BTC balance"*
- *"Send 500 sats to user@getalby.com via Lightning"*
- *"Create an invoice for $5 worth of Bitcoin"*
- *"What's the current BTC/USD rate?"*
- *"Set up a webhook to https://myapp.com/payments"*
- *"Show my last 10 transactions"*

The AI translates these into the right API calls automatically.

## Next Steps

- [Quick Start](/reference/mcp-quickstart) — Install and configure in 2 minutes
- [Tools Reference](/reference/mcp-tools) — Complete tool documentation
- [npm package](https://www.npmjs.com/package/neutron-mcp) — `npx neutron-mcp`
- [GitHub](https://github.com/nicholasoxford/neutron-mcp) — Source code


Get Neutron MCP running with your AI client in under 2 minutes.

## Prerequisites

- **Node.js 18+** installed
- **Neutron API credentials** — get them from your [Neutron portal](https://portal.neutron.me)
  - API Key
  - API Secret

## Install

No install needed — use `npx` to run directly:

```bash
npx neutron-mcp
```

Or install globally:

```bash
npm install -g neutron-mcp
```

## Configure Your AI Client

### Claude Desktop

Add to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "neutron": {
      "command": "npx",
      "args": ["neutron-mcp"],
      "env": {
        "NEUTRON_API_KEY": "your-api-key",
        "NEUTRON_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "neutron": {
      "command": "npx",
      "args": ["neutron-mcp"],
      "env": {
        "NEUTRON_API_KEY": "your-api-key",
        "NEUTRON_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

### VS Code (Copilot)

Add to your VS Code settings or `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "neutron": {
      "command": "npx",
      "args": ["neutron-mcp"],
      "env": {
        "NEUTRON_API_KEY": "your-api-key",
        "NEUTRON_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "neutron": {
      "command": "npx",
      "args": ["neutron-mcp"],
      "env": {
        "NEUTRON_API_KEY": "your-api-key",
        "NEUTRON_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

### Claude Code (CLI)

```bash
claude mcp add neutron -- npx neutron-mcp \
  -e NEUTRON_API_KEY=your-api-key \
  -e NEUTRON_API_SECRET=your-api-secret \
```

### OpenClaw

Add to your OpenClaw config:

```json
{
  "mcp": {
    "servers": {
      "neutron": {
        "command": "npx",
        "args": ["neutron-mcp"],
        "env": {
          "NEUTRON_API_KEY": "your-api-key",
          "NEUTRON_API_SECRET": "your-api-secret",
        }
      }
    }
  }
}
```

## Verify It Works

Once configured, ask your AI client:

> "Authenticate with Neutron and show my account info"

You should see your account details including display name, status, and country.

Then try:

> "Show my wallet balances"

If you see your BTC/USDT balances, you're all set! 🎉

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `NEUTRON_API_KEY` | ✅ | Your Neutron API key |
| `NEUTRON_API_SECRET` | ✅ | Your Neutron API secret |

> **Note:** You do not need to configure an account ID. Your account ID (starting with `ne01-`) is returned automatically when the MCP server authenticates.

> **Note:** Authentication is automatic — the MCP server authenticates on first tool call and refreshes tokens as needed. You only need to call `neutron_authenticate` if you want to explicitly verify your credentials.

## Troubleshooting

### "Tool not found" or no tools showing

- Make sure Node.js 18+ is installed: `node --version`
- Check that `npx neutron-mcp` runs without errors in your terminal
- Restart your AI client after config changes

### Authentication errors

- Verify your API key and secret are correct
- Your account ID (starting with `ne01-`) is returned automatically when the MCP server authenticates — you don't need to configure it
- Ensure there are no extra spaces in the env values

### Connection issues

- The MCP server connects to `api.neutron.me` — ensure your network allows HTTPS outbound
- If behind a proxy, set `HTTPS_PROXY` in the env block

## Next Steps

- [Tools Reference](/reference/mcp-tools) — Detailed docs for all 18 tools
- [Neutron MCP Overview](/reference/mcp-overview) — What MCP is and how it works


Complete reference for all 14 tools available in the Neutron MCP server. Each tool maps to one or more Neutron API endpoints.

## Account Tools

### neutron_authenticate

Verify your API credentials and get an access token.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| *(none)* | — | — | Uses credentials from environment variables |

**Returns:** Account ID, access token, token expiry.

**Example prompt:** *"Authenticate with Neutron"*

---

### neutron_get_account

Get account details including display name, status, country, and timezone.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| *(none)* | — | — | Uses authenticated account |

**Example prompt:** *"Show my Neutron account info"*

---

### neutron_get_wallets

List all wallets with current balances.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| *(none)* | — | — | Returns all wallets for the account |

**Example prompt:** *"What are my wallet balances?"*

---

### neutron_get_wallet

Get details of a specific wallet.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `walletId` | string | ✅ | Wallet ID to look up |

**Example prompt:** *"Show details for wallet wal_abc123"*

---

## Transaction Tools

### neutron_create_transaction

Create a new transaction. Supports Lightning, Bitcoin on-chain, USDT, and fiat payouts. This is the most versatile tool — it maps to the unified [Create Transaction](/reference/createtransaction) endpoint.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sourceCurrency` | string | ✅ | Source currency (`BTC`, `USDT`, `VND`, etc.) |
| `sourceMethod` | string | ✅ | Source method (`neutronpay`, `lightning`, `on-chain`) |
| `sourceAmount` | number | ❌ | Amount on source side (set source OR dest, not both) |
| `destCurrency` | string | ✅ | Destination currency |
| `destMethod` | string | ✅ | Dest method (`neutronpay`, `lightning`, `on-chain`, `tron`, `vnd-instant`) |
| `destAmount` | number | ❌ | Amount on destination side |
| `destAddress` | string | ❌ | Bitcoin/TRON address (for on-chain/tron sends) |
| `destPaymentRequest` | string | ❌ | Bolt11 invoice (for Lightning sends) |
| `destBankAcctNum` | string | ❌ | Bank account number (for fiat payouts) |
| `destInstitutionCode` | string | ❌ | Bank institution code (for fiat payouts) |
| `destRecipientName` | string | ❌ | Recipient legal name (for fiat payouts) |
| `destCountryCode` | string | ❌ | Recipient country code (for fiat payouts) |
| `extRefId` | string | ❌ | Your external reference ID |

**Example prompts:**
- *"Send 500 sats to user@getalby.com via Lightning"*
- *"Create a transaction to send 0.001 BTC to bc1q..."*
- *"Convert 100 USDT to BTC in my wallet"*

---

### neutron_confirm_transaction

Confirm a quoted transaction to execute it.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `transactionId` | string | ✅ | Transaction ID to confirm |

**Example prompt:** *"Confirm transaction d5a2c7b4-3456-..."*

---

### neutron_get_transaction

Get status and details of a specific transaction.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `transactionId` | string | ✅ | Transaction ID to look up |

**Example prompt:** *"What's the status of my last transaction?"*

**Transaction states (`txnState`):**

| State | Meaning | Action |
|-------|---------|--------|
| `quoted` | Created, awaiting confirmation | Call `neutron_confirm_transaction` |
| `processing` | Confirmed, payment in flight | Wait |
| `completed` | Payment delivered ✅ | Done |
| `failed` | Payment failed | Retry or investigate |
| `expired` | Invoice/transaction timed out | Create a new one |

---

### neutron_list_transactions

List transactions with optional filters.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | ❌ | Filter by status (`completed`, `quoted`, `failed`, etc.) |
| `method` | string | ❌ | Filter by method (`lightning`, `on-chain`, etc.) |
| `currency` | string | ❌ | Filter by currency |
| `startDate` | string | ❌ | Start of date range (ISO 8601) |
| `endDate` | string | ❌ | End of date range (ISO 8601) |

**Example prompts:**
- *"Show my last 10 transactions"*
- *"List all completed Lightning transactions this week"*

---

## Lightning Tools

### neutron_create_lightning_invoice

Create a Lightning invoice (BOLT11) to receive Bitcoin. Returns the payment request string and a hosted QR code page URL.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `amountSats` | number | ⚡ | Amount in satoshis (use this OR `amountBtc`) |
| `amountBtc` | number | ⚡ | Amount in BTC (use this OR `amountSats`) |
| `memo` | string | ❌ | Description for the invoice |
| `expiry` | number | ❌ | Expiry time in seconds (default: 3600) |
| `extRefId` | string | ❌ | Your external reference ID |

> ⚡ = At least one of these fields is required (provide either `amountSats` OR `amountBtc`, not both).

> 💡 This is a convenience tool — it wraps `create_transaction` + `confirm_transaction` into a single call for the common "receive Lightning payment" flow.

**Example prompts:**
- *"Create a Lightning invoice for 10,000 sats"*
- *"Generate an invoice for $5 worth of Bitcoin with memo 'Coffee payment'"*

---

## Webhook Tools

### neutron_create_webhook

Register a webhook to receive event notifications.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | ✅ | Callback URL (must be HTTPS) |
| `secret` | string | ✅ | Secret for signature verification |

**Example prompt:** *"Set up a webhook to https://myapp.com/webhooks with secret 'mysecret123'"*

---

### neutron_list_webhooks

List all registered webhooks.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| *(none)* | — | — | Returns all webhooks for the account |

---

### neutron_update_webhook

Update a webhook's URL or secret.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `webhookId` | string | ✅ | Webhook ID to update |
| `url` | string | ❌ | New callback URL |
| `secret` | string | ❌ | New secret |

---

### neutron_delete_webhook

Remove a registered webhook.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `webhookId` | string | ✅ | Webhook ID to delete |

---

## Exchange Rate Tools

### neutron_get_rate

Get current exchange rates for BTC against 28+ currencies.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| *(none)* | — | — | Returns all available rates |

**Returns:** BTC exchange rates for USD, EUR, VND, CAD, GBP, JPY, and more.

**Example prompts:**
- *"What's the current BTC/USD rate?"*
- *"How much is 0.01 BTC in VND?"*

---

## Tool → API Mapping

| MCP Tool | API Endpoint | Docs |
|----------|-------------|------|
| `authenticate` | POST `/api/v2/authentication/token-signature` | [Auth](/reference/authentication) |
| `get_account` | GET `/api/v2/account/{id}` | [Account](/reference/getaccount) |
| `get_wallets` | GET `/api/v2/account/{id}/wallet/` | [Wallets](/reference/getwallets) |
| `get_wallet` | GET `/api/v2/account/{id}/wallet/{walletId}` | [Wallet](/reference/getwallet) |
| `create_transaction` | POST `/api/v2/transaction/` | [Create](/reference/createtransaction) |
| `confirm_transaction` | PUT `/api/v2/transaction/{id}/confirm` | [Confirm](/reference/confirmtransaction) |
| `get_transaction` | GET `/api/v2/transaction/{id}` | [Get](/reference/gettransactionstatus) |
| `list_transactions` | GET `/api/v2/transaction` | [List](/reference/listtransactions) |
| `create_lightning_invoice` | POST + PUT `/api/v2/transaction/` | [Lightning](/reference/receive-bitcoin-with-lightning-invoice) |
| `create_webhook` | POST `/api/v2/webhook` | [Create](/reference/createwebhook) |
| `list_webhooks` | GET `/api/v2/webhook` | [List](/reference/listwebhooks) |
| `update_webhook` | PUT `/api/v2/webhook/{id}` | [Update](/reference/updatewebhook) |
| `delete_webhook` | DELETE `/api/v2/webhook/{id}` | [Remove](/reference/removewebhook) |
| `get_rate` | GET `/api/v2/rate` | [Rates](/reference/getexchangerates) |

## Related

- [Quick Start](/reference/mcp-quickstart) — Install and configure
- [Neutron MCP Overview](/reference/mcp-overview) — What MCP is and how it works
- [npm: neutron-mcp](https://www.npmjs.com/package/neutron-mcp) — Package page