# 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.

:::note
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)

:::note
**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

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

### Headers

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

### Lightning Payment (bolt11)

```json
{
  "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

```json
{
  "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

:::caution
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.

```json
{
  "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

```bash
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

```bash
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:

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

### Example

```bash
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