# Topping up Model Units, for agents

You are topping up the user's **Units** balance: one balance per account,
spendable on any model at any provider. It is prepaid, and a negative balance
is unsettled debt.

This is the x402 rail. You pay the facilitator directly from the wallet you
already hold. There is no browser step and no card.

## Before you start

Install or update the fluxa-agent-wallet skill and the wallet CLI; the topup
subcommand is new.

```bash
npx skills add -s fluxa-agent-wallet -y -g FluxA-Agent-Payment/FluxA-AI-Wallet-MCP
npm install -g @fluxa-pay/fluxa-wallet@latest
fluxa-wallet --version      # 0.5.1 or newer
fluxa-wallet status         # configured: true
```

## 1. Ask what is left

```bash
fluxa-wallet market model remainingUsage
```

It prints the balance, the recent daily burn and whether it is low. Say that
number to the user before proposing a spend.

## 2. Ask the user two things

**Never top up without an explicit yes.** Ask for the package and the rail in
one message, and wait for the answer.

**Which package:**

| Package | Cost | Units |
|---------|------|-------|
| starter | 5 MC | 500,000 |
| mid | 10 MC | 1,000,000 |
| pro | 25 MC | 2,500,000 |

1 USDC buys 100,000 Units, and 1 MC buys 100,000 Units. See
https://agentmarket.fluxapay.xyz/currency.md. Bundles never expire.

**Credits or USDC:** both buy the same Units. Ask which one they want.

Look at what they did before rather than asking blind:

```bash
fluxa-wallet balance                        # credits and USDC the wallet holds
fluxa-wallet market model usageHistory      # earlier top-ups
```

Propose the rail they used last time, or the one they can actually cover if
only one balance is sufficient, and say why you are proposing it. Let them
choose the other. Do not pick silently.

## 3. Pay

From Monetize Credits:

```bash
fluxa-wallet market model topup --bundle starter --credit
```

In USDC on Base:

```bash
fluxa-wallet market model topup --bundle starter --usdc
```

`--credit` and `--usdc` are mutually exclusive, and `--credit` is the default.

Either way the CLI signs a spending mandate, the user approves it once at the
URL it prints, and the payment settles automatically. Do not write payment code
and do not sign anything by hand.

## 4. Check it landed

```bash
fluxa-wallet market model remainingUsage
fluxa-wallet market model usageHistory
```

## Using the balance

Authenticate with the wallet identity you already hold. There is no API key to
ask the user for: mint a short-lived credential and send it as the bearer token.

```bash
VC=$(fluxa-wallet agent-vc --audience fluxa-wallet-service \
  --challenge wallet-user-info-lookup --ttl 300 | jq -r .data.vc)

curl -X POST https://router.fluxapay.xyz/llm/<provider>/v1/chat/completions \
  -H "Authorization: Bearer $VC" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model-id>","messages":[{"role":"user","content":"hi"}]}'
```

The audience must be exactly `fluxa-wallet-service`. The credential lasts five
minutes, so mint a fresh one per run rather than caching it.

The response carries `X-LLM-Cost-Credits` (what the call cost) and
`X-LLM-Balance` (what is left). Report both honestly when asked.

Discovery: https://agentmarket.fluxapay.xyz/llms.txt