Skip to main content

Nevermined Payments SDK

You are building an application that integrates Nevermined payments. Follow these patterns.

SDK Packages

  • TypeScript: @nevermined-io/payments (npm)
  • Python: payments-py (PyPI)

Environment Variables

Always use these env vars (never hardcode):
  • NVM_API_KEY — Nevermined API key (sandbox:... for sandbox, live:... for production)
  • NVM_ENVIRONMENTsandbox or live
  • NVM_PLAN_ID — payment plan ID
  • NVM_AGENT_ID — agent ID (when plans have multiple agents)

TypeScript Initialization

Python Initialization

Express.js Middleware (TypeScript)

FastAPI Middleware (Python)

Strands Agent Decorator (Python)

MCP Server (TypeScript)

Google A2A (TypeScript / Python)

x402 Headers

  • payment-signature: Client sends x402 access token
  • payment-required: Server sends payment requirements (402 response, base64-encoded)
  • payment-response: Server sends settlement receipt (200 response, base64-encoded)

Key Rules

  • Use verifyPermissions / settlePermissions for manual x402 (not deprecated isValidRequest)
  • Use buildPaymentRequired() (TS) or build_payment_required() (Python) to generate 402 responses
  • Credits are BigInt in TypeScript (1n), int or str in Python
  • Always settle after processing — middleware does this automatically

Autonomous Operations (REST, no SDK)

When an agent must act on its own behalf at runtime (buy a plan, enroll a card, check credits/revenue), call the REST API directly with Authorization: Bearer $NVM_API_KEY against https://api.sandbox.nevermined.app (sandbox) or https://api.live.nevermined.app (live). Buy in two calls — POST /api/v1/x402/permissions (→ accessToken) then POST /api/v1/x402/settle (→ billingModel, creditsRedeemed, remainingBalance, orderTx; on pay-as-you-go the two credit fields are always "0" even on a successful charge, so the proof is success + a non-empty orderTx/transaction). Crypto uses scheme: "nvm:erc4337" / network: "eip155:84532"; cards use scheme: "nvm:card-delegation" / network: "stripe". A human is needed only for one-time setup — the first API key, plus card enrollment if paying by card (the stablecoin path needs neither). Full runbook: skills/nevermined-payments/references/autonomous-operations.md.

Full Skill Reference

See skills/nevermined-payments/SKILL.md (Track A = operate autonomously via REST; Track B = add payments to your code via SDK).