API Reference

Complete GraphQL operation index for the Magma liquidity marketplace API, plus the LSP REST endpoints and the core type definitions.

Every operation Magma exposes, with links to the guide that explains how to use it. For interactive exploration use the Apollo Studio Explorer.

Endpoint

https://magma.amboss.tech/graphql

Authenticate as described in Authentication:

Authorization: Bearer YOUR_API_KEY_OR_SESSION_KEY

The LSP REST surface is mounted under the same host:

https://magma.amboss.tech/api/lsp/v1/{type}/...

See LSP REST API.

Queries

Public - no credentials required

Operation	Purpose	Guide
`market.liquidity.liquidity_per_usd`	Current `sats` and expected `usd` receiving capacity per USD spent.	Buy Liquidity
`market.offer.offers(page)`	Paginated list of all enabled offers on the marketplace.	Orders and Offers
`market.offer.get_offer(offer_id)`	Single offer with full detail.	Orders and Offers
`market.offer.offer_book`	Depth chart of offers across price tiers.	-
`market.transaction.get_outputs(tx_id)`	Outputs of a Bitcoin transaction (used to identify channel anchors).	-
`node.identifier_info`	Signing challenge for connecting a Lightning node to your account.	-
`node.node_info(connection_uri)`	Public information about a given Lightning node.	-
`assets.list(page)`	Supported channel assets (BTC base + Taproot Assets).	-

Authenticated - API key or session key

Operation	Purpose	Guide
`user` (root)	Current user - email, telegram, connected nodes.	Authentication
`user.market.offers.offers(page)`	Your offers.	Create Offers
`user.market.offers.get_offer(offer_id)`	One of your offers with full detail.	Create Offers
`user.market.orders.purchases(input, page)`	Orders where you're the buyer. Use `input.action_needed` to filter.	Tracking Orders
`user.market.orders.sales(input, page)`	Orders where you're the seller.	Sell Liquidity
`user.market.orders.get_order(order_id)`	Single order with full state.	Tracking Orders
`user.market.recent_nodes`	Nodes you've recently interacted with.	-
`user.market.stats`	Aggregate stats: active offers, total purchased/sold.	-
`user.subscriptions.list`	Your liquidity subscriptions.	Subscriptions
`user.subscriptions.get_one(subId)`	One subscription's full detail.	Subscriptions
`user.transactions.transaction_list(page)`	Your payment history (one-time orders + subscription invoices).	-
`user.transactions.get_one(transaction_id)`	One transaction's full detail.	-
`user.nodes`	Lightning nodes connected to your account.	-

Mutations

Public - no credentials required

Operation	Purpose	Guide
`liquidity.buy(input)`	One-off purchase of inbound liquidity.	Buy Liquidity
`liquidity.create_subscription(input)`	Recurring monthly liquidity subscription.	Subscriptions

Authenticated

Operation	Purpose	Guide
`market.offer.create(input)`	Post a new offer.	Create Offers
`market.offer.update(input)`	Modify an offer's fees, caps, conditions, or sizes.	Create Offers
`market.offer.toggle(input)`	Enable / disable an offer.	Create Offers
`market.order.create(input)`	Manual order against a specific offer.	-
`market.order.cancel(input)`	Cancel a pending order.	Errors
`market.order.seller.accept(input)`	Accept an order with a BOLT11 HODL invoice.	Sell Liquidity
`market.order.seller.reject(input)`	Reject a pending order.	Sell Liquidity
`market.order.seller.add_transaction(input)`	Report the funding TX for an accepted order.	Sell Liquidity
`account.node.connect(input)`	Verify ownership of a Lightning node and link it to your account.	-
`account.subscriptions.toggle(id)`	Cancel / reactivate a subscription.	Subscriptions

Order state reference

See Order Lifecycle for the full state machine and recovery semantics.

Core types

A condensed reference for the types you'll see in every response. Full definitions in Orders and Offers.

`SatoshiValue`

Every Bitcoin amount returned by the API.

type SatoshiValue {
  sats: String!             # Integer string
  btc: String!              # Decimal string
  usd: String!              # USD at current rate
  historical_usd: String    # USD at the resource's creation time
}

