Sending (BTC Line of Credit)

17 min

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.

For Development testing, choose Mutinynet Bitcoin. This is the correct wallet for a Bitcoin line of credit as well as Node-backed Bitcoin testing. Mutinynet USD and Voltage Cash are not the correct wallets for this workflow.

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)

No quotes needed! Unlike USD wallets, BTC wallets send payments directly in BTC without currency conversion. You do not need to use the Quotes API.

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

For accounting simplicity, please separate Lightning and on-chain usage between different wallets if you are on a node-backed setup.

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