Pay for runs from your wallet

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:

{
  "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 or an event source 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.