OpenNode Docs Portal

Welcome to the OpenNode Docs Portal. You'll find comprehensive guides and documentation to help you start working with OpenNode as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Receiving bitcoin payments

You need to create a 'charge' to receive payments through OpenNode. A charge contains both a Lightning Network BOLT11 invoice, capable of accepting payments through the LN protocol, and a on-chain address for standard on-chain transactions.


In order to receive notifications when a 'charge' changes its status, you need to subscribe to the 'charge' events. You can subscribe by passing a 'callback_url' parameter on the charge payload.


Lightning Network limit

The API does not return a lightning invoice when creating a charge with an amount bigger than 500000000 sats (5 BTC).


const opennode = require('opennode');
opennode.setCredentials('MY_API_KEY', 'dev');

const charge = {
  description: 'My test charge',
  amount: 10.5, // required
  currency: 'USD',
  order_id: '823320',
  customer_name: 'John Doe',
  customer_email: '[email protected]',
  notif_email: '[email protected]',
  callback_url: "",
  success_url: '',
  auto_settle: false

    .then(charge => {
    .catch(error => {
        console.error(`${error.status} | ${error.message}`);
curl \
    -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{ "description": "My test charge",
        "amount": 10.5,
      "currency": "USD",
      "order_id": "823320",
      "customer_name": "John Doe",
      "customer_email": "[email protected]",
      "notif_email": "[email protected]",
      "callback_url": "",
      "success_url": "",
      "auto_settle": false }'

If the request was correctly sent, the API will reply with a 201 status code and charge object:

    "data": {
        "id": "1543f881-5b86-46f0-b0ec-8f2d3a6b9498",
        "name": null,
        "description": "My test charge",
        "created_at": 1559566069,
        "status": "unpaid",
        "callback_url": "",
        "success_url": "",
        "order_id": "823320",
        "notes": "Order: 823320\nCustomer Email: N/A",
        "currency": "USD",
        "source_fiat_value": 10.5,
        "fiat_value": 10.5,
        "auto_settle": false,
        "notif_email": null,
        "lightning_invoice": {
            "expires_at": 1559569669,
        "chain_invoice": {
            "address": "2NAVFQaNg2y3QAoh6nZ5WrvWpxp7YQ7Yaed"
        "address": "2NAVFQaNg2y3QAoh6nZ5WrvWpxp7YQ7Yaed",
        "amount": 123025,

You can use OpenNode's native checkout experience by redirecting your user to the checkout endpoint:

Development - {id}
Production - {id}

If you want to build your own checkout experience you can create BIP21 + BOLT11 QR code using the uri field.

Updated 4 months ago

What's Next

Charges Webhooks

Receiving bitcoin payments

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.