Nevermined Catalog

Read your personal subscription balance and get the link the human opens to subscribe or manage their allowance when credits are short. Charges nothing and never starts a paid checkout. `topUpAvailable` says whether the human can buy a pack of never-expiring credits from the dashboard (`dashboardUrl`) now, which also switches on automatic top-ups or resumes paused ones; the message mentions top-ups only when it is true. An existing subscriber gets the dashboard and reset date. After the human finishes checkout, use get_budget to verify the credits, then retry pay_service. OAuth commerce connections must explicitly grant Nevermined credits.

Takes no parameters.

List the categories of paid services in the Nevermined Agent Services Catalog, with a count per category. Discovery only; no payment.

Takes no parameters.

Search the Nevermined Agent Services Catalog for paid services, ranked by ARD HYBRID relevance — semantic (meaning) matches merged with lexical (keyword) matches, most relevant first — falling back to pure lexical when the embedding provider is unavailable. Each result includes a closed matchReason, a per-item rankingSource, and one scale-specific score. A query is required; the other filters are optional. Returns matching listings (vendor, protocol, headlinePriceLabel, endpoints). headlinePriceLabel is derived from endpoint prices; "from" means prices vary. Budget against the selected endpoint price and quote before paying. Only the first page is returned: the `pageToken` in the result cannot be passed back to this tool, so to see other matches narrow the query or filters, or raise `pageSize` (up to 100). Discovery only; no payment. To have the platform PICK (and optionally pay) the single best service for a need instead of choosing yourself, use route_by_intent.

Fetch one catalog service by slug with metadata and a `requestShape` block. Read the endpoint's `payServiceArgs` before `pay_service`, replacing every `pathParams` placeholder. A checked invoke contract may include `invokePath`, `requestExample`, merchant-authored `responseSchema`/`responseExample`, and `exampleEvidence`: `paid-run` records a paid response, `challenge` proves only the request shape, and `docs` is unverified provider documentation. Only `paid-run` and `challenge` examples are pre-filled into `payServiceArgs`; adopt a `docs` example deliberately. Each endpoint also carries `requestExampleQuality`, grading how well it publishes the way to call it (not a callability verdict) — `proven` (a usable example earned against the real endpoint, including a concrete `invokePath` that fills a templated path), `docs` (a usable example from documentation, unverified), `no-input` (takes no request input, callable as-is), or `none` (no stored example — form the request from `requestSchema` if one is published). Merchant response shapes are sanitised, and harvested examples are published only when they validate against their schema. An `endpointCheck` records a dated unpaid failure. An endpoint with `auth: "siwx"` is not paid: it is a follow-up (a job or result poll) that only the wallet which paid an earlier call to the same service can read, so call it with `pay_service` after that call, filling its `pathParams` with the id the paid response returned; the Router signs the wallet challenge and charges nothing. A `requestSchema` is the merchant-declared JSON Schema of its request and is sanitised, not verified. A quote excludes the Router fee, which the budget must also cover. An unknown slug returns an error. Discovery only; no payment. Call `quote_service` for the live fee-inclusive total before paying.

Pay for a catalog service from your spend-capped delegation and return the vendor response. This charges real funds. Paid calls can take several seconds, including payment verification, service work and settlement; longer tasks can take more. Call `get_service` FIRST: its `requestShape.endpoints[]` lists the callable paths with their HTTP method and price, and each `payServiceArgs` is the `slug`/`path`/`method` to pass here, after replacing any `pathParams` placeholder in `path` with a real value. A bare slug reaches the service base URL, which for a multi-endpoint API answers 404 instead of a payment challenge; only a single-endpoint service is called by slug alone. Send the endpoint's `payServiceArgs`: they carry an example only when it is `paid-run` or `challenge`. A `docs` example (and its `invokePath`) is unverified — use it only deliberately, filling any path parameter with the entity you want; otherwise build `body` from the endpoint description or the provider's docs. `method` may be omitted: it is taken from the catalog endpoint matching `path` (POST when the catalog names none) and echoed back under `request`. To accept a live quote, pass its `quoteId` before `expiresAt` with the exact same call arguments; the Router uses that cached challenge and exact fee-inclusive total. Keep `maxTotalCents` as an independent ceiling. Repeating an identical call (same arguments, no `fresh`) charges nothing new: on a deployment running API 1.48 or later it is answered within 24 hours from the first call's stored result, or its `pending` answer; on an older deployment it comes back as `already_paid`. For an ASYNC service, where you submit once and then poll a status endpoint with the same id, set `fresh: true` on every poll INCLUDING THE FIRST: otherwise each 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 (the merch

