Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
Guides/Nevermined Payments

Nevermined x402 Payments

Monetize agents with per-request payments using the Nevermined x402 payment protocol. Users pay per chat message; agents earn credits.

Concepts

•x402 Protocol — HTTP-native payment protocol. Unauthenticated requests to a paid endpoint return HTTP 402 (Payment Required) with payment instructions.
•NVM API Key — Nevermined platform API key used to verify payments and settle credits.
•Agent ID — The Nevermined-assigned identifier for the agent being monetized.
•Plan ID — The Nevermined plan that defines credit pricing and allocation.
•Access Token — A payment-signature header value that proves the caller has purchased credits.

Setup (Admin)

1

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.

2

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.

3

Flip the Enabled toggle to switch payments on; Remove deletes the configuration and disables paid access.

4

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)
StepAction
1Client sends a chat request without payment credentials
2Trinity returns HTTP 402 with Nevermined payment details
3Client purchases credits via the Nevermined checkout page
4Client retries the request with payment-signature header containing the access token
5Trinity verifies payment, deducts the configured credits, routes to agent
6Trinity 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:

PlanScheme advertisedNetwork
Cryptonvm:erc4337eip155:8453 (live) / eip155:84532 (sandbox)
Card / fiatnvm:card-delegationThe 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.

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.

1

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.

2

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.

3

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.

4

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.

•If Trinity asks you to sign in again when Nevermined sends you back, the returned ids are lost: the mandate exists at Nevermined — revoke it there, or enroll again.
•Trinity sends 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.

1

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.

2

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.

3

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:

VariableDefaultMeaning
NEVERMINED_MAX_INFLIGHT8The most facilitator calls in flight at once, across all agents
NEVERMINED_DELEGATION_MAX_INFLIGHT4The 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_SECONDS5.0How long a call waits for a free slot before answering "busy, retry". A refused call never reaches the facilitator and burns nothing

API Endpoints

EndpointMethodDescription
/api/paid/{agent_name}/chatPOSTPaid 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}/infoGETPayment requirements, including the plan's scheme and an absolute resource.url (no auth)
/a2a/{agent_name}POSTThe A2A task door; charges a caller without a Trinity key when the agent is exposed and priced — see A2A Protocol
/api/nevermined/agents/{name}/configPOSTConfigure payment settings
/api/nevermined/agents/{name}/configGETGet payment configuration
/api/nevermined/agents/{name}/configDELETERemove payment configuration
/api/nevermined/agents/{name}/config/togglePUTEnable or disable payments
/api/nevermined/agents/{name}/paymentsGETPayment history
/api/nevermined/settlement-failuresGETFailed settlements (admin)
/api/nevermined/retry-settlement/{log_id}POSTRetry failed settlement (admin)
/api/nevermined/organizationGET / PUT / DELETEThe instance's Nevermined organization (admin)
/api/nevermined/agents/{agent_name}/widget-sessionPOSTOpen the Nevermined card widget (owner)
/api/nevermined/agents/{agent_name}/delegationPOST / GET / DELETEBind, read (live from Nevermined) or revoke the agent's card mandate

MCP Tools

ToolDescription
configure_neverminedSet 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_configRetrieve current payment configuration
toggle_neverminedEnable or disable payments. Shown only to your own user-scoped key (the agent's owner or an admin)
get_nevermined_paymentsView payment history
get_agent_spendingWhat the agent can still spend from its Nevermined card mandate
revoke_agent_delegationRevoke the agent's Nevermined card mandate. Shown only to your own user-scoped key (the agent's owner or an admin)

Limitations

•Only one Nevermined plan per agent.
•Settlement failures must be retried manually via the admin endpoint.
•The 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.)
•The A2A paid door needs the agent's A2A exposure turned on; a price alone does not open it.

See Also

Trinity docs

•MCP Server — the configure_nevermined tool family
•A2A Protocol — exposing an agent over A2A, and paying for inbound A2A calls
•Public Access — publishing the paid and A2A doors on a public hostname
•Chat API — the unpaid chat routes the paid endpoint wraps

External references

•Nevermined Documentation — registering agents and plans, buying credits, access tokens