> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Add bead account credit

> Add bead account credit with a durable purchase, pay through an offered method, and recover pending settlement.

Add bead account credit through one persisted prepaid purchase. Amounts are whole cents in the billing currency.

## Start a purchase

Set `TOPUP_CENTS` to your chosen purchase amount. For a human Checkout handoff:

```bash theme={null}
bead topup --amount "$TOPUP_CENTS" --checkout --purchase-file ./bead-purchase.json
```

Open the returned hosted Checkout URL to pay. Use a different private purchase file for each new purchase.

The CLI saves the purchase identity and possession secret before requesting payment. It also saves a separate private delivery key. Keep those files until the outcome is known and retain them for recovery.

## Pay from an agent

```bash theme={null}
bead topup --amount "$TOPUP_CENTS" --purchase-file ./bead-purchase.json
```

An unpaid purchase advertises Payment challenges. Use an authorized MPP wallet to fulfill a challenge the server actually offers. Payment methods depend on the deployment. The CLI reads `BEAD_PAYMENT_AUTHORIZATION` privately from its environment when supplied by your payment integration.

Give a human only the hosted Checkout URL. Keep purchase secrets, payment authorization, and delivery material private.

## Confirm settlement

Repeat the same command with the same amount and purchase file to retrieve the purchase status. A pending payment does not fund work. A Checkout return URL is not proof of settlement.

Only verified settlement adds credit. A first purchase for a new account delivers an encrypted API key; the CLI writes the decrypted key to an adjacent private `.api-key` file. It never prints the key. Set `BEAD_API_KEY_FILE` to that returned file when using the new account.

For an existing authenticated account, the purchase funds that organization. Confirm the account before paying.

```bash theme={null}
bead balance
```

## Recover a lost response

Keep the original purchase file and delivery key, then poll the same purchase. A new purchase can create another payment. If the payment is pending, follow its returned retry guidance.

See [Credit and payment problems](https://docs.bead.run/help/credit.md) and [Automatic credit refill](https://docs.bead.run/platform/auto-refill.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.