Price ONE call to a catalog service WITHOUT paying it: it charges nothing, signs nothing and reserves no budget. Pass exactly what you would pass to `pay_service` (the same `slug`, `path`, `method`, `search`, `headers`, `body` and `delegationId`): the Router sends that request to the service unpaid, reads the price it asks for, and returns an opaque `quoteId`, its short `expiresAt`, the rail (`protocol`), the network and merchant amount (`settlement`) and the fee-inclusive total (`fee.capChargedCents`, whole cents rounded up; `fee.capChargedMicros` exact, in 1/10,000 of a cent). Unlike the `quote` on a get_service endpoint (the last merchant price the catalog observed, routing fee excluded), this is priced live for your exact request and includes the fee. Because the request really reaches the service, a service that does not charge for it performs it, so take care quoting a method with side effects; and a quote spends the same per-service rate limit as a payment, so quote once per decision rather than polling. It prices the delegation pay_service would charge (`optionSet: "delegation"`, naming its `delegationId`), or, with no delegation set up, what a personal crypto delegation would select (`optionSet: "deployment"`); in that case `nextTool` is `setup_delegation`: set one up and quote again before paying, since the delegation you create can select a different rail and price. It checks neither your remaining budget nor your wallet balance (see get_budget and wallet_balance). Next step (`nextTool: "pay_service"`): if `fee.capChargedCents` fits what you planned to spend, call `pay_service` before expiry with the same arguments, the quoted `delegationId`, `quoteId`, and `maxTotalCents` set to that figure as a number. The quote id fixes the exact challenge and fee-inclusive total while `maxTotalCents` remains an independent ceiling. `paymentRequired: false` means the service did not ask for payment for this request; `upstreamStatus` is its answer, and a non-2xx usually

