Wallet Management

managing wallets wallets are central to your voltage payments integration, allowing you to manage funds, track balances, and orchestrate transactions this guide covers the complete lifecycle of wallet management through the api authentication the voltage api uses x api key authentication methods for api calls api key authentication (via x api key header) your api key can be generated from the "api keys" page in the dashboard for all examples in this guide, we'll show bearer token authentication, but you can use either method based on your preference and security requirements voltage pay api keys you can also get all of your credentials in the developer modal in the top right! voltage pay develper button overview a wallet in voltage payments stores funds for lightning network and on chain transactions maintains balance history and transaction ledger can be assigned limits and credit allocations supports custom metadata for your application needs wallet endpoints the full api spec is https //voltageapi com/v1/docs method endpoint description get /organizations/{organization id}/wallets list all wallets in an organization post /organizations/{organization id}/wallets create a new wallet get /organizations/{organization id}/wallets/{wallet id} get a single wallet's details delete /organizations/{organization id}/wallets/{wallet id} delete a wallet get /organizations/{organization id}/wallets/{wallet id}/ledger get a wallet's transaction history patch /organizations/{organization id}/wallets/{wallet id} updatewalletrequest only allows updating the wallet name right now creating a wallet before creating wallets through the api, you must first create your initial wallet through the ui this process automatically generates a line of credit id needed for api wallet creation prerequisites create your first wallet through the ui generate an api key with read, write, and billing permissions retrieve your line of credit id from the api keys page (click on your api key and the sidebar will pop out with line of credit id) you can also list and inspect your lines of credit via the lines of credit api if you prefer to configure this programmatically createwallet request curl 'https //voltageapi com/v1/organizations/{organization id}/wallets' \\ \ request post \\ \ header 'authorization bearer your secret token' \\ \ header 'content type application/json' \\ \ data '{ "environment id" "{environment id}", "id" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", # uuid you generate "line of credit id" "your line of credit id", "limit" 100000000, # denominated in msats (100,000,000 msats = 0 001 btc) "metadata" { "tag" "testing wallet", "customer id" "cust 123" # your custom metadata }, "name" "customer wallet", "network" "mutinynet" # or "mainnet", "testnet3" }' required parameters parameter type description id string (uuid) unique identifier you generate for the wallet environment id string (uuid) environment id to create the wallet in line of credit id string (uuid) your line of credit id obtained from ui name string display name for the wallet network string network to use "mainnet", "testnet3", or "mutinynet" limit integer credit limit for this wallet, denominated in the smallest unit of your line of credit currency (e g msats for btc, cents for usd) for btc credit lines, 100000000 msats = 0 001 btc optional parameters parameter type description metadata object custom application data linked to this wallet response the api will return a 202 status code indicating the wallet creation request was accepted to verify the wallet was created successfully, you need to query the wallet list or get the wallet by id listing wallets retrieve all wallets in your organization curl 'https //voltageapi com/v1/organizations/{organization id}/wallets' \\ \ header 'authorization bearer your secret token' response example \[ { "id" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", "active" true, "created at" "2025 04 11t14 45 30 974z", "updated at" "2025 04 11t14 45 30 974z", "deleted at" null, "deletion failed at" null, "name" "customer wallet", "organization id" "b0684ab8 1130 46af 8f70 71519442f108", "environment id" "123e4567 e89b 12d3 a456 426614174000", "limit" 100000000, "line of credit id" "456e7890 f12c 34d5 b678 426614174000", "network" "mutinynet", "metadata" { "tag" "testing wallet", "customer id" "cust 123" }, "balances" \[ { "id" "123e4567 e89b 12d3 a456 426614174000", "wallet id" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", "effective time" "2025 04 11t14 45 30 974z", "available" { "amount" 50000000, "currency" "btc", "unit" "msats", "negative" false }, "total" { "amount" 50000000, "currency" "btc", "unit" "msats", "negative" false }, "network" "mutinynet", "currency" "btc" } ], "holds" \[], "error" null } ] getting a single wallet retrieve details for a specific wallet curl 'https //voltageapi com/v1/organizations/{organization id}/wallets/{wallet id}' \\ \ header 'authorization bearer your secret token' the response format is the same as a single wallet object from the list endpoint checking wallet balance the wallet details endpoint also returns the current balance information in the balances array you can regularly poll this endpoint to monitor available funds key balance fields available currently available balance in msats total total balance including funds on hold currency the currency of the balance (e g , "btc") viewing wallet transaction history to view all transactions for a wallet curl 'https //voltageapi com/v1/organizations/{organization id}/wallets/{wallet id}/ledger' \\ \ header 'authorization bearer your secret token' query parameters parameter type description offset integer starting point for pagination limit integer maximum number of records to return payment id string (uuid) filter by payment id start date string (date time) filter transactions after this date end date string (date time) filter transactions before this date sort key string field to sort by "effective time", "message time", or "time and effective time" sort order string order "asc" or "desc" response example { "items" \[ { "credit id" "123e4567 e89b 12d3 a456 426614174000", "payment id" "11ca843c bdaa 44b6 965a 39ac550fcef7", "amount" { "amount" 10000000, "currency" "btc", "unit" "msats" }, "currency" "btc", "effective time" "2025 04 11t14 45 30 974z", "type" "credited" }, { "credit id" "456e7890 f12c 34d5 b678 426614174000", "payment id" "3e84b6c5 5bbe 4e0f 9fb3 f1198330f6fa", "amount" { "amount" 50000000, "currency" "btc", "unit" "msats" }, "currency" "btc", "effective time" "2025 04 10t18 32 15 123z", "type" "debited" } ], "offset" 0, "limit" 10, "total" 2 } deleting a wallet to delete a wallet curl 'https //voltageapi com/v1/organizations/{organization id}/wallets/{wallet id}' \\ \ request delete \\ \ header 'authorization bearer your secret token' a successful deletion returns a 200 status code using wallet metadata wallet metadata allows you to store custom information with your wallets for internal tracking this field accepts any valid json object "metadata" { "customer id" "cust 123", "purpose" "subscription payments", "team" "engineering", "region" "north america" } metadata is returned with wallet objects and can be used for filtering and organization in your application best practices monitor wallet balances regularly to ensure sufficient funds for outgoing payments use meaningful wallet names and metadata to organize wallets by purpose or customer set appropriate wallet limits based on expected transaction volumes check the ledger periodically to reconcile transactions with your internal systems consider creating separate wallets for different business functions or customers troubleshooting issue resolution wallet creation fails verify your line of credit id and ensure you have sufficient credit allocation can't retrieve wallet check if the wallet id exists and your api key has appropriate permissions balance discrepancies check the ledger for recent transactions and any holds on funds "403 forbidden" errors verify your api key has the correct permissions for the operation