`SizeValue`

A multi-asset wrapper. satoshi is populated for BTC channels; asset is populated for Taproot Asset channels.

type SizeValue {
  satoshi: SatoshiValue
  asset: AssetAmount
}

`MarketOfferFees` vs `MarketOrderFees`

Offers carry fee structure; orders materialise it for both parties.

type MarketOfferFees {
  fixed: SatoshiValue!      # Base fee per channel
  variable: SatoshiValue!   # Rate-based fee (ppm)
  amboss: SatoshiValue!     # Marketplace fee
}

type MarketOrderFees {
  fixed: SatoshiValue!
  variable: SatoshiValue!
  amboss: SatoshiValue!
  buyer: SatoshiValue!      # Total the buyer pays
  seller: SatoshiValue!     # Net the seller earns
}

`MarketOfferPromises` / `OrderPromises`

The commitments locked in for the channel's lock period.

type MarketOfferPromises {
  base_fee_cap: String      # Max base fee (sats) for min_block_length
  fee_rate_cap: String      # Max fee rate (ppm) for min_block_length
  min_block_length: Float!  # Minimum blocks the channel must remain open
}

type OrderPromises {
  locked_base_fee_cap: SatoshiValue!
  locked_fee_rate_cap: SatoshiValue!
  locked_min_block_length: Float!
}

Enums

Enum	Values
`OfferStatus`	`ENABLED`, `DISABLED`, `ADMIN_DISABLED`
`MarketOrderStatus`	17 values - see Order Lifecycle
`MarketOrderPaymentStatus`	`PENDING_PAYMENT`, `SUCCESSFUL_PAYMENT`, `HODL_INVOICE_TIMEOUT`, `SELLER_INVOICE_EXPIRED`, `PAYMENT_FAILED`, `PAYMENT_REJECTED_BY_DESTINATION`, `INVALID_PAYMENT_SECRET`
`OrderCancellationReason`	`CHANNEL_SIZE_OUT_OF_BOUNDS`, `UNABLE_TO_CONNECT_TO_NODE`, `UNABLE_TO_PAY`
`OfferCondition`	`NODE_CAPACITY`, `NODE_CHANNELS`, `NODE_SOCKETS`, `PARALLEL_CHANNELS`, `TERMINAL_WEB_RANK`
`OfferConditionOperator`	`EQUAL_TO`, `NOT_EQUAL_TO`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`, `CONTAINS`, `DOES_NOT_CONTAIN`
`OnchainPriority`	`LOW`, `MEDIUM`, `HIGH`
`ChannelAssetType`	`BASE_ASSET`, `TAPROOT_ASSET`
`TransactionStatus`	`PENDING`, `CONFIRMED`, `FAILED`, `CANCELLED`
`TransactionCurrency`	`BITCOIN_SAT`, `FIAT_USD_CENT`
`UserTransactionType`	`LIQUIDITY_ORDER`, `LIQUIDITY_SUBSCRIPTION`
`SubscriptionType`	`LIQUIDITY_SUBSCRIPTION`
`PaymentMethod`	`AMBUCKS`, `SATS`

Pagination

Most list queries accept a PageInput and return a Pagination block.

input PageInput {
  limit: Float!     # default 10
  offset: Float!    # default 0
}

type Pagination {
  limit: Float!
  offset: Float!
}

The list type also exposes a total field for "how many items exist in total" without re-fetching.

Errors

GraphQL errors come back in the standard errors array on the response. See Errors for the catalog and recovery patterns.

A 200 OK HTTP status doesn't mean the operation succeeded - GraphQL always returns 200. Check errors before reading data.

Tooling

Apollo Studio Explorer - magma (public schema, run real queries)
Schema file - Available as a .gql introspection result via Apollo Studio's download button
Postman / Insomnia - Use the GraphQL request type and point at https://magma.amboss.tech/graphql

Next steps

Integrate - end-to-end walkthrough
Authentication - credential matrix
Errors - error catalog
LSP REST API - BLIP-0051 alternative path

API Reference

On this page