get_budget

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

Read the spending budget pay_service spends from: its cap, what has been spent, what remains, how many payments were made (and the limit, if any), and when it expires. Reading costs nothing and charges nothing. Use it whenever the human asks how much is left, or before a run of paid calls. Money is in CENTS: `capCents` is whole cents; `spentCents` and `remainingCents` can carry up to four decimals because the budget is charged per call at 1/10,000 of a cent (e.g. `"1.632"` = 1.632¢), and `spentCents + remainingCents = capCents` while the budget is within its cap. Tell the human `message` as it stands and never substitute a figure of your own: the budget includes routing fees and rounding, so adding up your calls will not match it. With no `delegationId` it reads the budget pay_service would use; that only includes budgets that can still pay, so `{"status":"no_active_delegation"}` also covers a budget that ran out or expired — pass the `delegationId` from an earlier pay_service result to read that one anyway. On a deployment that reports it, `spentByDeliveryStatusCents` splits the spend by what each payment delivered (`delivered`, `charged_not_delivered`, `charged_unconfirmed`, `not_charged`, `pending`, the `deliveryStatus` values list_payments uses), and `unattributedSpentCents` is spend no payment record itemizes; a non-zero `charged_not_delivered` is what was spent on calls that delivered nothing although the merchant charged (the merchant charge plus any routing fee not given back), so tell the human. `lockedInChannels`, when present, is money the wallet this budget pays from has deposited into payment channels with merchants that charge per call (per token, as in wallet_balance). It is that WALLET's total, shared by every budget paying from it, not a figure of this budget's own: it is NOT spent and NOT charged to this budget, it can pay further calls only to the merchant holding each channel, and what is unused comes back to that wallet when the channel closes, after 15 minutes without use; `message` then says so. An empty list means nothing is locked; `null` means it could not be read, and `message` then says that too. When you have a Nevermined Subscription the result also carries `subscription` (`creditsLeft`, a digit string of credits spendable now; `resetsAt`, when they expire and, unless `cancelAtPeriodEnd`, the next period's are granted; `status`, `suspended` and `plan`) and `subscriptionMessage` to relay as it stands; `subscription.subscribed: false` means none. Never count credits yourself. Requires your Nevermined API key on the Authorization header.