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 start with your agent the easiest way to get started is with the voltage agent skill pack install it in claude code, codex, hermes agent, opencode, or another supported coding agent to get help with voltage api integrations, payment workflows, and development wallet setup 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 choose the correct development wallet use mutinynet bitcoin for bitcoin backed implementations, including node backed bitcoin and credit backed bitcoin use mutinynet usd for usd line of credit testing voltage cash is the experimental stablecoin test wallet and is not currently live because the intended tether backed asset has not yet been minted 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 api keys are managed within the selected environment open the environment's api keys page and select create api key give the key a descriptive name, grant only the permissions the integration needs, and add an ip allowlist when the caller uses stable source addresses the secret is shown once store it in an approved secret manager and never place it in source control, screenshots, logs, tickets, or chat empty api keys page for the selected environment open api keys from the environment where the integration will run create api key form with permissions and an example ip allowlist grant only required permissions and add an ip allowlist when source addresses are stable quick start guides detailed guides available for comprehensive documentation on sending and receiving payments, see sending docid\ ijeswowxjhpgyt6fv1kk1 | sending (usd line of credit) docid 1qzxwddcqh5wuzv6qf 0a | sending (btc line of credit) docid\ vfp1sk87foititazykggo receiving docid uq9knquoc9sgq0kuogmy | receiving (usd line of credit) docid\ jymho26n377vgern3on i | receiving (btc line of credit) docid jue9lmowhdzxiihroq8v checkout (beta) docid\ ejqbzjnhgvpdci jyzgtv hosted lightning checkout overview, integration paths, and server side verification boundaries 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 \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "id" "{payment id}", "wallet id" "{wallet id}", "currency" "btc", "payment kind" "bolt11", "amount" { "amount" 10000, "currency" "btc", "unit" "msats" }, "description" "test payment" }' 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" { "amount" 14000, "currency" "btc", "unit" "msats" }, "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", "wallet id" "{wallet id}", "currency" "btc", "type" "bolt11", "data" { "payment request" "lntbs1500n1p ", "amount" { "amount" 150000, "currency" "btc", "unit" "msats" }, "max fee" { "amount" 1000, "currency" "btc", "unit" "msats" } } }' amount field optional when payment request already contains an amount required when payment request has no amount if provided with an amount containing invoice, values must match max fee optional defaults to 1% of payment value or 1,000 msats (whichever is greater) 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 usd wallets if you're using a usd denominated wallet, you must first obtain a quote via the quotes api before creating a payment see sending (usd line of credit) docid 1qzxwddcqh5wuzv6qf 0a for details 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 before creating another staging wallet through the api, confirm that the staging environment and its current funding resources already exist create the api key in that environment and retrieve the current organization, environment, and funding identifiers from supported api or product surfaces do not infer line of credit limits or identifiers from a fixed dashboard location the example below uses the mutinynet network before using it, create or select mutinynet bitcoin for node backed or credit backed bitcoin testing, or mutinynet usd for usd line of credit testing voltage cash is not used for either workflow curl 'https //voltageapi com/v1/organizations/{organization id}/wallets' \\ \ request post \\ \ header 'content type application/json' \\ \ header 'x api key your staging api key' \\ \ data '{ "environment id" "{environment id}", "id" "{client generated wallet id}", "line of credit id" "{line of credit id}", "limit" 100000000, "metadata" {"tag" "testing wallet"}, "name" "staging 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 https //voltageapi com/v1/docs remember to always use appropriate error handling and logging in your integration to ensure reliable operation of your lightning network payments