Given a plain-language description of what you need, find, and optionally pay in the same call, the single best payable catalog service, so you do not have to pick among listings yourself. Use it instead of search_services when you want the right service for a task rather than a list to browse: it ranks candidates on Nevermined's own relevance and quality signals (deterministic; no model reads the merchant listings), applies a fail-closed payability gate (listed, healthy, moderated, x402/mpp, not flagged unpayable), and returns the winner as `chosen` (with its opaque invoke handle, never a raw host) plus a ranked `shortlist`; every shortlist item carries a closed `matchReason`, `gateReason`, per-item `rankingSource`, and one scale-specific score. With `autoPay:false` (the default) it returns the pick only and charges nothing; the next step is normally `get_service` on `chosen.slug`, then `pay_service` with the endpoint you need. With `autoPay:true` it also pays the winner through the same path as pay_service and returns the upstream call in `result`: `result.status` and `result.body` are the vendor's answer, and `result.paid: true` means a payment was attempted, not that it settled, so read `result.payment.status` (`Settled`, `Issued` or `Failed`). autoPay calls the winner at its base URL plus any `path` you pass, and you only learn the winner from this call, so it suits single-endpoint services; a multi-endpoint winner typically answers 404 at its base URL. autoPay requires `requestId`; an API-key caller must also pass `delegationId`, while an OAuth-connected caller spends from the grant it approved and needs none. Outcomes: no listed, payable match → `{"status":"no_fundable_match"}` (broaden the intent or filters; nothing charged), never a wrong pick; `missing_autopay_fields` (nothing charged); on autoPay, `payment_indeterminate` (check `list_payments`, and retry only with the same `requestId`) and `already_paid` (this `requestId` already carries a payment, see `p

Start the spending-delegation ceremony and return ONE URL for a human to open. Use this when `pay_service` returns `{"error":"no_delegation"}` — it is the way out of that state. It sets up a stablecoin (crypto) delegation that spends from the human's personal wallet, so that wallet also needs funds on the network a service settles on (see `wallet_balance`); it does not enroll a card or create a card delegation. The human sets the currency, spending cap, duration and transaction limit themselves in the browser; you CANNOT set them and must not ask the human to pass them to you. Returns `{"status":"human_action_required","url":…}` — relay the url, wait for the human to confirm, then simply call `pay_service` again. `{"status":"already_active"}` means a usable spending budget is in place — for an OAuth commerce caller it is the grant approved on the consent screen — and nobody needs to do anything: tell the human `message` as it stands (it states the cap, spent, remaining and expiry the API reports, in a voice written to be relayed), then follow `instructions` and call pay_service. The url embeds a short-lived session token, so treat it as sensitive and give it only to the account owner. Other outcomes: `delegation_setup_unavailable` (this deployment cannot run the ceremony) and `delegation_setup_failed` (the session could not be started) produce no URL; `return_url_not_allowed` means drop or fix `returnUrl`; a `human_action_required` answer with `delegationCheck: "failed"` means an existing budget could not be ruled out, so follow its `instructions` and try pay_service first. Requires your Nevermined API key on the Authorization header.

Read the spending budget pay_service spends from: its cap, what has been spent, what remains, how many payments were made (and the limit, if any), and when it expires. Reading costs nothing and charges nothing. Use it whenever the human asks how much is left, or before a run of paid calls. Money is in CENTS: `capCents` is whole cents; `spentCents` and `remainingCents` can carry up to four decimals because the budget is charged per call at 1/10,000 of a cent (e.g. `"1.632"` = 1.632¢), and `spentCents + remainingCents = capCents` while the budget is within its cap. Tell the human `message` as it stands and never substitute a figure of your own: the budget includes routing fees and rounding, so adding up your calls will not match it. With no `delegationId` it reads the budget pay_service would use; that 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. On a deployment that reports it, `spentByDeliveryStatusCents` splits the spend by what each payment delivered (`delivered`, `charged_not_delivered`, `charged_unconfirmed`, `not_charged`, `not_delivered`, `pending`, the `deliveryStatus` values list_payments uses), and `unattributedSpentCents` is spend no payment record itemizes; a non-zero `charged_not_delivered` is what was spent on calls that delivered nothing although the merchant charged (the merchant charge plus any routing fee not given back), so tell the human. `not_delivered` is held for calls the merchant answered with an error: not a confirmed charge; the reserve stays held until reconciliation decides whether the merchant charged after confirmed cancellation or authorization expiry (an older deployment reports it inside `pending`). `lockedInChannels`, when present, is money the wallet this budget pays from has deposited into payment channels with merchants that charge per call (per token, as in wallet_

Buy one credit pack on the card your human enrolled, within the monthly top-up limit they set — no new human approval. This CHARGES the human’s card. Pass `forCallCredits`: the credits the call you are about to make will spend. A pack is charged only when your spendable credits are below that — the recorded consent charges a pack “each time your credits are not enough for a call you make”, so state what that call needs (from a quote or your plan’s per-call cost); when your credits already cover it, nothing is charged (`not_needed`). Pass a `requestId` you choose as an idempotency handle: a NEW value for each top-up you intend, the SAME value only to re-send a call that may not have completed (a retry returns the pack already charged, never a second one). Read `status`: `bought` added credits (`creditsAdded`) — unless `replayed` is true, which means this requestId had already bought one and nothing new was charged (use a new id next time); `pending` means YOUR pack was charged and is awaiting confirmation (read the balance shortly); `busy` means another top-up is already being charged — nothing was charged for THIS request, so check your balance shortly and re-send the SAME requestId only if you still need one; `limit_reached` means this UTC month’s top-up limit is used up (no charge — do not retry until next month); `not_needed` means your credits already cover the call (no charge); `needs_attention` means the card was declined or needs 3-D Secure, a card payment to Nevermined is disputed, a human must finish setting top-ups up, a prior top-up is stuck, or a prior top-up’s outcome is unconfirmed (it may have been charged) — hand the human `operatorUrl`, never try to confirm it yourself, and do not start a new top-up until they act; `disabled` means a human must turn top-ups on first (give them `operatorUrl`); `unavailable` means nothing was charged — retry with a NEW requestId (reusing this one keeps returning the same settled result). `monthlyLimitUsd`/`boughtThisM

Read the result of a paid call, by its `paymentId`. Use it when `pay_service` answered `{"status":"pending"}` (the service was still working when the Router stopped waiting — a payment was attempted, the call keeps running and its outcome is not known yet), or to recover a result whose response you lost. Reading costs nothing and charges nothing. Every answer with a `state` carries `payment.status`. `state: "Pending"` — still running, call again in a few seconds. `state: "Ready"` — `status` is the service's HTTP status and `body` its response (`bodyEncoding` says whether it is parsed JSON, text, or base64). `state: "Failed"` — the call ended without a response; `failureReason` says why. That does not prove nothing was charged, so check `deliveryStatus` in `list_payments` before paying again. `{"status":"not_available"}` — nothing to return: results are kept for 24 hours for the account that paid, and only then. Do NOT call pay_service again to get a pending result: that does not return a new one. Requires your Nevermined API key on the Authorization header.

List your Router payments: the unified ledger across every service and delegation, newest first, at most 1000 records. Each record carries its `id` (the `paymentId` get_payment_result takes), `createdAt`, `status`, `protocol`, `network`, `requestId`, `delegationId` and `amount` in the asset's smallest unit (see `assetDecimals`), not in cents. Each row also carries `deliveryStatus`: `delivered` (request settled), `charged_not_delivered` (request failed and the merchant charge was observed), `charged_unconfirmed` (charge observed; delivery unconfirmed), `not_charged` (reconciliation recorded no merchant charge, including unreadable write-offs; not conclusive proof that no money moved), `not_delivered` (the merchant answered with an error, so nothing was delivered, and no charge has been seen: the amount stays reserved until reconciliation decides, after confirmed cancellation or payment authorization expiry, whether the merchant charged; it is not a confirmed charge), or `pending` (charge outcome unknown). Issued + `pending` means the charge outcome is unknown: neither payment nor no charge is established. On SPT and card rails, pending is not proof of no charge; those rows are never decided on chain. `merchantSettlementObservedAt` records an observed merchant charge; null is not, on its own, proof of no charge. Flag both charged states to the user. Each record also carries `fundingSource`, the funding it used: `delegation`, or `subscription` for your Nevermined credits, with or without a subscription. On a `subscription` row, `deliveryStatus` and `merchantSettlementObservedAt` describe what Nevermined paid the merchant, not a charge to you: what the call cost you is `creditsCharged`, and `creditsStatus` says whether that stands (`Committed` spent, `Reserved` held or marked for refund, `Refunded` returned). Do not report a charged state on such a row as a charge to the user. Pass `requestId` to look up the one payment with that id: the answer is then `{"presence":…,"p

Count your Router payment requests: `total` is how many there were in the period (uncapped, unlike list_payments) and `series` is that count per day (`date`, `value`), oldest first. `chargedNotDelivered` is the count of failed payments in the period whose merchant charge reconciliation observed on-chain (a failed payment not yet reconciled is not counted); this is the confirmed failed-and-charged count only. `countsByDeliveryStatus` exposes all six ledger delivery states, including `charged_unconfirmed`, `not_delivered` and `pending`, with zero counts included. The latter two have unknown charge outcomes: do not count them as confirmed charges. Flag both charged buckets and explain unresolved outcomes to the user. These buckets include calls paid with your Nevermined credits, so check `fundingSource` and `creditsStatus` in `list_payments` before telling the user they were charged. This reports numbers of payments, not money: for what has been spent or what is left, and how much of it was charged without delivery, use get_budget, and for amounts per payment use list_payments. Reading costs nothing. Requires your Nevermined API key on the Authorization header.

Read the balances of YOUR OWN PERSONAL wallet — the funding source the crypto rails PULL from when pay_service charges a PERSONAL delegation. It answers `how much do I have, and on which chain`. Reading costs nothing and charges nothing. WHAT IT DOES NOT COVER, so you do not mis-diagnose: a delegation backed by an ORGANIZATION wallet is paid from that wallet, not this one; and a CARD delegation has no wallet at all — there `BCK.ROUTER.0009` is the card ISSUER declining, with nothing to top up, so this tool does not apply and the answer is a different card. BY RAIL: on MPP the wallet is checked BEFORE anything is signed, and the `BCK.ROUTER.0009` you get back already names the wallet and the chain — what it never says is HOW MUCH is there, which is what this tool supplies. On x402 there is NO balance pre-check and `BCK.ROUTER.0009` is never raised: the credential is minted, budget is reserved, and a short wallet only surfaces when the merchant's on-chain transfer fails — by which point your budget is already committed, and the reserve comes back only once the reconciler has seen the authorization expire unconsumed. So on that rail read the balance BEFORE you pay, not after. By default this reports EVERY network this deployment settles on, and you must read the one the merchant quoted: a healthy balance on one chain says NOTHING about the other, and most services settle on only one of them. Pass `network` (a chain id) to read a single chain. A token whose `atomic`/`formatted` is `null` was NOT READ (the on-chain read failed) — that is not a zero balance, and reporting it as empty is wrong; a chain that could not be read at all comes back as an entry with `error` instead of `balances`. This tool diagnoses and fixes nothing: there is no on-ramp and you cannot top your own wallet up, so a genuine shortfall is a stop condition — report the network and the amount to your human, and do not retry the payment. Each entry with `balances` also carries `lockedInChannels` when th