Get Started

Create an account

Sign up at app.amboss.tech. The first account on a team is the master account — the only role that can create environments and mint API keys.

Create a sandbox environment

Click "Create Sandbox Environment" on the dashboard, or call the API. Sandbox auto-provisions wallets for every available asset and supports deterministic test transitions via metadata flags.

See Environments for the API mutation and the amb_sandbox_behavior test hook.

Create a wallet (if needed)

Sandbox auto-creates wallets for every asset; in live you create them on demand. One wallet = one asset = one balance.

See Wallets for the create mutation, asset discovery, and amount precision rules.

Mint a service API key

Generate a key scoped to your sandbox environment with PAYMENTS: WRITE, WALLETS: WRITE, and WEBHOOKS: WRITE permissions. The plaintext_key is returned once — save it immediately.

All subsequent API calls use the x-api-key header:

x-api-key: amb_test_PvDaoBz6TXhuMKxk0VkckiPUTX9BTSDyCT2Pqc_vgOw

See API Keys for permissions and rotation.

Receive a test payment

Call create_receive with metadata.amb_sandbox_behavior = "complete". The invoice auto-settles after a short delay and fires payment.completed:

await client.request(CREATE_RECEIVE, {
  input: {
    wallet_id: walletId,
    amount: "100000",
    metadata: JSON.stringify({ amb_sandbox_behavior: "complete" }),
  },
});

amb_sandbox_behavior defaults to expire when omitted, so the flag above is what makes this invoice auto-settle instead of timing out. See Receive Payments for the full input reference.

Listen for the webhook

Register an endpoint with payment.completed in event_filters. In sandbox you can point it at a temporary URL via webhook.site to inspect the payload, or use the dashboard's "Generate test URL" button.

Dedupe on the envelope id — webhooks deliver at-least-once.

See Webhooks for the payload shape, signature verification, and retry behaviour.

Try sending

Use @ambosstech/payments and call transactions.send with a password and either a BOLT11 invoice or Lightning Address. The SDK uses the password locally to decrypt the admin macaroon and call the node in production. It also requires the password in sandbox, where no node RPC runs, so your test code has the same call shape as production. Any non-empty sandbox value, such as Password123, works because it is not used. Set metadata.amb_sandbox_behavior to drive the sandbox terminal state.

See Send Payments for an SDK example, the complete payment flow, and network constraints.

Go live

When the sandbox flow works end-to-end, click "Go Live" in the dashboard. KYB is collected via Stripe; afterwards you can create a LIVE environment, mint amb_live_… keys, and create wallets that route real Lightning traffic.

See Environments → Going live.