Skip to main content
Pay for a service from your spend-capped delegation and return the vendor’s response. This charges real funds. Needs a credential (API key or OAuth 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 carries delegationId and budget (the spending budget after this call):
  • paid: true with a non-2xx upstreamStatus may still have cost the merchant price.
  • The request block rides on every result that resolved the endpoint (already_paid, payment_failed, …), not only the paid one.
  • budget: null means it couldn’t be read this time — not that it’s zero; call get_budget.
  • payable: false (with protocol, 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 as responseOmitted 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 contentUrl with your API key: GET …/result/content answers the bytes, with the service’s status in X-Upstream-Status.
  • Read resourceUri (MCP resources/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_result with this paymentId and inline: true, which returns the body in the tool result at its full size.
The same object comes as bodyOmitted from get_payment_result and from an autoPay route_by_intent.

Outcomes and refusals

Async services: set fresh: true on every poll, including the first. An async service returns a taskId, then you poll a status endpoint with the same id. Without fresh, every later poll reuses the first poll’s idempotency key and gets the first poll’s stored answer (or already_paid) back, so the status never advances. fresh makes each poll a distinct, separately-billed call. Leave fresh off the submit and off any retry of a call whose outcome is unsure.

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:
  • creditsStatus is Committed (spent), Reserved (still running, or marked for refund) or Refunded (returned). The top-level creditsCharged and creditsStatus are null when paid is false, or when the ledger couldn’t be read at answer time (payment then omits them) — read the payment with list_payments later.
  • creditsLeft is your credits after the call, as a digit string. null means it couldn’t be read, not zero.
  • A pending answer works as for any paid call: poll get_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 uses top_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 topUpMessage to the human. Their card was charged, and they should hear it from you, not only from the receipt email.
  • A pending answer carries them too.
  • When the pack the Router reported can’t be read, topUpMessage comes alone, without topUp, 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 as insufficient_credits or credits_frozen with topUps: "bought", the pack’s purchaseId and a topUpMessage to 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, an insufficient_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):