Set up Amboss Payments for an L402 API

Amboss Payments is a GraphQL API for sending and receiving payments over the Lightning Network. For an L402 seller, it is the part that creates invoices and tells you when they're paid. You start in a free sandbox, mint an API key, create a BTC wallet, create invoices, and listen for webhooks. Going live adds a business verification step and a short wait while your wallet is provisioned. This page walks through each step and links to the Amboss docs, which are the source of truth.

This is step 1 of the Sell to agents flow. Amazap is a flagship user of the Amboss API and runs its own payments on it.

Create your Amboss account

Disclosure: Amazap is an Amboss referral partner. Amazap earns a referral credit if you sign up through this link.

What Amboss Payments gives you

From the Amboss Payments docs and amboss.tech:

Step 1: Create your account

Sign up through the link above. The first account on a team becomes the master account, the only role that can create or revoke API keys (Integrate the Payments API). Every step below can be done in the dashboard at app.amboss.tech/pay or through the API.

Step 2: Create a sandbox environment

An environment holds your wallets, API keys, and webhook endpoints. Start with SANDBOX: payments settle in simulation, no Lightning node is needed, and sandbox wallets are created for you and ready immediately (Environments).

Step 3: Mint an API key

Keys are scoped by resource (ENVIRONMENTS, WALLETS, PAYMENTS, WEBHOOKS) and level (READ or WRITE). For an L402 server, PAYMENTS: WRITE covers creating invoices; add WEBHOOKS if your server registers its own endpoint. Sandbox keys start with amb_test_. The plaintext key is shown once, so put it straight into your secret manager. Your backend then sends it as x-api-key (Integrate the Payments API).

Step 4: Pick a BTC wallet

A wallet holds exactly one asset. List the available assets at runtime with the taproot_assets query; BTC appears as the base asset. Amounts are always decimal strings in the asset's smallest unit, so for BTC, sats: "100" is 100 sats (Wallets).

Step 5: Create an invoice for each paid request

When an unpaid request arrives, your L402 handler calls payment.transaction.create_receive with:

FieldUse in L402
wallet_idYour BTC wallet
amountYour per-call price in sats, as a string
descriptionShown to the payer, for example the endpoint name
expires_in_secondsDefaults to 10 minutes; set it to cover slow clients
idempotency_keyLets you retry safely without creating duplicate invoices
metadataYour own JSON, returned on webhooks

It returns a BOLT11 payment_request and a payment_hash (Receive Payments). The starter kit signs an HMAC L402 token that commits to that hash and returns the token with the invoice. Amboss does not document an L402 macaroon API. A Lightning macaroon, as the L402 spec describes it, is still accepted by Amazap's probe. The protocol is explained in Monetize an API with Lightning.

Step 6: Add webhooks for your records

Register an endpoint for payment.completed, payment.failed, and payment.expired. Verify every delivery: compute HMAC-SHA256 over ${timestamp}.${rawBody} with your endpoint secret and compare it to the x-webhook-signature header, using the x-webhook-timestamp header. Use the raw body, not re-serialized JSON, and dedupe on the event id (Verify Webhooks).

With L402, the preimage check already proves payment on the request itself, so webhooks are for accounting and reconciliation rather than gating the response. Amboss also notes that the amount you're credited is settle_amount, not amount, because Amboss's fee sits between them (Prompt for Agents).

Step 7: Test the branches in sandbox

Sandbox outcomes are deterministic. Put amb_sandbox_behavior in the invoice metadata as complete, fail, or expire (the default) to exercise each path (Environments).

For the Amazap listing probe, all your endpoint needs is to answer an unpaid request with a valid L402 challenge.

Step 8: Go live

From the Environments docs:

Next steps

  1. Put your endpoint behind L402 with the starter kit.
  2. Decide your price: How to price an API for AI agents.
  3. List it: List your L402 endpoint on Amazap.

Back to the overview: How to sell your API to AI agents. Curious what buyers see? Agents shop through the Amazap MCP server; the buyer side is in Agentic payments explained.

Set up Amboss Payments

Disclosure: Amazap is an Amboss referral partner. Amazap earns a referral credit if you sign up through this link.

FAQ

Is there a free Amboss sandbox?

Yes. Amboss says the sandbox is free and needs no card. Sandbox payments are simulated and need no Lightning node.

Does Amboss hold my funds?

Amboss says it never holds, receives, or proxies your funds. Payments settle to your own wallet.

How much does Amboss Payments cost?

Amboss says pricing is tailored to your payment volume and business requirements, and asks you to talk to their team. Amazap doesn't publish Amboss pricing.

Do I need a Lightning node?

Not for sandbox. A live environment has a Lightning node attached, and live wallets take about 30 minutes to be provisioned with liquidity. See the Amboss environment docs.

Does Amboss Payments support L402 directly?

The Amboss docs describe a payments API: invoices, payment status, and webhooks. The L402 token and preimage check run in your code. The Amazap seller starter signs an HMAC token bound to the payment hash Amboss returns, and checks the preimage locally. Amboss does not issue the L402 token.

Is there an SDK?

Yes. Amboss publishes an official TypeScript SDK, @ambosstech/payments, and a copy-paste prompt for coding agents. The API is standard GraphQL, so any language works.

How is Amazap related to Amboss?

Amazap is its own company. It is a flagship user of the Amboss API and an Amboss referral partner, and it earns a referral credit when you sign up through Amazap's link.

Sources