# Bitcoin payments

> Fund a BTC balance over Lightning or on-chain, pay for requests in sats with BTC keys, and read USD-indexed Bitcoin prices.

Source: https://0.0.0.0:3000/docs/account/bitcoin
Documentation index: https://0.0.0.0:3000/docs/llms.txt

An account can hold a BTC balance next to its USD balance and pay for requests in sats. Bitcoin is a separate currency end to end: you fund it with Bitcoin, spend it with BTC keys, and nothing is converted between USD and BTC. If [Billing](/dashboard/billing) shows no **Bitcoin** row, Bitcoin funding isn't available for your account.

## How the BTC currency works

- **Separate balance.** The BTC balance is never added to, converted to or used as a fallback for the USD balance.
- **BTC keys.** Only an inference key created with **Currency** set to **BTC** spends it. The choice is permanent; see [API keys](/docs/account/api-keys#the-billing-currency-is-permanent).
- **Sats.** For BTC keys, every price and cost in the API is in sats: `1` is one sat. Charges are exact decimals; payments on the Bitcoin network are whole sats.
- **BTC offers only.** A BTC key routes only to offers priced in BTC. A model with only USD offers doesn't appear in its [`GET /models`](/docs/api-reference/models/list-models) list.

The dashboard writes sats with the ₿ sign: `₿25,000` is 25,000 sats, and `₿120/M` is 120 sats per million tokens. Amounts are never shown as fractional BTC.

## Add Bitcoin credits

:::steps
### Open the dialog

In [Billing](/dashboard/billing), choose **Add Bitcoin** on the **Bitcoin** row. In an organization, only owners and administrators can do this.

### Choose a payment method

| Method | Dashboard label | Use it when |
| --- | --- | --- |
| **Bitcoin address** | Any amount · needs confirmations | Paying from an on-chain wallet or exchange, or sending several payments |
| **Lightning invoice** | Exact amount · settles in seconds | Paying from a Lightning wallet |

### Enter the amount

Enter sats in **Amount (sats)**, or switch the unit to **USD**. Presets are ₿10,000, ₿25,000, ₿50,000 and ₿100,000, or $10, $25, $50 and $100. If the amount is outside the deposit limits, the dialog shows the minimum or maximum under it.

### Create the payment request and pay

Choose **Create payment request**. The receipt shows a QR code and the address or invoice, with **Copy address** or **Copy invoice**, plus the platform fee and the credits you'll receive. Pay from your wallet; the receipt updates until the payment is credited.
:::

### Entering a USD amount

A USD amount is a convenience for choosing how many sats to request. It's converted once, at the current BTC/USD reference price, and the request is in sats from then on:

- You're credited the bitcoin actually received, not a dollar value.
- The USD balance is never read or changed.
- If the converted amount is outside the deposit limits, the dialog shows the minimum or maximum under the amount.
- If no reference price is available, the dashboard asks you to enter sats instead.

## Lightning

The dashboard creates a fixed-amount Lightning invoice for exactly the requested amount. A paid invoice is usually credited within seconds. The receipt shows when the invoice expires; after that it reads **This invoice expired and can no longer be paid.** Create a new request.

## On-chain

The dashboard creates a Bitcoin address for this one funding request. The QR code includes the requested amount, so most wallets prefill it.

- **Any amount.** The entered amount is a suggestion. The amount actually received is credited, whether less or more.
- **Several payments.** Partial and repeated payments to the address are each credited once they confirm.
- **Confirmations.** A payment is credited after sufficient network confirmations. Unconfirmed payments are never credited.
- **Network fee.** The network fee for receiving the payment is deducted from the credit. Until then the receipt shows estimated credits; once credited it shows the actual **Network fee**.
- **Limited watch period.** The receipt shows how long the address is watched. After that it reads **This address has expired. New payments to it won't be credited automatically.** Don't reuse an old address; create a new request.

## Receipts and fees

Every deposit appears in **Funding history** and opens its receipt. The receipt shows **Credits added**, **Platform fee** and, for on-chain payments, **Network fee** and **Confirmations**. The QR code and address or invoice appear only while the request can still be paid.

The platform fee on Bitcoin funding is taken from the amount you send; there's no fee on requests themselves. Partial or repeated payments don't change the total fee.

| Status | Meaning |
| --- | --- |
| **Starting** | The payment request is being prepared |
| **Awaiting payment** | Scan or copy the address or invoice to pay |
| **Confirming** | Payment seen, waiting for confirmations |
| **Claiming** | Confirmed; the credit is being posted |
| **Credited** | The credit is in your BTC balance |
| **Expired** | The invoice expired, or the address stopped being watched without a payment |
| **Failed** | The payment didn't complete |
| **Needs attention** | The deposit is under review. Don't send more to this request; contact support with the receipt reference |

Processing can occasionally be delayed. A delay doesn't mean a payment failed: keep the existing request and check its receipt before paying again.

## Pay for requests in sats

Create an inference key with **Currency: BTC** and use it like any other key. Everything money-related is then in sats:

- `pricing` in `GET /models` and the endpoints list, for example sats per token;
- `usage.cost` and `cost_details.upstream_inference_cost` on every response;
- `provider.max_price`;
- `limit`, `usage` and `limit_remaining` on the key.

```json title="Usage on a BTC key"
{
  "usage": {
    "prompt_tokens": 812,
    "completion_tokens": 164,
    "total_tokens": 976,
    "cost": 2.831647,
    "cost_details": { "upstream_inference_cost": 2.831647 }
  }
}
```

This request cost about 2.8 sats. Reservations, spending limits and `402` responses work as for USD; see [Credits and payments](/docs/account/credits#reservations).

## USD-indexed Bitcoin prices

A provider can price a BTC offer in one of two ways:

| Pricing | Catalogue label | Behavior |
| --- | --- | --- |
| **Fixed in sats** | A sat rate | The rate doesn't move with the exchange rate |
| **USD-indexed** | **Variable · USD-indexed** | The provider sets a USD rate; the sat rate follows the BTC/USD reference |

For a USD-indexed offer, the sat rate is `USD per unit × 100,000,000 / USD per BTC`, calculated exactly from a regularly refreshed BTC/USD reference.

The reference uses the median of fresh quotes from Coinbase, Kraken, Bitstamp and Bitfinex. At least two exchanges must agree within the configured price range. If an exchange is unavailable, the remaining quotes can keep indexed prices available. A missing or expired reference still prevents new indexed requests.

- **Locked per request.** The reference is locked when the request is routed and doesn't change while it runs.
- **History.** Logs show **Locked · USD-indexed** with the reference that applied.
- **API fields.** In `GET /models` and the endpoints list, USD-indexed prices carry `pricing_basis: "usd_indexed"`, the `reference` used (including `usd_per_btc`) and the provider's `usd_rates`. The `pricing` values are the sat rates.
- **No reference, no route.** Without a current reference, USD-indexed offers drop out of discovery and routing; fixed-sat offers are unaffected.

You still pay in sats from your BTC balance; no dollars are involved.

## What isn't offered

- **No currency conversion.** A BTC key with an empty BTC balance fails with `402`, even if the USD balance is funded.
- **No automatic Bitcoin top-up.** Auto top-up is card-only and USD-only.
- **No amountless invoices.** Lightning funding uses fixed-amount invoices.
- **No refunds or self-service withdrawal of customer credit.** To ask about returning bitcoin, contact support.

Provider earnings in BTC are withdrawn separately; see [Earnings and payouts](/docs/providers/earnings).

## Next steps

:::cards
- {coins} [Credits and payments](/docs/account/credits) Balances, reservations and spending limits.
- {key} [API keys](/docs/account/api-keys) Create a BTC key.
- {receipt} [Usage accounting](/docs/account/usage-accounting) How each request is measured and charged.
- {compass} [Models](/docs/models) Find models with BTC offers.
:::