Liquidity Subscriptions

Recurring monthly inbound Lightning liquidity via the Magma API. Create, manage, and cancel subscriptions programmatically.

A Liquidity Subscription is a recurring monthly purchase of inbound capacity for one of your nodes. Magma decides when and from whom to source liquidity based on your node's payment activity - your code never has to call liquidity.buy again.

This page covers the API surface: creating, listing, and cancelling subscriptions.

How a subscription works

Monthly amount is anywhere from $5 to $1,000 (500–100,000 cents).
Magma sources channels throughout the month - there isn't one big channel on day 1 and silence afterward.
Subscriptions are non-custodial. Each channel still opens via a HODL invoice between you and the seller.

1. Create a subscription

liquidity.create_subscription is a public mutation - no API key required. The response includes an external_url pointing at a Stripe checkout for the first payment.

mutation CreateSubscription($input: LiquiditySubscriptionInput!) {
  liquidity {
    create_subscription(input: $input) {
      account { account_id session_key }
      external_url
    }
  }
}

{
  "input": {
    "monthly_cents": 2500,
    "connection_uri": "[email protected]:9735",
    "payment_reliability_report": false
  }
}

curl -X POST https://magma.amboss.tech/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation($input: LiquiditySubscriptionInput!) { liquidity { create_subscription(input: $input) { account { account_id session_key } external_url } } }",
    "variables": {
      "input": {
        "monthly_cents": 2500,
        "connection_uri": "[email protected]:9735",
        "payment_reliability_report": false
      }
    }
  }'

import { GraphQLClient, gql } from "graphql-request";

const magma = new GraphQLClient("https://magma.amboss.tech/graphql");

const { liquidity } = await magma.request(
  gql`
    mutation CreateSubscription($input: LiquiditySubscriptionInput!) {
      liquidity {
        create_subscription(input: $input) {
          account { account_id session_key }
          external_url
        }
      }
    }
  `,
  {
    input: {
      monthly_cents: 2500,
      connection_uri: "[email protected]:9735",
      payment_reliability_report: false,
    },
  },
);

// Redirect the user (or open a browser server-side) to complete checkout
console.log(liquidity.create_subscription.external_url);

Inputs

Field	Required	Type	Description
`monthly_cents`	✅	`Float`	Monthly spend in USD cents. 500–100000 ($5–$1,000).
`connection_uri`	❌	`String`	Target node, in `pubkey@host:port` format. Omit to manage the connection later through the dashboard.
`payment_reliability_report`	✅	`Boolean`	Add the monthly Payment Reliability Report add-on. Adds $15 to the first invoice.
`referral_code`	❌	`String`	Optional referral.

Response

{
  "data": {
    "liquidity": {
      "create_subscription": {
        "account": {
          "account_id": "54b9e82d-39d0-42b9-9229-f67786cdf145",
          "session_key": "b65b867c345468a0a2e07b3b86aa3078"
        },
        "external_url": "https://checkout.stripe.com/c/pay/cs_test_..."
      }
    }
  }
}

As with liquidity.buy, the session_key here is the only way back to this subscription if you don't have an Amboss API key. Save it.

2. List subscriptions

Authenticated. Returns every subscription owned by the current account or session.

query ListSubscriptions {
  user {
    subscriptions {
      list {
        id
        active
        cancel_at_period_end
        monthly_amount
        period_end
        type
        created_at
        liquidity {
          payment_reliability_report
          node_pubkey { pubkey alias }
        }
      }
    }
  }
}

Response

{
  "data": {
    "user": {
      "subscriptions": {
        "list": [
          {
            "id": "sub_01HX9YQK7P8MVZ3FN4G2RWS6CD",
            "active": true,
            "cancel_at_period_end": false,
            "monthly_amount": "2500",
            "period_end": "2026-07-10T00:00:00Z",
            "type": "LIQUIDITY_SUBSCRIPTION",
            "created_at": "2026-06-10T00:00:00Z",
            "liquidity": {
              "payment_reliability_report": false,
              "node_pubkey": {
                "pubkey": "03abc...xyz",
                "alias": "my-node"
              }
            }
          }
        ]
      }
    }
  }
}

3. Get one subscription

query GetSubscription($subId: String!) {
  user {
    subscriptions {
      get_one(subId: $subId) {
        id
        active
        cancel_at_period_end
        monthly_amount
        period_end
        created_at
      }
    }
  }
}

4. Cancel a subscription

account.subscriptions.toggle flips a subscription between scheduled-cancel and not. Calling it on an active subscription sets cancel_at_period_end = true; calling it again before the period ends reverses that.

mutation ToggleSubscription($id: String!) {
  account {
    subscriptions {
      toggle(id: $id) {
        success
      }
    }
  }
}

{ "id": "sub_01HX9YQK7P8MVZ3FN4G2RWS6CD" }

curl -X POST https://magma.amboss.tech/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AMBOSS_API_KEY" \
  -d '{
    "query": "mutation($id: String!) { account { subscriptions { toggle(id: $id) { success } } } }",
    "variables": { "id": "sub_01HX9YQK7P8MVZ3FN4G2RWS6CD" }
  }'

const TOGGLE = gql`
  mutation ToggleSubscription($id: String!) {
    account { subscriptions { toggle(id: $id) { success } } }
  }
`;

await magma.request(TOGGLE, { id: subscriptionId });

Cancelling at period end is the default behaviour - the subscription continues to deliver liquidity until the paid period expires, then stops. Use period_end to know exactly when.

Subscription lifecycle

The active and cancel_at_period_end booleans on the subscription object map to this diagram:

`active`	`cancel_at_period_end`	Meaning
`true`	`false`	Subscription is live and will auto-renew.
`true`	`true`	Live until `period_end`, then stops.
`false`	-	Already cancelled or never activated.

Next steps

Buy Liquidity - one-time purchases
Tracking Orders - individual channels that a subscription opens still produce orders you can poll
Authentication - session-key vs API-key tradeoffs

Liquidity Subscriptions

On this page