wallet_balance

io.github.nevermined-io/catalog · Verify this server

Read the balances of YOUR OWN PERSONAL wallet — the funding source the crypto rails PULL from when pay_service charges a PERSONAL delegation. It answers `how much do I have, and on which chain`. Reading costs nothing and charges nothing. WHAT IT DOES NOT COVER, so you do not mis-diagnose: a delegation backed by an ORGANIZATION wallet is paid from that wallet, not this one; and a CARD delegation has no wallet at all — there `BCK.ROUTER.0009` is the card ISSUER declining, with nothing to top up, so this tool does not apply and the answer is a different card. BY RAIL: on MPP the wallet is checked BEFORE anything is signed, and the `BCK.ROUTER.0009` you get back already names the wallet and the chain — what it never says is HOW MUCH is there, which is what this tool supplies. On x402 there is NO balance pre-check and `BCK.ROUTER.0009` is never raised: the credential is minted, budget is reserved, and a short wallet only surfaces when the merchant's on-chain transfer fails — by which point your budget is already committed, and the reserve comes back only once the reconciler has seen the authorization expire unconsumed. So on that rail read the balance BEFORE you pay, not after. By default this reports EVERY network this deployment settles on, and you must read the one the merchant quoted: a healthy balance on one chain says NOTHING about the other, and most services settle on only one of them. Pass `network` (a chain id) to read a single chain. A token whose `atomic`/`formatted` is `null` was NOT READ (the on-chain read failed) — that is not a zero balance, and reporting it as empty is wrong; a chain that could not be read at all comes back as an entry with `error` instead of `balances`. This tool diagnoses and fixes nothing: there is no on-ramp and you cannot top your own wallet up, so a genuine shortfall is a stop condition — report the network and the amount to your human, and do not retry the payment. Each entry with `balances` also carries `lockedInChannels` when the API reports it, per token (`atomic` in the token's smallest unit, `formatted`, `symbol`): money your payer wallet (the one the Router signs MPP payments with, which is this wallet once your account is migrated) has deposited into payment channels with merchants that charge per call over an MPP session, held in the channel's escrow. It is NOT part of `balances` and it is NOT spent: it is still the human's. It can pay further calls only to the merchant holding that channel, never anyone else, and what is unused comes back to that wallet when the channel closes, after 15 minutes without use. Report it beside the balance, never as spending, and never count it toward paying any other merchant. Here a null `symbol`/`decimals`/`formatted` means a token Nevermined does not recognise, NOT an unread amount: report `atomic` as raw units of `token`. An empty list means nothing is locked; `lockedInChannels: null` means it could not be read, which is not the same as nothing locked. When you have a Nevermined Subscription the result also carries `subscription` (the credits left in your monthly allowance, reset date and plan, as in get_budget): that allowance is not held in this wallet and is not money; subscription calls are paid by Nevermined, not from this wallet. Requires your Nevermined API key on the Authorization header.