pay_service draws on: its cap, what’s been spent, what remains, how many payments were made (and the limit, if any), and when it expires. Reading charges nothing. Use it whenever the human asks how much is left, or before a run of paid calls. Needs a credential.
Auth: key / grant · Charges: nothing
Arguments
Returns
The figures are nested underbudget; delegationId, message, and instructions sit alongside it. Money is in cents: capCents is whole cents; spentCents and remainingCents can carry up to four decimals (charged per call at 1/10,000 of a cent, e.g. "1.632" = 1.632¢):
- Relay
messageas it stands — it is written to be read to the human, and because the figures include routing fees and rounding, never substitute a figure of your own. - Inside
budget:spentCents + remainingCents = capCentswhile within cap;transactionCountis how many payments were made andmaxTransactionsthe limit (nullwhen there is none). lockedInChannels, when present, is money the wallet this budget pays from has deposited into payment channels with merchants that charge per call over an MPP session, per token (same shape as inwallet_balance). 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;messagethen says so. It is that wallet’s total, not a figure of this budget’s own: every budget paying from the same wallet reports the same channels. An empty list means nothing is locked;nullmeans it could not be read, andmessagesays that too.sessionChannels, when present, is the history behind that: each payment channel this budget used, newest first, with itsmerchant,status, what was deposited (deposit, ordepositAtomicin raw units whensymbolis null), what came back (refund, null until the channel has closed and the refund is confirmed) andopenedAt/closedAt. It explains money leaving the wallet and coming back when no payment shows it, because a payment record carries one call’s price, never the deposit.sharedWithOtherBudgetsmeans the wallet’s channel also served another budget, anddepositConfirmed: falsemeans the open isn’t confirmed, so the deposit may not have landed.sessionChannelsTruncated: truemeans only the newest channels are listed and older ones exist. An empty list means none was used;nullmeans it could not be read; absent means this reader can’t see them, as with a member spending an organization’s budget.- With no
delegationIdthis reads the budgetpay_servicewould use, which only includes budgets that can still pay. So{ "status": "no_active_delegation" }also covers a budget that ran out or expired — pass thedelegationIdfrom an earlierpay_serviceresult to read that one anyway.
Nevermined credits
With a personal API key, the result also carries your Nevermined credits, with or without a subscription:creditsis your balance asGET /api/v1/credits/balancereports it:spendableis what can pay a call now, andpartslists the credits left by kind (welcomefor free credits,allowancefor a subscription’s monthly allowance,topupfor top-up credits) and expiry, with any freeze.creditsMessagesays the same in a sentence. Relay it as it stands.subscriptionis your Nevermined Subscription, withsubscriptionMessageto relay as it stands. It’s{ "subscribed": false }when you don’t subscribe. A subscriber sees the plan, the reset date andcreditsLeft. For a subscriber,subscriptionMessagenames the monthly allowance and when it resets, then describes your credits part by part, ascreditsMessagedoes. What it says about credits not carrying over, or about the subscription ending after a cancellation, is about the allowance only. When your balance couldn’t be read, it gives one total instead, free and top-up credits included:
- Don’t count credits yourself.
credits.spendableis whatpay_servicecan spend now with a personal API key; a call made in an organization never spends them.subscription.creditsLeftcounts your whole balance, free credits included.subscription.spendableis about the subscription only:falseunless it’sactiveortrialingand not suspended by a card dispute. While it’s overdue (past_dueorunpaid), only its allowance is frozen. creditsisnullwhen your balance couldn’t be read this time, andcreditsMessagesays so. That never means zero.- An OAuth connection that you allowed to spend your credits gets
subscriptionbut nocredits: that balance takes a personal API key. Any other OAuth connection gets neither. Both are also absent when the subscription isn’t available to you or when it couldn’t be read this time. Absent never means zero. - With no delegation,
status: "no_active_delegation"still carries these fields, and dropsnextTool: "setup_delegation"when your credits can pay:pay_serviceuses them by default. An OAuth connection gets nocredits, so without a subscription that can pay it keepsnextTool: "setup_delegation", even whenpay_servicecan spend its credits.
Top-up credits
Credits from top-up packs are atopup part that never expires (expiresAt: null), listed last because they’re spent last, and creditsMessage says so:
get_budget doesn’t report the top-up settings: credits carries no topups block, so it says nothing about whether top-ups are on, the monthly limit or a pause. The human sees those in the Nevermined App’s Top-ups panel; with a personal API key, topups on GET /api/v1/credits/balance has them too. When a call that goes ahead charges a pack, pay_service says so.
Try it
Ask your assistant:How much of my spending budget is left?Call it directly (charges nothing):