Skip to main content
Glama
Sign In

Nevermined Catalog

by io.github.nevermined-io
OverviewDiscussionsAdmin

List payments

list_payments
Read-only

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":…,"payments":[…]}, it ignores the other filters and the 1000-record limit, and presence: "absent" means no payment carries that id. Use this tool to reconcile an uncertain payment or find a paymentId; it does not return service responses (use get_payment_result) or the remaining budget (use get_budget, whose figures include fees and rounding). Reading costs nothing. Requires your Nevermined API key on the Authorization header.

Input Schema

NameRequiredDescriptionDefault
toNoISO-8601 upper bound on `createdAt`, inclusive. An unparseable value is an error.
fromNoISO-8601 lower bound on `createdAt`, inclusive. An unparseable value is an error.
requestIdNoThe `requestId` a pay_service or route_by_intent result gave you, matched exactly. Finds that one payment wherever it sits in the ledger; the other filters are ignored.
delegationIdNoOnly payments charged to this delegation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / requestId
      Added value: +{
+  "description": "The `requestId` a pay_service or route_by_intent result gave you, matched exactly. Finds that one payment wherever it sits in the ledger; the other filters are ignored.",
+  "minLength": 1,
+  "type": "string"
+}
  2. Changed1 schema field changed
    • removedInput schema / additionalProperties
      Removed value: -false
  3. First observed

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond readOnlyHint=true it adds cost ('Reading costs nothing'), the auth requirement ('Nevermined API key on the Authorization header'), the 1000-record cap, and how requestId bypasses filters and the limit. It also warns about interpretation pitfalls, e.g. that 'not_charged' is not conclusive proof no money moved and that subscription rows are not charges to the user — context annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is well front-loaded, but the description then runs into a long, dense enumeration of deliveryStatus and creditsStatus values, plus nested caveats, that is hard to scan and partly duplicates schema-documented field names. It is justified by the absence of an output schema, yet the presentation is not tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the record fields, status enums, and the requestId response shape must be documented here, and they are. Authorization, limits, cost, and response-shape changes are all covered, leaving nothing an agent needs in order to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: requestId yields a different response envelope with a 'presence' field and 'absent' semantics, and it overrides the other filters and limit. The from/to and delegationId semantics are left to the schema, which is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource plus scope: 'List your Router payments: the unified ledger across every service and delegation, newest first, at most 1000 records.' It also explicitly separates itself from get_payment_result and get_budget in the closing sentences.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States when to use it ('reconcile an uncertain payment or find a paymentId') and when not to, naming the alternatives for service responses (get_payment_result) and budget (get_budget). The requestId single-lookup mode is called out as a distinct use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Nevermined Catalog toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources