# Pay for runs from your wallet

> Fund a Synapse or Locus budget from your wallet's USDC instead of credits, and see each charge collected with its transaction.

Section: Synapse and Locus. Web page: https://docs.katara.com/products/wallet-budgets/

A budget can be paid with credits or from your wallet. Paid from the wallet,
it holds nothing: your USDC stays in your wallet, and what your runs spend is
collected from it in batches through the allowance your wallet already gives
Katara for chat and API use. Every collection is a transaction you can look up.

The wallet is your own smart account on the environment's network. A Live
budget pays in USDC on Avalanche C-Chain; a Test budget pays in the Test
network's USDC. Simulation budgets never move money, so they are not paid from
a wallet.

Paying from a wallet does not change what a run can do or where it runs.
Every grant, approval, policy and limit applies as it does for a credit
budget, and runs use Katara's own models whatever pays for them; Katara
Community is never used for agent runs.

## Fund a budget from the wallet

In the portal, open **Locus → Budgets & Grants → Fund a Budget**, choose the
usage, and set **Pay with** to **Wallet (USDC)**. The total and the category
caps are entered in USDC. The review shows the terms you consent to before
anything is created.

Through the API, create the payer consent with `funding_source` set to
`wallet` and a limit in USDC base units, six decimals, named by chain and
token:

```json
{
  "usage_class": "test_compute",
  "funding_source": "wallet",
  "limit": { "ledger_kind": "testnet", "asset": "USDC_ATOMIC", "scale": 6, "amount": "5000000",
             "chain_id": 43113, "token": "0xfed854555faeeca02acdb3fed90b0cd4048d3f45" },
  "expires_at": "2026-12-01T00:00:00Z"
}
```

Then fund the budget against that consent with `fundBudget` /
`fund_budget`, in the same unit. Its purpose caps are USDC base units too.
`ledger_kind` is `real` for USDC on Avalanche C-Chain and `testnet` on Fuji.

Funding checks your wallet. Its USDC balance and the allowance it gives Katara
must cover this budget's maximum, everything your other open wallet budgets
can still charge, and anything the wallet already owes. Nothing is moved when
a budget is funded, and closing a budget gives back what it could still have
charged.

A wallet budget reads like any other, with a `funding` object naming the
wallet, its network and whose wallet it is, and with every amount in USDC.
A budget without `funding` is paid with credits.

## When the wallet is charged

Each model call, tool action, sandbox step and evaluation case is charged to
the budget as it happens, rounded down to a whole USDC base unit. The wallet
owes those charges until they are collected. A collection takes everything the
wallet owes, across all the runs and budgets it pays for, in one transaction:

- when the wallet owes 0.50 USDC,
- five minutes after the oldest charge it owes,
- or when a run ends, if the wallet owes at least 0.10 USDC.

Smaller amounts left at the end of a run wait for the next collection, so many
short runs do not each cost a transaction.

The 0.50 USDC is also the most a wallet may owe before a run is refused. A run
on a wallet budget is refused while the wallet owes that much, and starts again
once the collection lands, usually within a minute.

## Read what a run paid

`getRunCharges` / `run_charges` for a run paid from a wallet carries a
`wallet` object. Each entry in `batches` is one collection that included this
run's charges: the run's share, the collection's total, its state and, once
it is paid, the transaction hash and when it was paid. A collection can carry
other runs' charges from the same wallet, which is why both amounts are given.
Charges not yet collected are listed with the state `unbatched`.

The run page in the portal shows the same table, with each transaction linked
to the network's explorer.

## When a collection fails

A collection can fail if the wallet no longer holds the USDC or the allowance
was lowered. When it does:

- every run the wallet pays for is stopped and ends with the reason
  `insufficient_funds`. Its work, results and charges are kept.
- new runs, new charges and new wallet budgets are refused with
  `wallet_payment_failed` until the collection is paid.
- the collection is tried again, under a new transaction, once the wallet can
  cover it. Add USDC or raise the allowance and it is collected within a few
  minutes.

Katara never holds your USDC. A collection pays exactly what the wallet owes,
straight from the wallet to Katara.

## Schedules and event sources

A [schedule](https://docs.katara.com/products/schedules.txt) or an [event source](https://docs.katara.com/products/event-sources.txt)
starts runs on the budget its run request names, so it pays the way that
budget pays: credits or the wallet. Each run it starts is admitted, checked and
charged like one started by hand. Paying a single run with an x402
authorization does not apply to scheduled or event-triggered runs.

## Refusals

| HTTP | code | Meaning |
|---|---|---|
| 409 | `wallet_required` | You have no wallet on this environment's network. Set it up in the portal first. |
| 409 | `wallet_insufficient_funds` | The wallet's balance and allowance do not cover the budget's maximum with your other wallet budgets and what it owes. |
| 409 | `wallet_unpaid_limit` | The wallet owes 0.50 USDC and its collection has not landed yet. Start the run again shortly. |
| 409 | `wallet_payment_failed` | A collection from the wallet failed and is unpaid. |
| 503 | `wallet_unavailable` | The wallet could not be checked. Nothing was charged; try again or pay with credits. |