---
name: bsv-micropayments
description: "Design or implement paying for use rather than by subscription: HTTP 402 payment inside a web request, prices of a few satoshis, allowances so there is no prompt per payment, showing the running total, and stopping instantly. Use when asked to 'charge per article', 'add HTTP 402', 'pay per API call', 'paywall with BSV', 'stream payments', 'show what I've spent', or anything about many small payments."
---

> Start from [bitcoinsv-design](../bitcoinsv-design/SKILL.md). Shared states, labels, errors, amounts and fees: [shared patterns](../bitcoinsv-design/references/shared-patterns.md).

# Charge per use with BSV micropayments

**Scope:** Paying for an article, a request or a minute: the 402 exchange, allowances, the running total and the stop control.

**Does NOT cover:**

- Asking for the allowance itself: see [bsv-wallet-connection](../bsv-wallet-connection/SKILL.md)
- Software deciding what to buy: see [bsv-agent-spending](../bsv-agent-spending/SKILL.md)

**Cross-references:** [bsv-wallet-connection](../bsv-wallet-connection/SKILL.md), [bsv-agent-spending](../bsv-agent-spending/SKILL.md), [bsv-amounts-and-copy](../bsv-amounts-and-copy/SKILL.md), [shared patterns](../bitcoinsv-design/references/shared-patterns.md).

Amounts of a few satoshis are practical on BSV, so there is no need to batch use into a subscription or a credit balance. The design problem moves from taking the payment to keeping it visible: a prompt per payment makes paying per use unusable, and no visibility at all makes it a blank cheque. The answer is a bounded allowance, the cost written on the thing, a running total where the spending happens, and a stop that works instantly.

## ALWAYS

- Name the article being bought on the wallet's payment sheet, so the reader can see that the thing she tapped is the thing she is paying for. _([costs money](https://www.bitcoinsv.design/guide/rule/dc76c094e7/))_
- Stop charging the moment the reader taps Stop, before any confirmation or animation, and say how much she spent today. _([costs money](https://www.bitcoinsv.design/guide/rule/2981555d83/))_
- Show the running total against the allowance wherever the spending is happening, not only in a settings screen. _([costs trust](https://www.bitcoinsv.design/guide/rule/758fae5e4a/))_
- Put a stop control next to that total. One action, no confirmation, effective immediately. _([costs trust](https://www.bitcoinsv.design/guide/rule/780419e009/))_
- Make stopping obvious and instantaneous, and confirm that it stopped. "Stopped. You spent 340 sats." closes the loop. _([costs trust](https://www.bitcoinsv.design/guide/rule/0b795249b1/))_
- Offer a ceiling before starting, not only an allowance. "Stop at 5,000 sats" is a different and more reassuring promise. _([costs trust](https://www.bitcoinsv.design/guide/rule/c46631d9e7/))_

## NEVER

- Charge for an article the reader has already bought, whether she returns to it on the same day or a month later. _([costs money](https://www.bitcoinsv.design/guide/rule/aa6089c9cb/))_
- Show Try again on an article while the wallet reports its payment as still being sent. _([costs money](https://www.bitcoinsv.design/guide/rule/08826b6288/))_
- Renew an allowance that has ended without asking the user again. A limit that starts again each month within a live grant is normal, provided the reset date is shown beside what is left. _([costs trust](https://www.bitcoinsv.design/guide/rule/4399f2f0dc/))_
- Describe a refund in the app as a payment being reversed or cancelled. Say "We've sent you 20 sats back". _([costs trust](https://www.bitcoinsv.design/guide/rule/fc4fae7aaf/))_
- Round a per-use price up to something tidy because the real number looks odd. The real number is the product's best argument. _([rule](https://www.bitcoinsv.design/guide/rule/c438b741e1/))_
- Show a notification per payment. The first one is informative, the fortieth is why the feature gets switched off. _([rule](https://www.bitcoinsv.design/guide/rule/e84ab93e7c/))_

## Patterns

_Design guidance in each pattern comes from the guide page it cites. Method names, arguments and code are implementation notes checked against `@bsv/sdk` 4.0.0._

### 1. Take payment inside the request (HTTP 402)

**When:** An app or API charges per use.

**How:**

1. The client requests the resource. The server replies **402 Payment Required** with the price in satoshis.
2. The user's wallet builds a payment to the server and the client repeats the request with it attached. The server checks the payment and returns the resource. No account, card or API key.
3. In `@bsv/sdk`, `AuthFetch` does the retry for you: it reads the server's `x-bsv-payment-satoshis-required` header, pays from the wallet, and repeats the request.
4. Pair it with an allowance (see bsv-wallet-connection) so each payment fits without a prompt.

```ts
import { AuthFetch, WalletClient } from "@bsv/sdk";

const wallet = new WalletClient("auto", "example.com");
const client = new AuthFetch(wallet);
const response = await client.fetch("https://api.example.com/article/42");
```

**Fallback:** The wallet has no allowance for this app: ask once, in consequence language, before the first paid request rather than failing it.

_Source: [Payments](https://www.bitcoinsv.design/guide/how-it-works/payments/)_

### 2. Put the cost on the thing, and the total where it is spent

**When:** Any surface where paid use happens.

**How:**

1. Put the price on the link or the endpoint: "20 sats" on the article, "5 sats per request" on the API. Never round it up to look tidy.
2. Lead with local currency for anything a person chooses to buy, and with satoshis for anything software decides or enforces, such as an allowance or what is left of it.
3. Show the running total against the allowance wherever the spending happens, not only in settings, with a stop control beside it.
4. In activity, group by what the user was doing: "The Satoshi Vision, 14 articles, 280 sats", opening into the individual payments. No notification per payment.

_Source: [Charging per use](https://www.bitcoinsv.design/guide/patterns/charging-per-use/)_

### 3. Stop instantly, and fail towards not charging

**When:** The user stops, the allowance runs out, or a payment fails.

**How:**

1. Stopping is one action with no confirmation, effective immediately, and confirmed afterwards: "Stopped. You spent 340 sats."
2. Offer a ceiling before starting: "Stop at 5,000 sats". A limit that resets each period within a live grant is fine, but never renew a grant that has ended without asking; one that quietly renews is a subscription nobody took out.
3. Decide what happens when one payment in a hundred fails (retry, skip or stop) and tell the user which, once.
4. When in doubt, do not charge. A user who got something free will forgive you; one charged twice will not.

_Source: [Charging per use](https://www.bitcoinsv.design/guide/patterns/charging-per-use/)_

## All the rules

`references/rules.md`: 46 rules from 5 pages, 17 of them costly, most costly first.
Every rule in the guide, most costly first: https://www.bitcoinsv.design/api/rules.json

## Implementation resources

- **[@bsv/sdk](https://bsv-blockchain.github.io/ts-sdk/)**: The TypeScript SDK: `WalletClient` for every BRC-100 call, `AuthFetch` for HTTP 402, transactions, scripts and BEEF. Source at github.com/bsv-blockchain/ts-sdk.
- **[Wallet Toolbox](https://github.com/bsv-blockchain/wallet-toolbox)**: The wallet side of the interface: storage, signing and `WalletPermissionsManager`. Start here if you are building a wallet rather than an app.
- **[BRCs](https://github.com/bsv-blockchain/BRCs)**: Every proposal the skills cite, by number.

---

_Generated from https://www.bitcoinsv.design/, Open BSV License Version 6. Rules are extracted from the guide's pages and cannot be out of date about what it says; the patterns may still need updating._