Developer Guide

Sending (BTC Line of Credit)

Sending Payments with Bitcoin Line of Credit

This guide explains how to send Lightning Network and on-chain Bitcoin payments from a BTC-denominated wallet using the Voltage Payments API.

Prerequisites

A Voltage account with an active BTC wallet (wallet associated with a Bitcoin line of credit)
An API key (from the “API Keys” page in your dashboard)

Sending a Payment

Endpoint

POST https://voltageapi.com/v1/organizations/{organization_id}/environments/{environment_id}/payments

Headers

x-api-key: your-api-key
Content-Type: application/json

Lightning Payment (bolt11)

{
  "id": "68d00852-8dd8-4c71-94d2-91c84695da78",
  "wallet_id": "7a68a525-9d11-4c1e-a3dd-1c2bf1378ba2",
  "currency": "btc",
  "type": "bolt11",
  "data": {
    "payment_request": "lntbs1500n1p...",
    "amount": {
      "currency": "btc",
      "amount": 150000,
      "unit": "msats"
    },
    "max_fee": {
      "currency": "btc",
      "amount": 1000,
      "unit": "msats"
    }
  }
}

Request Fields

id – Unique identifier for the payment (UUID you create)
wallet_id – ID of the BTC wallet sending the payment
currency – Must be “btc”
type – “bolt11” for Lightning payments
data.payment_request – The Lightning invoice to pay (required, cannot be empty)
data.amount – 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 (in msats)
data.max_fee – Optional maximum routing fee (defaults to 1% of payment value or 1,000 msats, whichever is greater)

On-Chain Payment

{
  "id": "2ec1e783-19b4-4c10-8181-66336a6232bd",
  "wallet_id": "7a68a525-9d11-4c1e-a3dd-1c2bf1378ba2",
  "currency": "btc",
  "type": "onchain",
  "data": {
    "address": "tb1pzkhtj4ld86g9c49du5yagnncfrm0s489t76vmrwmt2ecxfnf7spsvjte49",
    "amount": {
      "currency": "btc",
      "amount": 15000000,
      "unit": "msats"
    },
    "max_fee": {
      "currency": "btc",
      "amount": 1000000,
      "unit": "msats"
    },
    "description": "test payment"
  }
}

Request Fields

type – “onchain” for on-chain payments
data.address – The recipient’s Bitcoin address
data.amount – Amount to send in msats (15,000,000 msats = 15,000 sats)
data.max_fee – Optional maximum miner fee in msats
data.description – Optional memo

Unified Payment (bip21)

A BIP21 URI can include both an on-chain address and a Lightning invoice.

{
  "id": "3e84b6c5-5bbe-4e0f-9fb3-f1198330f6fa",
  "wallet_id": "7a68a525-9d11-4c1e-a3dd-1c2bf1378ba2",
  "currency": "btc",
  "type": "bip21",
  "data": {
    "address": "bitcoin:tb1pzkhtj4ld86g9c49du5yagnncfrm0s489t76vmrwmt2ecxfnf7spsvjte49?lightning=lntbs1500n1p...",
    "payment_request": "lntbs1500n1p...",
    "amount": {
      "currency": "btc",
      "amount": 150000,
      "unit": "msats"
    },
    "max_fee": {
      "currency": "btc",
      "amount": 1000,
      "unit": "msats"
    },
    "description": "Payment for services"
  }
}

Required Fields

id – Unique identifier for the payment (UUID you create)
wallet_id – ID of the BTC wallet sending the payment
currency – Must be “btc”
type – Must be “bip21”
data.address – BIP21 URI to pay (cannot be empty)

Optional Fields

data.payment_request – Lightning invoice (if you want to pass it separately)
data.amount – BTC Amount object in msats
data.max_fee – BTC Amount object in msats (max Lightning fee)
data.description – Optional description/memo

Example Implementations

Lightning Payment

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": "7a68a525-9d11-4c1e-a3dd-1c2bf1378ba2",
    "currency": "btc",
    "type": "bolt11",
    "data": {
      "payment_request": "lntbs1500n1p...",
      "amount": {
        "currency": "btc",
        "amount": 150000
      },
      "max_fee": {
        "currency": "btc",
        "amount": 1000
      }
    }
  }'

On-Chain Payment

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": "2ec1e783-19b4-4c10-8181-66336a6232bd",
    "wallet_id": "7a68a525-9d11-4c1e-a3dd-1c2bf1378ba2",
    "currency": "btc",
    "type": "onchain",
    "data": {
      "address": "tb1pzkhtj4ld86g9c49du5yagnncfrm0s489t76vmrwmt2ecxfnf7spsvjte49",
      "amount": {
        "currency": "btc",
        "amount": 15000000
      },
      "max_fee": {
        "currency": "btc",
        "amount": 1000000
      },
      "description": "test payment"
    }
  }'

Monitoring Payment Status

After sending a payment, monitor its status using:

GET https://voltageapi.com/v1/organizations/{organization_id}/environments/{environment_id}/payments/{payment_id}

Example

curl 'https://voltageapi.com/v1/organizations/{organization_id}/environments/{environment_id}/payments/{payment_id}' \
  --header 'x-api-key: your-api-key'

Payment States

sending – Payment is in progress
completed – Payment was successful
failed – Payment failed (check the error field for details)

Error Handling

HTTP Status Codes

200 – Success
400 – Invalid request (check error message)
403 – Authentication error
404 – Payment not found
500 – Server error

Common Errors

Invalid invoice – The Lightning invoice is malformed or expired
Insufficient balance – Your BTC wallet doesn’t have enough funds
Route not found – No viable Lightning route to the destination
Invalid address – The Bitcoin address is invalid