Nevermined x402 Payments
Monetize agents with per-request payments using the Nevermined x402 payment protocol. Users pay per chat message; agents earn credits.
Concepts
Setup (Admin)
Open the agent detail page and select the Payments tab. Anyone with access to the agent can read it; changing it needs the owner or an admin.
Enter the NVM API Key, Environment (sandbox by default; live, staging_sandbox, staging_live or custom), Agent ID, and Plan ID from Nevermined, and the Credits per Request to charge (default 1; 0 for a time-based plan). Click Save Configuration.
Flip the Enabled toggle to switch payments on; Remove deletes the configuration and disables paid access.
The agent now has a paid chat endpoint, shown as Paid Endpoint on the tab: POST /api/paid/{agent_name}/chat. The Payment Log below lists settled and failed payments.
Payment Flow
Client -> POST /api/paid/{agent}/chat (no token)
<- 402 Payment Required (includes payment info)
Client -> Purchases credits via Nevermined checkout page
Client -> POST /api/paid/{agent}/chat (payment-signature header)
<- 200 OK (agent response, 1 credit deducted)| Step | Action |
|---|---|
| 1 | Client sends a chat request without payment credentials |
| 2 | Trinity returns HTTP 402 with Nevermined payment details |
| 3 | Client purchases credits via the Nevermined checkout page |
| 4 | Client retries the request with payment-signature header containing the access token |
| 5 | Trinity verifies payment, deducts the configured credits, routes to agent |
| 6 | Trinity asks Nevermined to settle the transaction; Nevermined settles it |
Payment Info (Public)
Call GET /api/paid/{agent_name}/info to retrieve payment requirements without authentication. Returns the Agent ID, Plan ID, checkout URL, and credits per request.
Crypto Plans and Card (Fiat) Plans
Nevermined plans are paid either in crypto or by card, and the x402 requirements Trinity advertises must match the plan — the facilitator checks the buyer's token against them, so a card plan described as a crypto one is simply unpayable. Trinity reads the plan's own type from Nevermined and advertises it:
| Plan | Scheme advertised | Network |
|---|---|---|
| Crypto | nvm:erc4337 | eip155:8453 (live) / eip155:84532 (sandbox) |
| Card / fiat | nvm:card-delegation | The plan's payment provider — stripe, braintree or visa |
Nothing to configure: the plan type comes from Nevermined, is cached for five minutes, and GET /api/paid/{agent}/info shows the scheme a client will be asked for. If Nevermined is unreachable when the lookup is first needed, Trinity serves the last answer it had — or falls back to nvm:erc4337— and logs a warning naming the plan.
The URL in a 402 Must Be the URL You Call
The 402 carries a resource.url that your payment token is minted and verified against, so it has to be the origin a buyer actually reaches Trinity on. Trinity uses the public URL you configured (Public URL under Settings → General, or the PUBLIC_CHAT_URL / FRONTEND_URL environment variables) when it matches the host of the incoming request, and otherwise the request's own host — upgraded to https when your proxy sends X-Forwarded-Proto: https. If a buyer reports a token rejected for the wrong resource URL, check that your TLS terminator forwards that header and that the configured public URL is the hostname clients really use.
Paid Calls over A2A
The same paywall guards an agent's A2A door (POST /a2a/{agent_name}) once the agent is both exposed over A2A and has payments enabled. A caller with a Trinity key still runs free; a caller without one gets 402 and pays with the same Nevermined token. A priced agent's A2A card also states the plan, the credits per call and a paymentInfoUrl pointing at /api/paid/{agent}/info, so a payment-aware client can pay on its first request. The reply carries the payment status and receipt in the Task's metadata. The details — where the token goes in an A2A message, retries and refusals — are in A2A Protocol.
Time-Based Plans
For a duration plan, set Credits per Request to 0. The plan charges by time, so Trinity sends no per-call amount and the A2A card advertises the cost as plan-defined. A negative value is rejected.
Fund an Agent with a Card
The sections above are the seller side: an agent charging its callers. An agent can also be a buyer— funded with a card so it can pay for things itself. Nevermined holds the card and the spending mandate and settles every purchase; Trinity never sees or stores the card. Trinity keeps only the delegation id Nevermined hands back, gives it to the agent, shows what is left to spend (read live from Nevermined) and revokes the mandate at Nevermined when you ask.
From the Trinity UI.Nevermined holds the card throughout; Trinity shows Nevermined's own card form and records the mandate id it returns.
Admin, once: Settings › Integrations › Nevermined organization. Enter the Nevermined organization id, pick the Nevermined environment (sandbox first), and paste the Nevermined widget secret and agent API key. Both secrets are needed the first time; afterwards the fields stay blank and a pasted value rotates that secret. Switching the environment asks first. Remove Nevermined organization is refused while any agent holds an active Nevermined mandate.
Owner, per agent: start the agent, open its Payments tab and find Spending · Nevermined card mandate. Choose Enroll a card with Nevermined. Nevermined's card form opens inside the page (or over the whole page on a narrow screen — press Esc to close it). Enter the card; Nevermined creates the mandate, and Trinity binds it to the agent.
If binding fails after Nevermined created the mandate (for example the agent stopped), the panel keeps the ids in this browser tab and offers Retry bind — after a "too many requests" or "unreachable" answer it waits the seconds the server asked for. Discard keeps the mandate at Nevermined; revoke it there if you do not want it.
A funded agent shows Nevermined's live numbers (remaining, limit, spent, purchases, expiry) and Revoke at Nevermined, which asks first.
If the browser blocks Nevermined's embedded form, the panel offers Continue on Nevermined: Nevermined's own card page opens with a one-time session in the address bar and brings you back to the agent's page, where Trinity binds the mandate only if the return matches the request this browser tab made. The Nevermined widget key's allowed origins must include this Trinity instance's address, or Nevermined's form does not start.
Permissions-Policy: payment=(), so wallet buttons (Apple Pay, Google Pay) inside Nevermined's form are unavailable; typing the card works.Once per instance (admin). Connect the instance's Nevermined organization: PUT /api/nevermined/organization with the org_id, the environment (sandbox or live — start with sandbox), the organization's widget secret and its agent API key. Both secrets are write-only: no read ever returns them. Give that agent_api_keythe least privilege Nevermined allows — every funded agent receives it. While any agent holds an active mandate you cannot change the environment, rotate the key or remove the organization; revoke the mandates first.
Per agent (owner). The agent must be running.
Open the Nevermined card widget for the agent (POST /api/nevermined/agents/{agent_name}/widget-session). Nevermined enrols the card and creates the spending mandate in the widget.
Trinity binds the mandate (POST /api/nevermined/agents/{agent_name}/delegation), after checking with Nevermined that it exists and is active, and writes NVM_DELEGATION_ID, NVM_API_KEY and NVM_ENVIRONMENT into the agent's .env. NVM_ENVIRONMENT tells the agent which Nevermined environment (sandbox or live) the key and mandate belong to. The keys take effect at the agent's next execution.
An agent holds one mandate at a time. To change it, revoke the current one first.
What is left to spend. GET /api/nevermined/agents/{agent_name}/delegation (or the get_agent_spending MCP tool) returns the remaining budget, the limit, purchases used and the expiry — every number straight from Nevermined. If Nevermined cannot be reached the status reads unknownand the numbers are empty; Trinity never estimates them. An agent can read its own budget and no other agent's.
Revoke. DELETE /api/nevermined/agents/{agent_name}/delegation (or the revoke_agent_delegation MCP tool, your own user-scoped key only) revokes the mandate at Nevermined — Nevermined refuses the agent's next paid call — and removes the keys from the agent. If the agent is stopped, the delegation id left in its .env is inert, but the organization's agent key stays until the next bind rewrites it or you remove it. Trinity never overwrites or removes an NVM_API_KEY you set by hand: while the agent holds one that is not the organization's key, bind is refused (409 agent_key_present) — remove it from the agent's credentials first. The same refusal covers a stale organization key left behind from before the key was rotated; remove it and bind again.
An unreadable .env is never overwritten. Bind and revoke rewrite the agent's whole .env, so if Trinity cannot read that file as text (it is not UTF-8, or the read fails), bind is refused with 409 env_unreadable and nothing is written or recorded. Revoke still revokes the mandate at Nevermined, but leaves the file untouched and says so in the response's env_note. Fix the file, then bind again or remove the keys by hand.
Operator Settings
Every payment verify and settle is a call to the Nevermined facilitator, and every card-mandate check or revoke is a call to Nevermined too. Three optional environment variables bound those calls across the whole platform; all need a backend restart:
| Variable | Default | Meaning |
|---|---|---|
| NEVERMINED_MAX_INFLIGHT | 8 | The most facilitator calls in flight at once, across all agents |
| NEVERMINED_DELEGATION_MAX_INFLIGHT | 4 | The most card-mandate verify and revoke calls in flight at once, across all agents — its own gate, so a polling spending panel never takes a facilitator slot |
| NEVERMINED_FACILITATOR_WAIT_SECONDS | 5.0 | How long a call waits for a free slot before answering "busy, retry". A refused call never reaches the facilitator and burns nothing |
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /api/paid/{agent_name}/chat | POST | Paid chat: 402 without a payment-signature header, 403 for an invalid or exhausted token, 200 with the reply. Accepts an Idempotency-Key header |
| /api/paid/{agent_name}/info | GET | Payment requirements, including the plan's scheme and an absolute resource.url (no auth) |
| /a2a/{agent_name} | POST | The A2A task door; charges a caller without a Trinity key when the agent is exposed and priced — see A2A Protocol |
| /api/nevermined/agents/{name}/config | POST | Configure payment settings |
| /api/nevermined/agents/{name}/config | GET | Get payment configuration |
| /api/nevermined/agents/{name}/config | DELETE | Remove payment configuration |
| /api/nevermined/agents/{name}/config/toggle | PUT | Enable or disable payments |
| /api/nevermined/agents/{name}/payments | GET | Payment history |
| /api/nevermined/settlement-failures | GET | Failed settlements (admin) |
| /api/nevermined/retry-settlement/{log_id} | POST | Retry failed settlement (admin) |
| /api/nevermined/organization | GET / PUT / DELETE | The instance's Nevermined organization (admin) |
| /api/nevermined/agents/{agent_name}/widget-session | POST | Open the Nevermined card widget (owner) |
| /api/nevermined/agents/{agent_name}/delegation | POST / GET / DELETE | Bind, read (live from Nevermined) or revoke the agent's card mandate |
MCP Tools
| Tool | Description |
|---|---|
| configure_nevermined | Set NVM API Key, environment, Agent ID, Plan ID and credits per request. Takes a signed-in session, so an MCP API key is refused: configure on the agent's Payments tab |
| get_nevermined_config | Retrieve current payment configuration |
| toggle_nevermined | Enable or disable payments. Shown only to your own user-scoped key (the agent's owner or an admin) |
| get_nevermined_payments | View payment history |
| get_agent_spending | What the agent can still spend from its Nevermined card mandate |
| revoke_agent_delegation | Revoke the agent's Nevermined card mandate. Shown only to your own user-scoped key (the agent's owner or an admin) |
Limitations
payment-signature header is required on every paid request to /api/paid/{agent}/chat; there is no session persistence. (On the A2A door the token travels in the message metadata instead.)See Also
Trinity docs
configure_nevermined tool familyExternal references