Skip to main content
Read the spending budget 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 under budget; 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 message as 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 = capCents while within cap; transactionCount is how many payments were made and maxTransactions the limit (null when 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 in wallet_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; message then 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; null means it could not be read, and message says that too.
  • sessionChannels, when present, is the history behind that: each payment channel this budget used, newest first, with its merchant, status, what was deposited (deposit, or depositAtomic in raw units when symbol is null), what came back (refund, null until the channel has closed and the refund is confirmed) and openedAt / 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. sharedWithOtherBudgets means the wallet’s channel also served another budget, and depositConfirmed: false means the open isn’t confirmed, so the deposit may not have landed. sessionChannelsTruncated: true means only the newest channels are listed and older ones exist. An empty list means none was used; null means it could not be read; absent means this reader can’t see them, as with a member spending an organization’s budget.
  • With no delegationId this reads the budget pay_service would use, which 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.

Nevermined credits

With a personal API key, the result also carries your Nevermined credits, with or without a subscription:
  • credits is your balance as GET /api/v1/credits/balance reports it: spendable is what can pay a call now, and parts lists the credits left by kind (welcome for free credits, allowance for a subscription’s monthly allowance, topup for top-up credits) and expiry, with any freeze. creditsMessage says the same in a sentence. Relay it as it stands.
  • subscription is your Nevermined Subscription, with subscriptionMessage to relay as it stands. It’s { "subscribed": false } when you don’t subscribe. A subscriber sees the plan, the reset date and creditsLeft. For a subscriber, subscriptionMessage names the monthly allowance and when it resets, then describes your credits part by part, as creditsMessage does. 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.spendable is what pay_service can spend now with a personal API key; a call made in an organization never spends them. subscription.creditsLeft counts your whole balance, free credits included. subscription.spendable is about the subscription only: false unless it’s active or trialing and not suspended by a card dispute. While it’s overdue (past_due or unpaid), only its allowance is frozen.
  • credits is null when your balance couldn’t be read this time, and creditsMessage says so. That never means zero.
  • An OAuth connection that you allowed to spend your credits gets subscription but no credits: 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 drops nextTool: "setup_delegation" when your credits can pay: pay_service uses them by default. An OAuth connection gets no credits, so without a subscription that can pay it keeps nextTool: "setup_delegation", even when pay_service can spend its credits.

Top-up credits

Credits from top-up packs are a topup 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):