Skip to Content
MagmaBuy Liquidity

Buy Liquidity

This guide explains how to purchase inbound Lightning liquidity using the Magma  API.

You will learn:

  • How much liquidity (in sats) you can expect for a given dollar amount
  • How to use the GraphQL buy mutation to purchase liquidity
  • How invoice creation & payment works

Overview

Buying liquidity on Magma is a simple 2-step flow:

Call the buy GraphQL mutation

Provide your node’s connection_uri, the amount in usd_cents (minimum $5), and any optional redirect URL or liquidity options.

Pay the BTCPay invoice

Pay the invoice returned by the mutation, either directly via the Lightning invoice or through the BTCPay checkout URL.

Open the buy mutation in the Apollo Explorer

The Magma API supports anonymous buyers. If you’re not logged in, it creates a session account and issues an authentication cookie on the fly. You can find your session key in the API response to use it later on. This allows you to authenticate future requests without creating new session accounts.

1. How much liquidity do you get for a certain USD amount?

You can use GraphQL, Node.js, or any other stack that supports either REST or GraphQL to get cost estimates from the Magma API.

The liquidity estimate comes from Magma’s internal market depth and pricing data. It’s an approximation and can vary with market conditions.

GraphQL Query

query.gql
query LiquidityPerUsd {
  market {
    liquidity {
      liquidity_per_usd {
        sats
        usd
      }
    }
  }
}

Example response

response.json
{
  "data": {
    "market": {
      "liquidity": {
        "liquidity_per_usd": {
          "sats": "543260",
          "usd": "501.0921588"
        }
      }
    }
  }
}

Values

  • sats indicates how many satoshis of liquidity you receive for each 1 USD paid.
  • usd indicates the expected dollar receiving capacity for each 1 USD paid.

With this response, paying 1 USD may enable you to receive roughly 500 USD in payments, equivalent to a 0.2% payment-processing cost!

Example

For the response above, the estimated liquidity for common USD amounts:

  • $5 → ~2,716,300 sats
  • $50 → ~27,163,000 sats
  • $100 → ~54,326,000 sats

You can also see the estimated liquidity sats your node is going to get on the Magma homepage .

image

2. How to Buy Liquidity

You can call the buy mutation from any HTTP/GraphQL client. Pick the example that matches your stack:

Authentication

Magma accepts Amboss API Keys. Create one at account.amboss.tech/settings/api-keys  and pass it in the Authorization header.

image

Authorization: Bearer [API_KEY]

Call the buy mutation

Open this mutation in the Apollo Explorer 

mutation.gql
mutation BuyLiquidity($input: LiquidityOrderInput!) {
  liquidity {
    buy(input: $input) {
      account {
        session_key
        id
      }
      order {
        transaction_id
        usd_cents
      }
      payment {
        redirect_url
        lightning_invoice
      }
    }
  }
}

Example variables:

variables.json
{
  "input": {
    "connection_uri": "024ae5265b5f4d1c789010f479d6b5a2e2c26948d301b00e170c1ed6f6c81c717a@bb4iz3w54euuhq2plh75jtrc4ogvafgz5vyjapwj2z24sl7f5b2nbgid.onion:9735",
    "usd_cents": "5000",
    "options": {
      "rails_cluster_only": true
    }
  }
}

Inputs you provide

ParameterRequiredTypeDescription
connection_uri✅ Requiredpubkey@host:portYour node’s connection string for liquidity delivery. Get this from lncli getinfo (LND) or lightning-cli getinfo (CLN).
usd_cents✅ RequiredintegerAmount to spend in USD cents (minimum 500 cents = $5.00).
redirect_url❌ OptionalstringURL to redirect after BTCPay payment completion. Defaults to the Magma transaction status page.
options❌ OptionalobjectAdditional channel configuration. Supports private (boolean) and rails_cluster_only (boolean).

What we return

FieldSub-fieldDescription
paymentredirect_urlBTCPay checkout URL for paying via the web interface.
lightning_invoiceLN invoice string for direct Lightning payment.
ordertransaction_idInternal transaction ID for tracking.
usd_centsThe amount to spend in USD cents.
accountsession_keySession key assigned for new session accounts (anonymous buyers).
idAccount ID (automatically created for session accounts).

Example response

response.json
{
  "data": {
    "liquidity": {
      "buy": {
        "payment": {
          "redirect_url": "https://btcpay0.voltageapp.io/i/LJfTHukUZLXCt1u7VpZDmB",
          "lightning_invoice": "lnbc655250n1p53epcypp5sj3ge9jckqt5pv5a34tcnnnhuhd46ts98t9fsm4zwr6052cg348qdr02pskjepqw3hjqstdvfhhxueq2d6x7un9yq5y7unyv4ezqj2y8gsx2ce4xcergdee94sngc3c956rge3595un2c3595cn2vrzxvcnqwpnxfjx22gcqzzsxqrrsssp5lyswnfuvp9vzuwu96xc8jkfdzakeg4ldlhkf5zydefwnadxlaz4q9qxpqysgq7ph586z60xltvysqftqqauukd4zde80njp9udynywaxgmgh0m2v8rzzzhjeq8uajscwsrlv90fk9hajer66neg2mspq5m52rd56wm7cpczgtpq"
        },
        "order": {
          "transaction_id": "ec562479-a4b8-44f4-95b4-150b310832de",
          "usd_cents": "6000"
        },
        "account": {
          "session_key": "b65b867c345468a0a2e07b3b86aa3078",
          "id": "54b9e82d-39d0-42b9-9229-f67786cdf145"
        }
      }
    }
  }
}

Minimum amount is $5. Requests lower than this are not allowed at the moment.

3. Payment Flow

Call the buy mutation

Send the node’s connection_uri and the desired dollar amount.

Receive the response

The API responds with a checkout URL (BTCPay payment page) and a Lightning invoice (direct-pay option).

Pay

Pay via the Lightning invoice or through the BTCPay checkout page.

Liquidity is delivered

After payment is confirmed, our internal intelligence layer begins sourcing the requested liquidity for your node.

MagmaSell Liquidity