Check Your Credits (Buyer)

Have an AI agent report your Nevermined buyer status — credits remaining on each plan, active delegations, and remaining spending budgets — so it can top up before running out.

An agent that pays for services should know where it stands: how many credits are left on each plan, and how much budget remains on its delegations. This flow pulls that status over the REST API so the agent can warn you — or top up — before it runs dry mid-task.

Useful for

• A pre-flight check before a run: does the agent have enough credits and delegation budget to finish?
• A “what do I have” report across every plan you hold and every delegation you’ve granted.
• Top-up triggers: detect when a balance or budget is low and act before it hits zero.

Try it yourself

You are my autonomous payments agent. Use the Nevermined `nevermined-payments` skill (https://github.com/nevermined-io/docs/tree/main/skills/nevermined-payments) (Track A, sections A2 and A5) and my NVM_API_KEY. Base URL: https://api.sandbox.nevermined.app/api/v1. Authenticate every call with `Authorization: Bearer $NVM_API_KEY`. Give me a buyer-account status report for sandbox:

1) PAYMENT METHODS — GET /payment-methods. List each method's type (card vs crypto_wallet/stablecoin), brand+last4, provider, and status. Note that `status` is capitalized (e.g. "Active", "Revoked"). Tell me which are active and usable, and call out any revoked one (it cannot back a delegation).

2) DELEGATIONS — GET /delegation. For each, report spendingLimitCents, amountSpentCents, remainingBudgetCents, expiresAt, and status, formatting the cents fields (they come back as STRINGS) as dollars. Flag a delegation if status != "Active", OR remainingBudgetCents is at/below 20% of spendingLimitCents, OR it expires within 48 hours. Report `status` verbatim — note that a delegation can show "Exhausted" even when amountSpent is 0 (it just means expired-and-closed), so describe what the API says rather than guessing the cause. If a delegation has charges, you may inspect them via GET /delegation/{id}/transactions.

3) PLANS I HOLD + CREDIT BALANCE — there is NO endpoint that lists the plans a buyer has purchased. (GET /protocol/plans only returns plans I AUTHORED as a seller, so it will NOT surface plans I merely bought — don't rely on it to find my purchases.) So you need the plan ids to check: use the ones I give you, the ids I retained from past purchases, or the plans advertised in the agentic-instructions.md / llms.txt of any org I've bought from. For EACH such plan id, call GET /protocol/plans/{planId}/balance/{myAddress} — myAddress is the `id` of my erc4337/crypto_wallet payment method from step 1 (it covers both card- and crypto-bought plans) — and report planName, planType, balance (remaining credits), and isSubscriber (true = I hold it). Flag any held plan with a low balance (under 50 credits). If you have no plan ids to check, say so plainly rather than reporting "no plans held".

Then give me a short "action needed" section: anything expired/exhausted/revoked/low, and exactly what I'd do to top up — to restore spending, create a fresh delegation via POST /delegation/create (provider "erc4337" for crypto, or "stripe" with providerPaymentMethodId = my active card's id for card); to add plan credits, run the x402 buy+settle flow (skill A4) against the plan id using a live delegation. Keep all secrets masked in your output.

How it works

All three checks are simple authenticated GETs.

1. Payment methods

   GET {API_BASE}/payment-methods
   Authorization: Bearer <api-key>
   

   Returns your cards and your stablecoin (erc4337) wallet, each with status. The erc4337 method’s id is your wallet/holder address — you’ll use it as the holder when checking plan balances.

2. Delegations and remaining budget

   GET {API_BASE}/delegation
   Authorization: Bearer <api-key>
   

   Returns { totalResults, page, offset, delegations: [ … ] }, each with spendingLimitCents, amountSpentCents, remainingBudgetCents, status, and expiresAt. (Delegation and transaction lists use totalResults; the plan/agent lists use total — mind the difference if you write one pagination helper for both.) Drill into one delegation’s charges with:

   GET {API_BASE}/delegation/{delegationId}/transactions
   Authorization: Bearer <api-key>
   

   (returns { totalResults, page, offset, transactions: [ … ] }).

3. Credit balance per plan

   For each plan you hold, query your balance with your wallet as the holder:

   REST

   GET {API_BASE}/protocol/plans/{planId}/balance/{yourAddress}
   Authorization: Bearer <api-key>
   

   {yourAddress} is the id of your erc4337 payment method from step 1 (or the userWallet from an embed session). Returns { planName, planType, isSubscriber, balance, pricePerCredit, … } — balance is your remaining credits.

   TypeScript

   const balance = await payments.plans.getPlanBalance(planId)
   console.log(`Credits: ${balance.balance}`) // bigint
   

   Python

   balance = payments.plans.get_plan_balance(plan_id)
   print(f"Credits: {balance['balance']}")
   

   The receipt from a purchase (creditsRedeemed / remainingBalance, returned by settle or decoded from the payment-response header) is also a live proof of your balance right after a buy.

Related

Buy access

Top up when a balance runs low.

Enroll a card & delegate

Grant a fresh budget when a delegation is spent or expired.

Order Plans

Buy credits upfront for stablecoin plans.