commerce grant). Always read get_service first and pass its requestShape.endpoints[].payServiceArgs through as-is — it carries slug / path / method, and for a verified endpoint a pre-filled body (and sometimes search / headers); don’t drop those and rebuild your own. Where an example filled a path parameter, path already holds that example’s entity (not a {placeholder}) — swap in the entity you want rather than looking for a placeholder to replace.
Auth: key / grant · Charges: real funds
Arguments
A bare slug reaches the service’s base URL. For a multi-endpoint API that is a 404, not a purchase — pass the endpoint’s
path. Only a single-endpoint service is callable by slug alone.Returns
The vendor’s response plus the payment record. A paid result also carriesdelegationId and budget (the spending budget after this call):
paid: truewith a non-2xxupstreamStatusmay still have cost the merchant price.- The
requestblock rides on every result that resolved the endpoint (already_paid,payment_failed, …), not only the paid one. budget: nullmeans it couldn’t be read this time — not that it’s zero; callget_budget.payable: false(withprotocol,priceLabel,network,note; never the upstream URL) means the service isn’t on a payable rail — nothing charged.
When the body is not inlined
A paid body that is binary (audio, images, PDFs), or whose JSON form is larger than the server’s inline limit (32 KiB by default), comes asresponseOmitted in place of response and bodyEncoding, once the Router is confirmed to have kept the result; if that cannot be confirmed, the body stays inline. It does not mean the body is empty:
reason is binary or too_large, and sizeBytes is the size of the body itself (decoded, for binary). A resource_link content block pointing at resourceUri follows the JSON. Getting the body charges nothing; never pay again to get it:
- Download
contentUrlwith your API key:GET …/result/contentanswers the bytes, with the service’s status inX-Upstream-Status. - Read
resourceUri(MCPresources/read), with the credential you send this server, so it also serves an OAuth connection. Claude Code saves a resource blob it reads to a file and puts only a one-line pointer in the context. - As a last resort, call
get_payment_resultwith thispaymentIdandinline: true, which returns the body in the tool result at its full size.
bodyOmitted from get_payment_result and from an autoPay route_by_intent.
Outcomes and refusals
Pay with subscription credits
With Nevermined credits — free credits from sign-up, top-up packs, or a Nevermined Subscription’s monthly allowance —pay_service can pay with credits instead of your delegation: Nevermined pays the merchant, credits follow the service’s live price with a 1-credit minimum, and the credits come back if the service doesn’t answer with a 2xx. Credits are spent with a personal API key, or through an OAuth connection you allowed to spend them; any other OAuth connection pays from its grant.
The funding argument decides what pays:
delegationId, quoteId and maxTotalCents only mean something to a delegation, so passing one with funding: "subscription" is refused (invalid_arguments, with the offending fields).
For a subscriber in good standing, the default doesn’t look at how many credits are left or at the merchant’s live price — those are checked when the call is made, and a refusal for them is not moved to your delegation (see the note below). Without a subscription in good standing, the quote also checks that your credits cover this call, unless an automatic top-up would cover it. When your credits were refused for this call up front (no rate, nothing that can pay it, credits frozen by a card dispute or an overdue renewal), the delegation-funded result says so: funding: "delegation", fundingReason: "subscription_refused", the API’s fundingCode and a fundingNote (or fundingReason: "delegation_arguments" when you passed a delegation-only argument). If credits aren’t available to you at all — an OAuth connection you didn’t allow to spend them, for example — the result carries no funding fields. And if the subscription’s answer couldn’t be read, the call is refused with funding_undetermined rather than paid from your delegation.
A credits call answers with funding: "subscription", the credits it cost and where they stand — and no budget or delegationId, since no delegation was charged:
creditsStatusisCommitted(spent),Reserved(still running, or marked for refund) orRefunded(returned). The top-levelcreditsChargedandcreditsStatusarenullwhenpaidisfalse, or when the ledger couldn’t be read at answer time (paymentthen omits them) — read the payment withlist_paymentslater.creditsLeftis your credits after the call, as a digit string.nullmeans it couldn’t be read, not zero.- A
pendinganswer works as for any paid call: pollget_payment_result. The credits stay reserved until the service answers.
When a call charges a top-up pack
With top-ups on and a personal API key, a credits call that runs out of credits charges one pack to the human’s saved card and goes ahead (a call made through an OAuth connection never charges a pack on its own — an OAuth-connected agent usestop_up_credits instead). Its result then also carries topUp — the credits the pack added and its price in US dollars, before tax — and topUpMessage, a sentence to relay:
- Relay
topUpMessageto the human. Their card was charged, and they should hear it from you, not only from the receipt email. - A
pendinganswer carries them too. - When the pack the Router reported can’t be read,
topUpMessagecomes alone, withouttopUp, saying the call may have charged a pack. Relay that as well. - Only a call that goes ahead carries
topUp. A call refused after its pack was charged says so asinsufficient_creditsorcredits_frozenwithtopUps: "bought", the pack’spurchaseIdand atopUpMessageto relay; any other refusal then says nothing about the pack. The human’s Packs list in the Nevermined App and the receipt email are the record.
Refusals when paying with credits
These spend and reserve no credits. They charge nothing either — except that with top-ups on, aninsufficient_credits with topUps: "pending", or any refusal with topUps: "bought", can follow a pack charged to the human’s card: tell them. A refusal with topUps: "bought" carries a topUpMessage saying so — relay it. Each carries funding: "subscription", the API’s code, retryable and message, and an alternative saying how to pay the same call from your delegation instead.
With
funding omitted, a call whose credits a dispute or an overdue renewal froze before it was quoted is paid from your delegation instead, with fundingCode saying why.
With funding omitted, { "error": "funding_undetermined", "retryable": true } means what would pay this call couldn’t be decided — nothing was charged; retry.
Other failures of a credits call use the usual outcomes above — payment_failed, payment_indeterminate, already_paid, pending — with funding: "subscription": read code and retryable.
A credits call refused at the call because too few credits are left (
insufficient_credits) is not moved to your delegation on its own — starting to spend money when your credits run out is your decision. Retry with funding: "delegation" if you want the delegation to pay. To have a pack of credits charged automatically instead, the human turns on top-ups in the Nevermined App; an assistant can’t turn them on.Try it
Ask your assistant:
Pay openweather-mpp for the current weather in Lisbon and show me the response.
Call it directly (⚠️ charges real funds — rehearse on https://mcp.sandbox.nevermined.app/mcp first):