Lightning Addresses

A Lightning Address looks like an email address: [email protected]. Anyone with a Lightning wallet can pay it without asking you for an invoice first. Each payment lands in the wallet the address points to.

Rules

• Live only. Addresses receive real payments, so you can only claim them in a live environment.
• BTC wallets only. Stablecoin wallets can't receive to an address yet.
• Up to 5 per team, counted across all your environments.
• Names are 4 to 32 characters: lowercase letters, numbers, dots, dashes and underscores. They start and end with a letter or number. Names are first come, first served.
• Amounts from 1 to 10,000,000 sats per payment. The payer's wallet shows these limits.
• Description is optional, up to 100 characters. The payer's wallet shows it. Without one, it shows Payment to [email protected].

In the dashboard

1. Open your live environment and go to Lightning Addresses.
2. Click Claim address, type a name, pick a BTC wallet and optionally add a description.
3. Share [email protected].

To stop an address receiving payments, click Disable. The name stays yours and still counts toward your limit. Pick a wallet again to turn it back on.

With the API

Reads need a service API key with PAYMENTS: READ, and claiming or changing an address needs PAYMENTS: WRITE. Use a key for the whole environment: Lightning Addresses belong to the environment, so a key limited to one wallet or node is refused. See API Keys.

Claim an address

payment.lightning_address.create(input: CreateLightningAddressInput) → LightningAddress

mutation CreateLightningAddress {
  payment {
    lightning_address {
      create(input: {
        environment_id: "81b73615-ddf3-46e3-943a-467c3e442e04"
        name: "shop"
        wallet_id: "5e4b1e2a-9f3c-4a5b-8c7d-1234567890ab"
      }) {
        id
        name
        wallet_id
        created_at
      }
    }
  }
}

curl -X POST https://app.amboss.tech/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: $AMBOSS_API_KEY" \
  -d '{
    "query": "mutation($input: CreateLightningAddressInput!) { payment { lightning_address { create(input: $input) { id name wallet_id created_at } } } }",
    "variables": {
      "input": {
        "environment_id": "81b73615-ddf3-46e3-943a-467c3e442e04",
        "name": "shop",
        "wallet_id": "5e4b1e2a-9f3c-4a5b-8c7d-1234567890ab"
      }
    }
  }'

Errors you might see:

• Lightning address name is already taken: pick another name.
• You cannot claim this Lightning address: the name is reserved.
• A team can have at most 5 Lightning addresses: disable won't free a slot; the name stays yours.

Change the wallet, or disable

payment.lightning_address.assign_wallet(input: AssignLightningAddressWalletInput) → LightningAddress

Send a new wallet_id to move the address to another BTC wallet. Send wallet_id: null to disable it: payers then get a "Lightning Address not found" error.

mutation DisableLightningAddress {
  payment {
    lightning_address {
      assign_wallet(input: {
        id: "0f9a7c3e-2b1d-4e5f-8a6b-9c0d1e2f3a4b"
        wallet_id: null
      }) {
        id
        wallet_id
      }
    }
  }
}

Change the description

payment.lightning_address.update_description(input: UpdateLightningAddressDescriptionInput) → LightningAddress

Send null or an empty string to go back to the default text.

mutation UpdateLightningAddressDescription {
  payment {
    lightning_address {
      update_description(input: {
        id: "0f9a7c3e-2b1d-4e5f-8a6b-9c0d1e2f3a4b"
        description: "Coffee at My Shop"
      }) {
        id
        description
      }
    }
  }
}

List your addresses

list returns the addresses in one environment. max is the limit for the whole team. count is how many you have: across the team in the dashboard, or in the key's environment with an API key.

query ListLightningAddresses {
  payment {
    lightning_address {
      find_many {
        list(environment_id: "81b73615-ddf3-46e3-943a-467c3e442e04") {
          id
          name
          wallet_id
          description
        }
        count
        max
      }
    }
  }
}

Getting paid

Each payment to your address is a normal receive in the wallet. You track it the same way as an invoice you made with create_receive:

• A PENDING receive transaction appears when the payer's wallet asks for an invoice, with a payment.pending webhook.
• It moves to COMPLETED when paid (payment.completed), or EXPIRED if the payer never pays (payment.expired).

See Webhooks for the payload.

Next steps