How to Buy Liquidity Using Magma

This guide explains how to purchase inbound Lightning liquidity using our 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:

1. Call the buy GraphQL mutation with:

   • your node’s connection_uri
   • the amount in usd_cents (minimum $5)
   • optional redirect URL and liquidity options

2. Pay the BTCPay invoice returned by the mutation. You can pay directly via Lightning invoice or use the BTCPay checkout URL).

Click here  to open the buy mutation in the Apollo Explorer

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.

GraphQL Query

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

Example response

{
  "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.

Example

For example, for the above response, these are the estimated liquidity amounts you’ll get for the following 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 in the Magma homepage .

2. How to Buy Liquidity

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

How to Authenticate

You can access the Magma Liquidity API using Amboss API Keys.

Buy via GraphQL

Click here  to open the mutation in the Apollo Explorer

GraphQL Mutation

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

You provide:

For authenticated requests, use the API key in the Authorization header.

'Authorization': 'Bearer [API KEY]'

1. connection_uri (Required)

   • pubkey@host:port: Your node’s connection string for liquidity delivery. For example, if your node is using LND, you can get this from the lncli getinfo command, or using lightning-cli getinfo for Core Lightning nodes.

2. usd_cents (Required)

   • integer: Amount to spend in USD cents (minimum 500 cents = $5.00)

3. redirect_url (Optional)

   • string: The URL users are redirected to after completing their payment when using the BTCPay Checkout Page.
   • Default: Magma transaction status page if not provided

4. options (Optional)

   • object: Additional channel configuration
   • Currently supports:
     • private: boolean - creates private channel if true
     • rails_cluster_only: boolean - liquidity will be provided exlusively from Rails nodes if true

Example input

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

We return:

1. payment

   • redirect_url: BTCPay checkout URL
   • lightning_invoice: LN invoice string (you can pay this directly)

2. order

   • transaction_id: Transaction ID used internally
   • usd_cents: Amount to spend in USD cents

3. account

   • session_key: assigned for new session accounts
   • id: account ID (session accounts created automatically)

Example Output

{
  "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"
  }
}

Buy via NodeJS

A simple graphql-request client using an Amboss API Key 

import { GraphQLClient, gql } from "graphql-request";
 
const TOKEN = "API_KEY";
 
const client = new GraphQLClient("https://magma.amboss.tech/graphql", {
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
});
 
const BUY_MUTATION = gql`
  mutation BuyLiquidity($input: LiquidityOrderInput!) {
    buy(input: $input) {
      account {
        id
        session_key
      }
      payment {
        redirect_url
        lightning_invoice
      }
      order {
        transaction_id
        usd_cents
      }
    }
  }
`;
 
async function buyLiquidity({ connectionUri, usd }) {
  const variables = {
    input: {
      connection_uri: connectionUri,
      usd_cents: Math.round(usd * 100),
    },
  };
 
  const result = await client.request(BUY_MUTATION, variables);
  return result.buy;
}
 
const resp = await buyLiquidity({
  connectionUri:
    "024ae5265b5f4d1c789010f479d6b5a2e2c26948d301b00e170c1ed6f6c81c717a@bb4iz3w54euuhq2plh75jtrc4ogvafgz5vyjapwj2z24sl7f5b2nbgid.onion:9735",
  usd: 50,
});
 
console.log("BTCPay checkout URL:", resp.payment.redirect_url);
console.log("Lightning invoice:", resp.payment.lightning_invoice);
console.log("Session key:", resp.account.session_key);

3. Payment Flow

1. Client calls the buy mutation with the node’s connection_uri and the desired dollar amount.

2. The API responds with:

   • A checkout URL (BTCPay payment page)
   • A Lightning invoice (direct-pay option)

3. You pay

   • Either via the Lightning invoice
   • Or through the BTCPay checkout page

4. After payment is confirmed:

   • Our internal intelligence layer begins sourcing the requested liquidity for your node.