Nevermined Payments

Nevermined Payments Integration

Skill version: 0.5.1 | Last updated: 2026-06-18 | Canonical source (always latest): https://github.com/nevermined-io/docs/tree/main/skills/nevermined-payments

⚠️ Use the latest version. This skill changes often. If you have an installed or cached copy, check its Last updated date against the canonical source above and refresh it if older — an out-of-date copy may be missing whole flows (e.g. the card-enrollment / embed/session steps were added after Feb 2026). Unless a specific version is requested, always work from the latest.

Verified against the live sandbox API (https://api.sandbox.nevermined.app/api/v1/rest/docs-json); the cited SDK method names are stable from @nevermined-io/payments@1.4.1 through the current 1.9.0, and payments-py@1.15.1.

Overview

Nevermined provides financial rails for AI agents — real-time monetization, access control, and payments. This skill covers two modes, and most tasks fall cleanly into one:

If you are an autonomous agent that needs to pay, enroll, register, or report, start at Track A — Operate as an autonomous agent. If you are building a service that needs to charge callers, jump to Track B — Add payments to your code.

How payments work (x402 in one minute)

Nevermined uses the x402 protocol (HTTP 402 Payment Required). A buyer acquires an access token authorizing a spend, then settles it — which charges the payment method, mints, and burns credits. The same token can be sent to a protected agent in the payment-signature header; the agent verifies and settles for you.

Two payment schemes exist:

Three HTTP headers carry x402 data: payment-signature (client→server, the token), payment-required (server→client on 402, base64 JSON), payment-response (server→client on 200, base64 settlement receipt).

---

Track A — Operate as an autonomous agent

This is a REST runbook: every step (A1–A8 below) is a plain HTTPS call you can make with curl or any HTTP client — no SDK install required. Each flow ends with the equivalent SDK one-liner if you prefer typed calls.

Where the full detail lives. Every flow is documented inline below (A1–A8). The complete request/response bodies are in the reference files alongside this skill — read the matching one when you need exact payloads:

Design principle — minimal human interaction. A human is needed for at most two one-time setup steps — often just one:

1. Get your first API key (a human signs in once) — always required, and
2. Enroll a card (a human enters card details in a browser — required by PCI) — only if you pay by card; the stablecoin path skips this entirely.

Everything else is fully programmatic and reusable: checking payment methods, creating delegations, purchasing, settling, registering plans/agents, and reading buyer/seller status. Store the API key and any delegationId and reuse them.

A0 · Environment

Pick the environment and use its exact base URL for every call. State it explicitly to yourself — do not infer it from anything else.

• Auth: send your key as Authorization: Bearer on every call (a few read-only endpoints — e.g. GET /protocol/plans/{id} and GET /protocol/agents/{id}/plans — are public, but the header is harmless there).
• Never log or persist secrets in the clear: API keys, delegationId, and paymentMethodId arrive as query-string params on your 127.0.0.1 callback (see A1/A3). Your callback server must not log the request line, and you should keep the key in a secret store — query strings are the most-logged part of any request (access logs, shell history, process args).
• Discover the API surface: GET {API_BASE}/api/v1/rest/docs-json returns the OpenAPI JSON. Heads-up — it is not exhaustive: several agent-facing endpoints are served but deliberately omitted from docs-json, notably POST /embed/session (card enrollment), the delegation/* routes, and organizations/{orgId}/analytics/*. Don't conclude an endpoint doesn't exist because it's absent from the OpenAPI — use the exact paths documented in this skill directly. (To confirm one is live, send the request: a 401/400 means it exists; only 404 means it doesn't.)
• Default to sandbox unless the human explicitly asks for live — live moves real money.
• Pin the API version: send Nevermined-Version: on every direct REST call so platform releases can't change the wire shape under you. Discover the supported range with GET {API_BASE}/api/v1/meta/versions (authenticated; returns current, floor, gatedVersions, and the pin of YOUR key) and default to its current. Without the header, requests use the key's stored pin (editable by the key owner in the dashboard). The SDKs send the header automatically (LOCKED_API_VERSION). Never silently change a key's stored pin — pinning is the integration owner's deliberate decision. Changelog: https://nevermined.ai/docs/development-guide/api-changelog

A1 · Get a Nevermined API key (needs a human once)

You cannot mint your first key yourself — a human signs in once. Default flow: drive a one-time browser login and capture the key automatically (Option A). Host a 127.0.0.1 callback, print a single sign-in URL for the human to open, and read the key off the redirect. Do not ask the human to copy/paste a key or write it to a file unless Option A is genuinely impossible (no localhost callback) — then use Option B.

Option A — embedded login (the default; the key returns to you automatically). Host a tiny callback server on 127.0.0.1 (the login page only redirects to localhost/127.0.0.1 callbacks), then print this URL and ask your human to open it:

https://nevermined.app/auth/cli?callback_url=http://127.0.0.1:/callback

After they sign in, the browser is redirected to http://127.0.0.1:/callback?nvm_api_key= — read nvm_api_key off that request. (Keys for sandbox start with sandbox; for live, live.)

Option B — manual paste (works anywhere). Ask your human to open nevermined.app, sign in, create an API Key (Settings → Global NVM API Keys → + New API Key), and paste it back. Or, once signed in, open https://nevermined.app/auth/cli with no callback_url to see the key on screen.

Store the key and reuse it. Never fabricate a key; the placeholder is sandbox:your-api-key. Full docs: https://nevermined.ai/docs/agents-guide/get-api-key

A2 · Check your payment methods

curl -H "Authorization: Bearer $NVM_API_KEY" \
  https://api.sandbox.nevermined.app/api/v1/payment-methods
# → [ { id, type, brand, last4, provider, status, ... } ]

• A stablecoin payment method (an account-abstraction smart account) exists by default — fund it and you can pay immediately, no human needed. In sandbox it spends test USDC on Base Sepolia; see stablecoin payments for funding. Its id is your wallet/holder address (used in A5).
• A card method appears here only after the one-time enrollment in A3 below.
• Field shapes: status is capitalized ("Active", "Revoked") and the erc4337 method's type is "crypto_wallet". (In A5, delegation cents fields like spendingLimitCents come back as strings, not numbers.)

SDK: payments.delegation.listPaymentMethods() / payments.delegation.list_payment_methods().

A3 · Enroll a card + create a delegation (needs a human once)

Skip this entirely if you pay with stablecoins. To pay with a card, use the embedded browser flow — same shape as the API key in A1: host a 127.0.0.1 callback, print the card-setup URL for the human to open in a browser, they sign in and enter the card, and you capture paymentMethodId + delegationId from the redirect. Open to any agent with an API key (no organization required).

# 1. Mint an embedded session (host a 127.0.0.1 callback first)
curl -X POST -H "Authorization: Bearer $NVM_API_KEY" -H "Content-Type: application/json" \
  -d '{"returnUrl":"http://127.0.0.1:/callback"}' \
  https://api.sandbox.nevermined.app/api/v1/embed/session
# → { "sessionToken": "...", "userId": "...", "userWallet": "0x...", "expiresAt": "..." }

POST /api/v1/embed/session is served but not listed in docs-json (see A0) — call it directly; don't search the OpenAPI for it. It accepts any valid API key, takes only { returnUrl } (a localhost/127.0.0.1 URL), and returns a sessionToken.

1. Print the card-setup URL and ask your human to open it in their browser:

https://embed.nevermined.app/cards/setup?sessionToken=&returnUrl=http://127.0.0.1:/callback&state=&provider=stripe

1. When they finish, the browser redirects to your returnUrl with paymentMethodId and delegationId as query params. Store the delegationId — a delegation authorizes you to spend within a fixed budget and time window, and you reuse it until it is spent or expires. To enforce a specific spending cap and duration (e.g. $50 over 30 days), create the delegation explicitly with POST /delegation/create (below), passing the callback's paymentMethodId as the providerPaymentMethodId field.

Generate state as an unguessable random value and reject the callback unless the returned state matches the one you sent — it binds the response to your request (CSRF guard). And per A0, don't log the callback request line: paymentMethodId/delegationId ride in the query string.

Create a delegation explicitly. provider is one of stripe, braintree, visa (card) or erc4337 (stablecoin). provider, currency, spendingLimitCents, and durationSecs are required (no silent default for provider or currency; use currency: "usdc" for erc4337, "usd" for card providers).

# Stablecoin (crypto) — no card, no human. Uses your default smart-account method.
curl -X POST -H "Authorization: Bearer $NVM_API_KEY" -H "Content-Type: application/json" \
  -d '{"provider":"erc4337","spendingLimitCents":10000,"durationSecs":604800,"currency":"usdc"}' \
  https://api.sandbox.nevermined.app/api/v1/delegation/create

# Card (Stripe). providerPaymentMethodId is the `id` returned by GET /payment-methods.
curl -X POST -H "Authorization: Bearer $NVM_API_KEY" -H "Content-Type: application/json" \
  -d '{"provider":"stripe","providerPaymentMethodId":"pm_...","spendingLimitCents":10000,"durationSecs":604800,"currency":"usd"}' \
  https://api.sandbox.nevermined.app/api/v1/delegation/create
# → { "delegationId": "...", "delegationToken": "..." }

SDK: payments.delegation.createDelegation({ provider: 'erc4337', spendingLimitCents, durationSecs, currency: 'usdc' }). provider and currency are required (no silent default); the delegation is plan-agnostic unless you pass planId.

Visa caveat. delegation/create does accept provider: "visa", but only together with a browser-produced consumerPrompt + assuranceData from a Visa WebAuthn ceremony; omitting them is rejected with BCK.VISA.0014 ("requires consumerPrompt and assuranceData"). An autonomous agent can't generate assuranceData, so in practice have your human create the Visa delegation in the webapp and reuse its delegationId.

Full detail: the complete embedded card-enrollment handshake (session → card-setup redirect → delegationId), the localhost-callback rules, and every delegation/create field and response are in references/autonomous-operations.md §3.

A4 · Buy access via x402 (fully programmatic)

Two calls: get an access token, then settle. x402 is the default buy flow for both rails — crypto and card work the same way, only scheme/network differ. The facilitator charges the right method (on-chain against your delegation for crypto, the card for fiat), mints, and burns.

# 1. Get an access token (authorizes the spend against your delegation)
curl -X POST -H "Authorization: Bearer $NVM_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "accepted": { "scheme": "nvm:erc4337", "network": "eip155:84532", "planId": "" },
        "delegationConfig": { "delegationId": "" }
      }' \
  https://api.sandbox.nevermined.app/api/v1/x402/permissions
# → { "accessToken": "..." }

# 2. Settle — charges the method, mints, and burns; this receipt is your proof of purchase
curl -X POST -H "Authorization: Bearer $NVM_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "paymentRequired": {
          "x402Version": 2,
          "resource": { "url": "" },
          "accepts": [ { "scheme": "nvm:erc4337", "network": "eip155:84532", "planId": "", "extra": {} } ],
          "extensions": {}
        },
        "x402AccessToken": ""
      }' \
  https://api.sandbox.nevermined.app/api/v1/x402/settle
# → { "success": true, "creditsRedeemed": "1", "remainingBalance": "999", "transaction": "0x...", "network": "eip155:84532" }

• Pay with a card instead: set "scheme": "nvm:card-delegation" and "network": "stripe" (or braintree/visa) in both accepted and accepts[0].
• resource.url for a plan top-up = the plan's own URL, {API_BASE}/api/v1/protocol/plans/.
• Which scheme does a plan use? GET {API_BASE}/api/v1/protocol/plans/ (public) returns the plan's metadata and pricing so you can pick nvm:erc4337 vs nvm:card-delegation before paying. When buying from a protected agent, its 402 tells you instead.
• Note the field rename: /permissions returns accessToken; pass that value as x402AccessToken in /settle and /verify.
• Dry run first (optional): POST /api/v1/x402/verify with the same { paymentRequired, x402AccessToken } body → { "isValid": true }.
• Proof of purchase = success: true with creditsRedeemed > 0 and a remainingBalance (and, for crypto, an on-chain transaction).
• Card budget caveat: a card settle may not immediately move the delegation's amountSpentCents/remainingBudgetCents — use the settle receipt + the A5 plan balance as the source of truth for card spend, not the delegation budget.

Calling a protected agent directly (the common case): just send the access token as the payment-signature header to the agent's endpoint — the agent's own 402 response is your paymentRequired, and the agent verifies + settles for you. You only call /settle yourself when topping up a plan with no protected endpoint to hit.

A dedicated orderPlan / POST /protocol/plans/{id}/order endpoint exists for an explicit, upfront stablecoin purchase, but x402 above is the default for both rails — use /order only when specifically requested.

SDK shortcut for step 1:

const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {
  delegationConfig: { delegationId }        // create the delegation first via createDelegation, then pass its delegationId
})

res = payments.x402.get_x402_access_token(plan_id, agent_id,
    token_options=X402TokenOptions(delegation_config=DelegationConfig(delegation_id=delegation_id)))

Full crypto + card walkthroughs with every field: references/autonomous-operations.md. Subscriber-side SDK patterns: references/client-integration.md.

A5 · Check your purchases & credits (as a buyer) (fully programmatic)

You query a plan you hold by its ``. There is no "list every plan I've purchased" endpoint, so retain the plan IDs you buy — each /x402/settle receipt identifies the plan, and the plan URL embeds the id. (GET /protocol/plans lists plans you published as a seller, not ones you bought.)

# Credits left on a plan you hold. YOUR_ADDRESS = your wallet: the `id`/address of your
# erc4337 payment method from GET /payment-methods (crypto), or the `userWallet` from POST /embed/session.
curl -H "Authorization: Bearer $NVM_API_KEY" \
  https://api.sandbox.nevermined.app/api/v1/protocol/plans//balance/
# → { planId, planName, planType, isSubscriber, balance, pricePerCredit, ... }

# Your delegations and remaining budget
curl -H "Authorization: Bearer $NVM_API_KEY" \
  https://api.sandbox.nevermined.app/api/v1/delegation
# → { totalResults, delegations: [ { delegationId, status, spendingLimitCents, amountSpentCents, remainingBudgetCents, expiresAt } ] }
# `status` is "Active" | "Expired" | "Exhausted" — flag a delegation when status != "Active", or remainingBudgetCents is at/near 0, or expiresAt is near.
# Caveat: a CARD delegation's budget may not reflect a card settle immediately (amountSpentCents can stay 0) — for cards, treat the settle receipt + plan balance as the spend source of truth, not the delegation budget.

# A delegation's individual charges
curl -H "Authorization: Bearer $NVM_API_KEY" \
  https://api.sandbox.nevermined.app/api/v1/delegation//transactions

SDK: payments.plans.getPlanBalance(planId) (PlanBalance.balance is a bigint in TS / int in Python). The creditsRedeemed/remainingBalance you get back from /settle (or the decoded payment-response header) is also a live proof of your balance after a purchase.

A6 · Register a plan + agent (as a seller) (fully programmatic — SDK-first)

Registration is the one flow where the SDK is the recommended path: the price/credits configs are low-level on-chain structures (amounts, receivers, token addresses, redemption type, nonce) that the SDK helpers build for you.

const { agentId, planId } = await payments.agents.registerAgentAndPlan(
  { name: 'Weather Agent', description: 'Forecasts on demand', tags: ['weather'], dateCreated: new Date() },
  { endpoints: [{ POST: 'https://your-api.com/query' }] },   // optional; omit for an open agent
  { name: 'Starter Plan', description: '100 requests for $10', dateCreated: new Date() },
  payments.plans.getFiatPriceConfig(10_000_000n, BUILDER_ADDRESS, 'USD'),  // $10.00 — fiat is 6-decimal units, NOT cents. Or getERC20PriceConfig(...) for crypto
  payments.plans.getFixedCreditsConfig(100n, 1n)
)

Price helpers: getERC20PriceConfig/getEURCPriceConfig (crypto), getFiatPriceConfig (card). Credits helpers: getFixedCreditsConfig (prepaid), getExpirableDurationConfig (time-based), getPayAsYouGoCreditsConfig (per-call). The raw REST endpoints exist (POST /api/v1/protocol/plans, /api/v1/protocol/agents, /api/v1/protocol/agents/plans) but expect the fully-formed priceConfig/creditsConfig objects — use the SDK helpers to produce them. Full plan-type matrix and helper reference: references/payment-plans.md.

A7 · Check your agents' status & revenue (as a seller) (fully programmatic)

Organization analytics (require an active Premium org tier). Discover your orgId from your own records — every item in GET /protocol/plans and /protocol/agents carries .orgId + .organizationName; take the most common non-null .orgId across your published items (it's the org-... id, also in your …/organizations//agentic-instructions.md). Only call analytics with an id matching ^org-[0-9a-f-]+$. Failure modes to handle (fall back to the any-tier building blocks below on any of them):

• a foreign / non-admin org → 403 BCK.AUTH.0004 ("Organisation admin privileges required");
• a non-Premium org → 403 BCK.ORGANIZATIONS.0022;
• a malformed / placeholder org id → a silent 200 of all-zeros — never report that as real revenue; if you have published plans but analytics returns zeros, treat it as a failure.

B=https://api.sandbox.nevermined.app/api/v1/organizations//analytics
curl -H "Authorization: Bearer $NVM_API_KEY" "$B/revenue?from=2026-03-20T00:00:00Z&to=2026-06-18T00:00:00Z"
# → { items: [ { agentId, agentName, totalRevenue, transactionCount } ], totalRevenue }
curl -H "Authorization: Bearer $NVM_API_KEY" "$B/mrr"
# → { mrr, activeSubscriptions }
curl -H "Authorization: Bearer $NVM_API_KEY" "$B/usage?from=...&to=..."
# → { items: [ { planId, planName, creditsBurned, uniqueUsers } ] }
curl -H "Authorization: Bearer $NVM_API_KEY" "$B/customers?limit=20"
# → { items: [ { customerId, userId, totalSpent, firstSeenAt, lastActiveAt } ], totalCustomers }

Reading the analytics rows: they're labelled agentId/agentName but are grouped by plan; totalRevenue/totalSpent are stringified integers in 6-decimal token units (divide by 1,000,000 for USD), while creditsBurned is a plain count. mrr is legitimately 0 when sales were one-off credit purchases rather than recurring subscriptions.

Any-tier building blocks (no Premium required) — list what you've published and inspect each:

curl -H "Authorization: Bearer $NVM_API_KEY" https://api.sandbox.nevermined.app/api/v1/protocol/plans     # your plans
curl -H "Authorization: Bearer $NVM_API_KEY" https://api.sandbox.nevermined.app/api/v1/protocol/agents    # your agents
curl -H "Authorization: Bearer $NVM_API_KEY" https://api.sandbox.nevermined.app/api/v1/protocol/agents//plans  # plans on an agent

These return { total, page, offset, plans|agents: [ … ] }, but each item is the full record, not a flat summary: read the name from metadata.main.name and price/type from registry / metadata (the id is the plan/agent id). The flat { planName, planType, pricePerCredit } shape is only returned by the balance endpoint in A5, not by these list endpoints.

For per-request usage and cost observability (Helicone), see references/seller-operations.md, which details every seller query and the response shapes.

A8 · Onboard your own customers (white-label) (org admin — fully programmatic)

If you operate an organization, provision Nevermined accounts for your customers from your backend — no member seat, recorded in your Customers CRM, and returning a scoped key you use to pay for your agents on their behalf. One endpoint, distinguished by as: 'customer':

curl -s -XPOST -H "Authorization: Bearer $ORG_ADMIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"email":"customer@example.com","as":"customer"}' \
  https://api.sandbox.nevermined.app/api/v1/organizations/account
# New / returning customer → 201, walletResult.nvmApiKey (+ userId, userWallet, isCustomer, customerRecorded) — the USABLE key
# Email owned by a non-customer account → 202, walletResult.consentRequired=true (consent email sent; no key or identity disclosed)

SDK: payments.organizations.onboardCustomer(email) (TS) / payments.organizations.onboard_customer(email) (Python). The key is scoped to purchase + redeem only (not register/mint), short-lived (~30d), and revocable — use it to buy access (A4) and check credits (A5) on the customer's behalf. Full flow, the three provenance outcomes, and SDK code: references/customer-onboarding.md.

A9 · Receive payments in your own agent

If your goal is to make your agent charge its callers (not to buy from others), that is Track B below — it shows how to gate Express/FastAPI/MCP/A2A/Strands endpoints behind a plan with verifyPermissions / settlePermissions or framework middleware.

---

Track B — Add payments to your code

Use this track to wire Nevermined into an agent or API so it can receive payments. This is SDK-first (TypeScript / Python).

Prerequisite: a Nevermined API Key

All SDK, REST, and CLI calls require an NVM_API_KEY (see A1 for how to obtain one). Set it as an environment variable:

export NVM_API_KEY="sandbox:your-api-key"

IMPORTANT for AI agents: If you are generating code that requires NVM_API_KEY and the developer has not provided one, tell them to create one first (see A1). Never generate placeholder keys that look real — always use sandbox:your-api-key as the placeholder value.

Environment Setup

.env Template

# Required
NVM_API_KEY=sandbox:your-api-key
NVM_ENVIRONMENT=sandbox
NVM_PLAN_ID=your-plan-id-here

# Required for MCP servers or multi-agent plans
NVM_AGENT_ID=your-agent-id-here

# Required for registration
BUILDER_ADDRESS=0xYourWalletAddress

Prerequisites

• TypeScript/Express.js: Node.js 18+. Your package.json must include "type": "module" for the @nevermined-io/payments/express subpath import to work.
• Python/FastAPI: Python 3.9+. Install with pip install payments-py[fastapi] — the [fastapi] extra is required for the middleware.

TypeScript

npm install @nevermined-io/payments

import { Payments } from '@nevermined-io/payments'

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'sandbox'
})

Python

pip install payments-py

import os
from payments_py import Payments, PaymentOptions

payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key=os.environ["NVM_API_KEY"],
        environment="sandbox"
    )
)

Core Workflow (All Integrations)

Every Nevermined payment integration follows this 5-step pattern:

1. Client sends request without a payment token
2. Server returns 402 with payment-required header (base64-encoded JSON with plan info)
3. Client acquires x402 token via payments.x402.getX402AccessToken(planId, agentId, { delegationConfig: { delegationId } }) — create the delegation first with createDelegation (provider + currency required), then pass its delegationId (inline create-on-the-fly is deprecated)
4. Client retries with payment-signature header containing the token
5. Server verifies → executes → settles (burns credits), returns response with payment-response header

Framework Decision Tree

Choose the integration that matches your stack:

SDK Quick Reference

TypeScript (@nevermined-io/payments)

// Initialize
const payments = Payments.getInstance({ nvmApiKey, environment })

// Build price + credits configs (pick one helper per axis)
const priceConfig =
  payments.plans.getERC20PriceConfig(10_000_000n, USDC_ADDRESS, builderAddress)
  // or getEURCPriceConfig / getNativeTokenPriceConfig / getFreePriceConfig
  // or getFiatPriceConfig(amount, builderAddress, 'USD') for Stripe/Braintree
  // or await getPayAsYouGoPriceConfig(amount, builderAddress, tokenAddress?)

const creditsConfig =
  payments.plans.getFixedCreditsConfig(100n, 1n)
  // or getDynamicCreditsConfig / getExpirableDurationConfig
  // or getPayAsYouGoCreditsConfig() for PAYG plans

// Register agent + plan
const { agentId, planId } = await payments.agents.registerAgentAndPlan(
  agentMetadata, agentApi, planMetadata, priceConfig, creditsConfig
)

// Subscriber: order plan and get token
await payments.plans.orderPlan(planId)
const planBalance = await payments.plans.getPlanBalance(planId)
console.log(`Credits remaining: ${planBalance.balance}`)  // PlanBalance.balance is bigint

// Create the delegation first (provider + currency required), then request the token by delegationId.
const delegation = await payments.delegation.createDelegation({
  provider: 'erc4337', spendingLimitCents: 100, durationSecs: 3600, currency: 'usdc'
})
const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {
  delegationConfig: { delegationId: delegation.delegationId }
})

// Server: verify and settle
const verification = await payments.facilitator.verifyPermissions({
  paymentRequired, x402AccessToken: token, maxAmount: BigInt(credits)
})
const settlement = await payments.facilitator.settlePermissions({
  paymentRequired, x402AccessToken: token, maxAmount: BigInt(creditsUsed)
})

// Helpers
import { buildPaymentRequired } from '@nevermined-io/payments'
import { paymentMiddleware, X402_HEADERS } from '@nevermined-io/payments/express'

// MCP server
payments.mcp.registerTool(name, config, handler, { credits: 5n })
const { info, stop } = await payments.mcp.start({ port, agentId, serverName })

// A2A server
const agentCard = payments.a2a.buildPaymentAgentCard(baseCard, { paymentType, credits, planId, agentId })
const server = await payments.a2a.start({ port, basePath: '/a2a/', agentCard, executor })
// A2A client
const client = payments.a2a.getClient({ agentBaseUrl, agentId, planId })
await client.sendMessage("Hello", accessToken)

Python (payments-py)

from payments_py.x402 import CreateDelegationPayload, DelegationConfig, X402TokenOptions

# Initialize
payments = Payments.get_instance(PaymentOptions(nvm_api_key=key, environment="sandbox"))

# Build price + credits configs (helpers exist on payments.plans and as module funcs)
price_config = payments.plans.get_erc20_price_config(10_000_000, USDC_ADDRESS, builder_address)
# or get_eurc_price_config / get_native_token_price_config / get_free_price_config
# or get_fiat_price_config(amount, builder_address, "USD") for Stripe/Braintree
# or payments.plans.get_pay_as_you_go_price_config(...)  (sync; uses cached contract address)
credits_config = payments.plans.get_fixed_credits_config(100, 1)

# Register agent + plan
result = payments.agents.register_agent_and_plan(
    agent_metadata, agent_api, plan_metadata, price_config, credits_config
)

# Subscriber: order plan and get token
payments.plans.order_plan(plan_id)
plan_balance = payments.plans.get_plan_balance(plan_id)
print(f"Credits remaining: {plan_balance.balance}")  # PlanBalance.balance is int
# Create the delegation first (provider + currency required), then request the token by delegation_id.
delegation = payments.delegation.create_delegation(
    CreateDelegationPayload(
        provider="erc4337", spending_limit_cents=100, duration_secs=3600, currency="usdc"
    )
)
token_res = payments.x402.get_x402_access_token(
    plan_id, agent_id,
    token_options=X402TokenOptions(
        delegation_config=DelegationConfig(delegation_id=delegation.delegation_id)
    )
)

# Server: verify and settle
verification = payments.facilitator.verify_permissions(
    payment_required=pr, x402_access_token=token, max_amount=str(credits)
)
settlement = payments.facilitator.settle_permissions(
    payment_required=pr, x402_access_token=token, max_amount=str(credits_used)
)

# Helpers
from payments_py.x402.helpers import build_payment_required
from payments_py.x402.fastapi import PaymentMiddleware
from payments_py.x402.strands import requires_payment

# A2A server
from payments_py.a2a.agent_card import build_payment_agent_card
from payments_py.a2a.server import PaymentsA2AServer
agent_card = build_payment_agent_card(base_card, { ... })
server = PaymentsA2AServer.start(agent_card=agent_card, executor=executor, payments_service=payments, port=3005)
# A2A client
client = payments.a2a.get_client(agent_base_url=url, agent_id=agent_id, plan_id=plan_id)

x402 Payment Headers

All x402 v2 integrations use these three HTTP headers:

The payment-required payload structure:

{
  "x402Version": 2,
  "resource": { "url": "/api/endpoint" },
  "accepts": [{
    "scheme": "nvm:erc4337",
    "network": "eip155:84532",
    "planId": "",
    "extra": { "agentId": "" }
  }],
  "extensions": {}
}

Supported x402 schemes

The SDK auto-resolves the scheme from the plan's priceConfig metadata. You only need to pass scheme explicitly if you want to override it.

Payment Plan Types

Nevermined supports several plan types:

• Credits-based: prepaid balance, deducted per request (most common for APIs). Use getFixedCreditsConfig or getDynamicCreditsConfig.
• Time-based: access for a fixed duration (e.g., 30 days unlimited). Use getExpirableDurationConfig.
• Pay-as-you-go (PAYG): one credit granted and burned per purchase — clients re-purchase before each call. Use getPayAsYouGoPriceConfig + getPayAsYouGoCreditsConfig.
• Trial: free limited access, one-time claim per user. Use getFreePriceConfig.
• Hybrid: combine fixed credits with a time expiry by passing accessLimit: 'time' and an expirable duration config.

Each plan can be priced in crypto (getERC20PriceConfig, getEURCPriceConfig, getNativeTokenPriceConfig) or fiat (getFiatPriceConfig — Stripe / Braintree / Visa Trusted Agent). The selected price helper determines the x402 scheme used at runtime.

For fiat plans, the active provider is selected per plan via the fiatPaymentProvider metadata field ('stripe', 'braintree', or 'visa'). Sellers using Braintree must connect a Braintree merchant account with at least one child merchant account in the plan's currency. Sellers offering Visa Trusted Agent plans must complete Stripe Connect onboarding (Visa delegations settle through Stripe Connect) — see braintree-onboarding for the Braintree seller setup and card-enrollment for the buyer-side flow.

Visa caveat for SDK builders. Visa delegation creation is browser-only — it requires consumerPrompt + assuranceData produced by an in-browser WebAuthn ceremony embedded by Visa VTS. The SDK can consume an existing Visa delegation by passing its delegationId to DelegationConfig, but calling createDelegation / create_delegation with provider: 'visa' is rejected by the backend (BCK.VISA.0014). For any SDK code path that needs a Visa delegation, instruct the user to create it in the Nevermined webapp and pass the resulting ID back to the agent.

See references/payment-plans.md for plan registration code.

Common Patterns

Express.js — Fixed credits per route

import { paymentMiddleware } from '@nevermined-io/payments/express'

app.use(paymentMiddleware(payments, {
  'POST /ask': { planId: PLAN_ID, credits: 1 },
  'POST /generate': { planId: PLAN_ID, credits: 5 }
}))

FastAPI — Fixed credits per route

from payments_py.x402.fastapi import PaymentMiddleware

app.add_middleware(
    PaymentMiddleware,
    payments=payments,
    routes={
        "POST /ask": {"plan_id": PLAN_ID, "credits": 1},
        "POST /generate": {"plan_id": PLAN_ID, "credits": 5}
    }
)

Express.js — Dynamic credits based on response

paymentMiddleware(payments, {
  'POST /generate': {
    planId: PLAN_ID,
    credits: (req, res) => {
      const tokens = res.locals.tokenCount || 100
      return Math.ceil(tokens / 100)
    }
  }
})

FastAPI — Dynamic credits based on request

async def calculate_credits(request: Request) -> int:
    body = await request.json()
    max_tokens = body.get("max_tokens", 100)
    return max(1, max_tokens // 100)

app.add_middleware(
    PaymentMiddleware,
    payments=payments,
    routes={"POST /generate": {"plan_id": PLAN_ID, "credits": calculate_credits}}
)

MCP Server — Register tool with paywall

payments.mcp.registerTool(
  "weather.today",
  { title: "Today's Weather", inputSchema: z.object({ city: z.string() }) },
  async (args, extra, context) => ({
    content: [{ type: "text", text: `Weather in ${args.city}: Sunny, 25C` }]
  }),
  { credits: 5n }
)

const { info, stop } = await payments.mcp.start({
  port: 3000,
  agentId: process.env.NVM_AGENT_ID!,
  serverName: "my-server"
})

Strands Agent — Decorator-based payment

from strands import Agent, tool
from payments_py.x402.strands import requires_payment

@tool(context=True)
@requires_payment(payments=payments, plan_id=PLAN_ID, credits=1)
def analyze_data(query: str, tool_context=None) -> dict:
    return {"status": "success", "content": [{"text": f"Analysis: {query}"}]}

agent = Agent(tools=[analyze_data])

Google A2A — Agent server with payment extension

TypeScript

const agentCard = payments.a2a.buildPaymentAgentCard(baseAgentCard, {
  paymentType: "dynamic",
  credits: 1,
  planId: process.env.NVM_PLAN_ID!,
  agentId: process.env.NVM_AGENT_ID!,