Developer Guide

introduction the voltage api enables you to integrate lightning network functionality into your applications this guide will walk you through common tasks and help you get started with the api if you are starting here we are assuming that you already have a team and a staging wallet setup for you if you do not, the wallet setup guide will get you ready base url https //voltageapi com/v1 authentication the voltage api uses x api key authentication methods for api calls api key authentication (via x api key header) \ header 'x api key your api key' generating api key you can manage your api keys by visiting your team page and clicking on "api keys" be sure to select the correct environment for your api key when generating and give it a descriptive name quick start guides receiving a payment the payment flow for receiving payments follows these steps 1 create a new payment (returns 202 on success) curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments' \\ \ request post \\ \ data '{ "amount msats" 10000, "currency" "btc", "description" "test payment", "id" {payment id}, // unique uuid created by you "payment kind" "bolt11", "wallet id" {wallet id} }' 2 after receiving 202, fetch the payment details to get the invoice curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id}' \\ \ request get important the payment creation endpoint returns a 202 status code on success, indicating the request was accepted you must then fetch the payment details separately to get the invoice and monitor its status example payment details response { "bip21 uri" "lightning\ lntbs140n1pnag ", "created at" "2025 03 14t16 08 11 692963z", "currency" "btc", "data" { "amount msats" 14000, "memo" "test payment", "payment request" "lntbs140n1pnag " }, "direction" "receive", "environment id" "{environment id}", "error" null, "id" "11ca843c bdaa 44b6 965a 39ac550fcdf3", "organization id" "{organization id}", "status" "receiving", "type" "bolt11", "updated at" "2025 03 14t16 08 13 959324z", "wallet id" "{wallet id}" } sending a payment the payment flow for sending payments follows these steps 1 initiate payment send (returns 202 on success) curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments' \\ \ request post \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "id" "68d00852 8dd8 4c71 94d2 91c84695da78", # unique payment identifier "wallet id" "{wallet id}", "currency" "btc", "type" "bolt11", "data" { \# optional when payment request already has an amount \# required when payment request has no amount \# if provided with an amount containing payment request, values must match "amount msats" 150000, \# optional defaults to 1% of payment value or 1,000 msats (whichever is greater) "max fee msats" 1000, \# required lightning invoice to pay "payment request" "lntbs1500n1p " } }' 2 after receiving 202, fetch payment status to monitor progress curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id}' \\ \ request get important like the receive flow, the send payment endpoint returns a 202 status code on success you must fetch the payment details separately to monitor its status payment status monitoring when sending or receiving payments, you must actively monitor the payment status by fetching the payment details the status field will progress through these states for sent payments initial sending final completed or failed for received payments initial receiving final completed or failed best practices for monitoring poll the payment status endpoint every few seconds implement appropriate timeout logic handle both success and error states consider implementing webhook notifications for status changes example of checking payment status async function monitorpayment(paymentid) { while (true) { const response = await fetchpaymentstatus(paymentid); if (response status === 'completed') { return response; // payment successful } if (response status === 'failed') { throw new error(response error || 'payment failed'); } // wait before checking again await new promise(resolve => settimeout(resolve, 2000)); } } wallet balance management regularly check wallet balances to ensure sufficient funds curl 'https //voltageapi com/v1/organizations/{organization id}/wallets/{wallet id}' payment history track payment history and events curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id}/history' creating a staging wallet through the api in order to create a staging wallet through the api you must have already created your first wallet through the ui doing this will autmatically generated you a line of credit id that you can use to start creating new wallets through the api team page api keys api keys great! you now have the info required to make the request below and create staging wallets through the api curl 'https //voltageapi com/v1/organizations/{organization id}/wallets' \\ \ request post \\ \ data '{ "environment id" {environment id}, "id" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", # uuid you generate "line of credit id" "your line of credit id", \# denominated in msats "limit" 100000000, "metadata" { "tag" "testing wallet" }, "name" "my first wallet", "network" "mutinynet" }' metadata support add custom metadata to wallets for better organization curl 'https //voltageapi com/v1/organizations/{organization id}/wallets' \\ \ request post \\ \ data '{ "name" "customer wallet", "metadata" { "customer id" "cust 123", "purpose" "subscription payments" } // other wallet creation fields }' error handling the api uses standard http status codes 200 success 201 resource created 202 successfully requested a new payment be created 400 bad request 403 authentication/authorization error 404 resource not found 500 server error always check the response status and handle errors appropriately support and resources for additional support review the full api documentation remember to always use appropriate error handling and logging in your integration to ensure reliable operation of your lightning network payments