{ "schemaVersion": "1.0", "item": { "slug": "nevermined-payments", "name": "Nevermined Payments", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/aaitor/nevermined-payments", "canonicalUrl": "https://clawhub.ai/aaitor/nevermined-payments", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/nevermined-payments", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=nevermined-payments", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "references/a2a-integration.md", "references/client-integration.md", "references/express-integration.md", "references/fastapi-integration.md", "references/mcp-paywall.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/nevermined-payments" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/nevermined-payments", "agentPageUrl": "https://openagent3.xyz/skills/nevermined-payments/agent", "manifestUrl": "https://openagent3.xyz/skills/nevermined-payments/agent.json", "briefUrl": "https://openagent3.xyz/skills/nevermined-payments/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Overview", "body": "Nevermined provides financial rails for AI agents — real-time monetization, access control, and payments. This skill gives you everything needed to:\n\nProtect API endpoints with the x402 payment protocol\nCharge per-request using credit-based billing\nIntegrate with Express.js, FastAPI, Strands agents, MCP servers, or Google A2A agents\nSupport subscriber-side flows (purchase plans, generate tokens, call protected APIs)\nEnable agent-to-agent payments via the Google A2A protocol\n\nThe x402 protocol uses HTTP 402 responses to advertise payment requirements. Clients acquire an access token and retry the request. The server verifies permissions, executes the workload, then settles (burns credits)." }, { "title": "Quick Start Checklist", "body": "Get an API key at nevermined.app → Settings → API Keys\nInstall the SDK (npm install @nevermined-io/payments or pip install payments-py)\nRegister your agent and plan (via the App UI or programmatically — see references/payment-plans.md)\nAdd payment protection to your routes/tools (see framework-specific references below)\nTest — call without token (expect 402), then with token (expect 200)" }, { "title": "Environment Setup", "body": "VariableRequiredDescriptionNVM_API_KEYYesYour Nevermined API key (get it at nevermined.app → Settings → API Keys)NVM_ENVIRONMENTYessandbox for testing, live for productionNVM_PLAN_IDYesThe plan ID from registrationNVM_AGENT_IDSometimesRequired for MCP servers and plans with multiple agentsBUILDER_ADDRESSFor registrationWallet address to receive payments" }, { "title": ".env Template", "body": "# Required\nNVM_API_KEY=your-api-key-here\nNVM_ENVIRONMENT=sandbox\nNVM_PLAN_ID=your-plan-id-here\n\n# Required for MCP servers or multi-agent plans\nNVM_AGENT_ID=your-agent-id-here\n\n# Required for registration\nBUILDER_ADDRESS=0xYourWalletAddress" }, { "title": "Prerequisites", "body": "TypeScript/Express.js: Node.js 18+. Your package.json must include \"type\": \"module\" for the @nevermined-io/payments/express subpath import to work.\nPython/FastAPI: Python 3.9+. Install with pip install payments-py[fastapi] — the [fastapi] extra is required for the middleware." }, { "title": "TypeScript", "body": "npm install @nevermined-io/payments\n\nimport { Payments } from '@nevermined-io/payments'\n\nconst payments = Payments.getInstance({\n nvmApiKey: process.env.NVM_API_KEY!,\n environment: 'sandbox'\n})" }, { "title": "Python", "body": "pip install payments-py\n\nimport os\nfrom payments_py import Payments, PaymentOptions\n\npayments = Payments.get_instance(\n PaymentOptions(\n nvm_api_key=os.environ[\"NVM_API_KEY\"],\n environment=\"sandbox\"\n )\n)" }, { "title": "Core Workflow (All Integrations)", "body": "Every Nevermined payment integration follows this 5-step pattern:\n\nClient sends request without a payment token\nServer returns 402 with payment-required header (base64-encoded JSON with plan info)\nClient acquires x402 token via payments.x402.getX402AccessToken(planId, agentId)\nClient retries with payment-signature header containing the token\nServer verifies → executes → settles (burns credits), returns response with payment-response header" }, { "title": "Framework Decision Tree", "body": "Choose the integration that matches your stack:\n\nFrameworkLanguageReferenceKey ImportExpress.jsTypeScript/JSreferences/express-integration.mdpaymentMiddleware from @nevermined-io/payments/expressFastAPIPythonreferences/fastapi-integration.mdPaymentMiddleware from payments_py.x402.fastapiStrands AgentPythonreferences/strands-integration.md@requires_payment from payments_py.x402.strandsMCP ServerTypeScriptreferences/mcp-paywall.mdpayments.mcp.start() / payments.mcp.registerTool()Google A2ATS / Pythonreferences/a2a-integration.mdpayments.a2a.start() / payments.a2a.buildPaymentAgentCard()Any HTTPAnyreferences/x402-protocol.mdManual verify/settle via facilitator APIClient-sideTS / Pythonreferences/client-integration.mdpayments.x402.getX402AccessToken()" }, { "title": "TypeScript (@nevermined-io/payments)", "body": "// Initialize\nconst payments = Payments.getInstance({ nvmApiKey, environment })\n\n// Register agent + plan\nconst { agentId, planId } = await payments.agents.registerAgentAndPlan(\n agentMetadata, agentApi, planMetadata, priceConfig, creditsConfig\n)\n\n// Subscriber: order plan and get token\nawait payments.plans.orderPlan(planId)\nconst balance = await payments.plans.getPlanBalance(planId)\nconst { accessToken } = await payments.x402.getX402AccessToken(planId, agentId)\n\n// Server: verify and settle\nconst verification = await payments.facilitator.verifyPermissions({\n paymentRequired, x402AccessToken: token, maxAmount: BigInt(credits)\n})\nconst settlement = await payments.facilitator.settlePermissions({\n paymentRequired, x402AccessToken: token, maxAmount: BigInt(creditsUsed)\n})\n\n// Helpers\nimport { buildPaymentRequired } from '@nevermined-io/payments'\nimport { paymentMiddleware, X402_HEADERS } from '@nevermined-io/payments/express'\n\n// MCP server\npayments.mcp.registerTool(name, config, handler, { credits: 5n })\nconst { info, stop } = await payments.mcp.start({ port, agentId, serverName })\n\n// A2A server\nconst agentCard = payments.a2a.buildPaymentAgentCard(baseCard, { paymentType, credits, planId, agentId })\nconst server = await payments.a2a.start({ port, basePath: '/a2a/', agentCard, executor })\n// A2A client\nconst client = payments.a2a.getClient({ agentBaseUrl, agentId, planId })\nawait client.sendMessage(\"Hello\", accessToken)" }, { "title": "Python (payments-py)", "body": "# Initialize\npayments = Payments.get_instance(PaymentOptions(nvm_api_key=key, environment=\"sandbox\"))\n\n# Register agent + plan\nresult = payments.agents.register_agent_and_plan(\n agent_metadata, agent_api, plan_metadata, price_config, credits_config\n)\n\n# Subscriber: order plan and get token\npayments.plans.order_plan(plan_id)\nbalance = payments.plans.get_plan_balance(plan_id)\ntoken_res = payments.x402.get_x402_access_token(plan_id, agent_id)\n\n# Server: verify and settle\nverification = payments.facilitator.verify_permissions(\n payment_required=pr, x402_access_token=token, max_amount=str(credits)\n)\nsettlement = payments.facilitator.settle_permissions(\n payment_required=pr, x402_access_token=token, max_amount=str(credits_used)\n)\n\n# Helpers\nfrom payments_py.x402.helpers import build_payment_required\nfrom payments_py.x402.fastapi import PaymentMiddleware\nfrom payments_py.x402.strands import requires_payment\n\n# A2A server\nfrom payments_py.a2a.agent_card import build_payment_agent_card\nfrom payments_py.a2a.server import PaymentsA2AServer\nagent_card = build_payment_agent_card(base_card, { ... })\nserver = PaymentsA2AServer.start(agent_card=agent_card, executor=executor, payments_service=payments, port=3005)\n# A2A client\nclient = payments.a2a.get_client(agent_base_url=url, agent_id=agent_id, plan_id=plan_id)" }, { "title": "x402 Payment Headers", "body": "All x402 v2 integrations use these three HTTP headers:\n\nHeaderDirectionDescriptionpayment-signatureClient → Serverx402 access tokenpayment-requiredServer → Client (402)Base64-encoded JSON with plan requirementspayment-responseServer → Client (200)Base64-encoded JSON settlement receipt\n\nThe payment-required payload structure:\n\n{\n \"x402Version\": 2,\n \"accepts\": [{\n \"scheme\": \"nvm:erc4337\",\n \"network\": \"eip155:84532\",\n \"planId\": \"\",\n \"extra\": { \"agentId\": \"\" }\n }]\n}" }, { "title": "Payment Plan Types", "body": "Nevermined supports several plan types:\n\nCredits-based: prepaid balance, deducted per request (most common for APIs)\nTime-based: access for a fixed duration (e.g., 30 days unlimited)\nPay-as-you-go (PAYG): settle in USDC per request, no credit balance\nTrial: free limited access, one-time claim per user\nHybrid: combine credits with time expiry\n\nSee references/payment-plans.md for plan registration code." }, { "title": "Express.js — Fixed credits per route", "body": "import { paymentMiddleware } from '@nevermined-io/payments/express'\n\napp.use(paymentMiddleware(payments, {\n 'POST /ask': { planId: PLAN_ID, credits: 1 },\n 'POST /generate': { planId: PLAN_ID, credits: 5 }\n}))" }, { "title": "FastAPI — Fixed credits per route", "body": "from payments_py.x402.fastapi import PaymentMiddleware\n\napp.add_middleware(\n PaymentMiddleware,\n payments=payments,\n routes={\n \"POST /ask\": {\"plan_id\": PLAN_ID, \"credits\": 1},\n \"POST /generate\": {\"plan_id\": PLAN_ID, \"credits\": 5}\n }\n)" }, { "title": "Express.js — Dynamic credits based on response", "body": "paymentMiddleware(payments, {\n 'POST /generate': {\n planId: PLAN_ID,\n credits: (req, res) => {\n const tokens = res.locals.tokenCount || 100\n return Math.ceil(tokens / 100)\n }\n }\n})" }, { "title": "FastAPI — Dynamic credits based on request", "body": "async def calculate_credits(request: Request) -> int:\n body = await request.json()\n max_tokens = body.get(\"max_tokens\", 100)\n return max(1, max_tokens // 100)\n\napp.add_middleware(\n PaymentMiddleware,\n payments=payments,\n routes={\"POST /generate\": {\"plan_id\": PLAN_ID, \"credits\": calculate_credits}}\n)" }, { "title": "MCP Server — Register tool with paywall", "body": "payments.mcp.registerTool(\n \"weather.today\",\n { title: \"Today's Weather\", inputSchema: z.object({ city: z.string() }) },\n async (args, extra, context) => ({\n content: [{ type: \"text\", text: `Weather in ${args.city}: Sunny, 25C` }]\n }),\n { credits: 5n }\n)\n\nconst { info, stop } = await payments.mcp.start({\n port: 3000,\n agentId: process.env.NVM_AGENT_ID!,\n serverName: \"my-server\"\n})" }, { "title": "Strands Agent — Decorator-based payment", "body": "from strands import Agent, tool\nfrom payments_py.x402.strands import requires_payment\n\n@tool(context=True)\n@requires_payment(payments=payments, plan_id=PLAN_ID, credits=1)\ndef analyze_data(query: str, tool_context=None) -> dict:\n return {\"status\": \"success\", \"content\": [{\"text\": f\"Analysis: {query}\"}]}\n\nagent = Agent(tools=[analyze_data])" }, { "title": "Google A2A — Agent server with payment extension", "body": "TypeScript\n\nconst agentCard = payments.a2a.buildPaymentAgentCard(baseAgentCard, {\n paymentType: \"dynamic\",\n credits: 1,\n planId: process.env.NVM_PLAN_ID!,\n agentId: process.env.NVM_AGENT_ID!,\n})\n\nconst server = await payments.a2a.start({\n port: 3005,\n basePath: '/a2a/',\n agentCard,\n executor: new MyExecutor(),\n})\n\nPython\n\nfrom payments_py.a2a.agent_card import build_payment_agent_card\nfrom payments_py.a2a.server import PaymentsA2AServer\n\nagent_card = build_payment_agent_card(base_agent_card, {\n \"paymentType\": \"dynamic\",\n \"credits\": 1,\n \"planId\": os.environ[\"NVM_PLAN_ID\"],\n \"agentId\": os.environ[\"NVM_AGENT_ID\"],\n})\n\nserver = PaymentsA2AServer.start(\n agent_card=agent_card,\n executor=MyExecutor(),\n payments_service=payments,\n port=3005,\n base_path=\"/a2a/\",\n)" }, { "title": "Google A2A — Client sending a paid task", "body": "const client = payments.a2a.getClient({\n agentBaseUrl: 'http://localhost:3005/a2a/',\n agentId: AGENT_ID,\n planId: PLAN_ID,\n})\n\nconst { accessToken } = await payments.x402.getX402AccessToken(PLAN_ID, AGENT_ID)\nconst response = await client.sendMessage(\"Analyze this data\", accessToken)" }, { "title": "Gathering Developer Information Upfront", "body": "When a developer asks you to integrate Nevermined payments, gather ALL required information in a single question before generating code. This avoids multiple back-and-forth interactions.\n\nAsk the developer once for:\n\nFramework: Express.js, FastAPI, MCP server, Strands agent, Google A2A, or generic HTTP?\nRoutes to protect: Which endpoints need payment protection and how many credits each? (e.g., POST /chat = 1 credit, POST /generate = 5 credits)\nPricing model: Fixed credits per request, or dynamic pricing based on request/response parameters?\nNevermined API Key: Do they already have an NVM_API_KEY? If not, direct them to nevermined.app → Settings → API Keys\nPlan ID: Do they already have a NVM_PLAN_ID? If not, do they need a registration script too?\nEnvironment: sandbox (testing) or live (production)?\n\nIf they need plan registration, also ask:\n\nPlan name and description: e.g., \"Starter Plan — 100 API requests\"\nPricing: How much in USDC? (e.g., 10 USDC for 100 credits)\nCredits per plan: Total credits included (e.g., 100)\nBuilder wallet address (BUILDER_ADDRESS): The wallet that receives payments\n\nExample combined prompt to offer the developer:\n\nI need to set up Nevermined payments. Here's my info:\n\nFramework: Express.js\nRoutes: POST /chat (1 credit), POST /summarize (3 credits)\nI need a registration script too\nPlan: \"Starter Plan\", 100 credits for 10 USDC\nEnvironment: sandbox\nMy API key is in the NVM_API_KEY env var\nMy wallet: 0x1234...\n\nWith this information, generate both the registration script and the payment-protected server in a single response." }, { "title": "Using the SDK (Recommended)", "body": "Register your agent and plan programmatically — see references/payment-plans.md for complete code.\n\n// TypeScript\nconst { agentId, planId } = await payments.agents.registerAgentAndPlan(\n { name: 'My Agent', description: 'AI service', tags: ['ai'], dateCreated: new Date() },\n { endpoints: [{ POST: 'https://your-api.com/query' }] },\n { name: 'Starter Plan', description: '100 requests for $10', dateCreated: new Date() },\n payments.plans.getERC20PriceConfig(10_000_000n, USDC_ADDRESS, process.env.BUILDER_ADDRESS!),\n payments.plans.getFixedCreditsConfig(100n, 1n)\n)\n\n# Python\nresult = payments.agents.register_agent_and_plan(\n agent_metadata={'name': 'My Agent', 'description': 'AI service', 'tags': ['ai']},\n agent_api={'endpoints': [{'POST': 'https://your-api.com/query'}]},\n plan_metadata={'name': 'Starter Plan', 'description': '100 requests for $10'},\n price_config=get_erc20_price_config(10_000_000, USDC_ADDRESS, os.environ['BUILDER_ADDRESS']),\n credits_config=get_fixed_credits_config(100, 1)\n)" }, { "title": "Using the Nevermined App (No-Code)", "body": "Go to nevermined.app and sign in\nClick \"My agents\" → register a new agent with metadata and endpoints\nCreate a payment plan: set pricing, credits, and duration\nLink the plan to your agent and publish\nCopy the agentId and planId for your .env file" }, { "title": "Using the CLI", "body": "# 1. Install CLI\nnpm install -g @nevermined-io/cli\n\n# 2. Configure (use sandbox for testing)\nnvm config init --api-key \"$NVM_API_KEY\" --environment sandbox\n\n# 3. Register agent and plan together\nnvm agents register-agent-and-plan \\\n --agent-metadata '{\"name\":\"My Agent\",\"description\":\"AI service\"}' \\\n --agent-api '{\"endpoints\":[{\"POST\":\"https://your-api.com/query\"}]}' \\\n --plan-metadata '{\"name\":\"Starter Plan\",\"description\":\"100 requests\"}' \\\n --price-config '{\"tokenAddress\":\"0x036CbD53842c5426634e7929541eC2318f3dCF7e\",\"price\":10000000,\"amountOfCredits\":100}' \\\n --credits-config '{\"minCreditsRequired\":1,\"minCreditsToCharge\":1,\"maxCreditsToCharge\":10}'\n\n# 4. List your plans\nnvm plans get-plans\n\n# 5. As a subscriber: order a plan and get an x402 token\nnvm plans order-plan $PLAN_ID\nnvm x402token get-x402-access-token $PLAN_ID --agent-id $AGENT_ID\n\n# 6. Test against your running server\ncurl -X POST http://localhost:3000/chat \\\n -H \"Content-Type: application/json\" \\\n -H \"payment-signature: $TOKEN\" \\\n -d '{\"message\": \"Hello\"}'" }, { "title": "Troubleshooting", "body": "SymptomCauseFixHTTP 402 returnedNo payment-signature header or invalid/expired tokenGenerate a fresh token via getX402AccessTokenMCP error -32003Payment Required — no token, invalid token, or insufficient creditsCheck subscriber has purchased plan and has credits remainingMCP error -32002Server misconfigurationVerify NVM_API_KEY, NVM_PLAN_ID, and NVM_AGENT_ID are set correctlyverification.isValid is falseToken expired, wrong plan, or insufficient creditsRe-order the plan or generate a new tokenCredits not deductingSettlement not called after requestEnsure you call settlePermissions after processing (middleware does this automatically)payment-required header missingServer not returning 402 properlyUse buildPaymentRequired() helper or framework middleware" }, { "title": "Additional Resources", "body": "Documentation: nevermined.ai/docs\nNevermined App: nevermined.app — register agents, create plans, manage subscriptions\nMCP Search Server: https://docs.nevermined.app/mcp — search Nevermined docs from any MCP client\nTutorials: github.com/nevermined-io/tutorials\nDiscord: discord.com/invite/GZju2qScKq\nTypeScript SDK: @nevermined-io/payments on npm\nPython SDK: payments-py on PyPI" } ], "body": "Nevermined Payments Integration\nOverview\n\nNevermined provides financial rails for AI agents — real-time monetization, access control, and payments. This skill gives you everything needed to:\n\nProtect API endpoints with the x402 payment protocol\nCharge per-request using credit-based billing\nIntegrate with Express.js, FastAPI, Strands agents, MCP servers, or Google A2A agents\nSupport subscriber-side flows (purchase plans, generate tokens, call protected APIs)\nEnable agent-to-agent payments via the Google A2A protocol\n\nThe x402 protocol uses HTTP 402 responses to advertise payment requirements. Clients acquire an access token and retry the request. The server verifies permissions, executes the workload, then settles (burns credits).\n\nQuick Start Checklist\nGet an API key at nevermined.app → Settings → API Keys\nInstall the SDK (npm install @nevermined-io/payments or pip install payments-py)\nRegister your agent and plan (via the App UI or programmatically — see references/payment-plans.md)\nAdd payment protection to your routes/tools (see framework-specific references below)\nTest — call without token (expect 402), then with token (expect 200)\nEnvironment Setup\nVariable\tRequired\tDescription\nNVM_API_KEY\tYes\tYour Nevermined API key (get it at nevermined.app → Settings → API Keys)\nNVM_ENVIRONMENT\tYes\tsandbox for testing, live for production\nNVM_PLAN_ID\tYes\tThe plan ID from registration\nNVM_AGENT_ID\tSometimes\tRequired for MCP servers and plans with multiple agents\nBUILDER_ADDRESS\tFor registration\tWallet address to receive payments\n.env Template\n# Required\nNVM_API_KEY=your-api-key-here\nNVM_ENVIRONMENT=sandbox\nNVM_PLAN_ID=your-plan-id-here\n\n# Required for MCP servers or multi-agent plans\nNVM_AGENT_ID=your-agent-id-here\n\n# Required for registration\nBUILDER_ADDRESS=0xYourWalletAddress\n\nPrerequisites\nTypeScript/Express.js: Node.js 18+. Your package.json must include \"type\": \"module\" for the @nevermined-io/payments/express subpath import to work.\nPython/FastAPI: Python 3.9+. Install with pip install payments-py[fastapi] — the [fastapi] extra is required for the middleware.\nTypeScript\nnpm install @nevermined-io/payments\n\nimport { Payments } from '@nevermined-io/payments'\n\nconst payments = Payments.getInstance({\n nvmApiKey: process.env.NVM_API_KEY!,\n environment: 'sandbox'\n})\n\nPython\npip install payments-py\n\nimport os\nfrom payments_py import Payments, PaymentOptions\n\npayments = Payments.get_instance(\n PaymentOptions(\n nvm_api_key=os.environ[\"NVM_API_KEY\"],\n environment=\"sandbox\"\n )\n)\n\nCore Workflow (All Integrations)\n\nEvery Nevermined payment integration follows this 5-step pattern:\n\nClient sends request without a payment token\nServer returns 402 with payment-required header (base64-encoded JSON with plan info)\nClient acquires x402 token via payments.x402.getX402AccessToken(planId, agentId)\nClient retries with payment-signature header containing the token\nServer verifies → executes → settles (burns credits), returns response with payment-response header\nFramework Decision Tree\n\nChoose the integration that matches your stack:\n\nFramework\tLanguage\tReference\tKey Import\nExpress.js\tTypeScript/JS\treferences/express-integration.md\tpaymentMiddleware from @nevermined-io/payments/express\nFastAPI\tPython\treferences/fastapi-integration.md\tPaymentMiddleware from payments_py.x402.fastapi\nStrands Agent\tPython\treferences/strands-integration.md\t@requires_payment from payments_py.x402.strands\nMCP Server\tTypeScript\treferences/mcp-paywall.md\tpayments.mcp.start() / payments.mcp.registerTool()\nGoogle A2A\tTS / Python\treferences/a2a-integration.md\tpayments.a2a.start() / payments.a2a.buildPaymentAgentCard()\nAny HTTP\tAny\treferences/x402-protocol.md\tManual verify/settle via facilitator API\nClient-side\tTS / Python\treferences/client-integration.md\tpayments.x402.getX402AccessToken()\nSDK Quick Reference\nTypeScript (@nevermined-io/payments)\n// Initialize\nconst payments = Payments.getInstance({ nvmApiKey, environment })\n\n// Register agent + plan\nconst { agentId, planId } = await payments.agents.registerAgentAndPlan(\n agentMetadata, agentApi, planMetadata, priceConfig, creditsConfig\n)\n\n// Subscriber: order plan and get token\nawait payments.plans.orderPlan(planId)\nconst balance = await payments.plans.getPlanBalance(planId)\nconst { accessToken } = await payments.x402.getX402AccessToken(planId, agentId)\n\n// Server: verify and settle\nconst verification = await payments.facilitator.verifyPermissions({\n paymentRequired, x402AccessToken: token, maxAmount: BigInt(credits)\n})\nconst settlement = await payments.facilitator.settlePermissions({\n paymentRequired, x402AccessToken: token, maxAmount: BigInt(creditsUsed)\n})\n\n// Helpers\nimport { buildPaymentRequired } from '@nevermined-io/payments'\nimport { paymentMiddleware, X402_HEADERS } from '@nevermined-io/payments/express'\n\n// MCP server\npayments.mcp.registerTool(name, config, handler, { credits: 5n })\nconst { info, stop } = await payments.mcp.start({ port, agentId, serverName })\n\n// A2A server\nconst agentCard = payments.a2a.buildPaymentAgentCard(baseCard, { paymentType, credits, planId, agentId })\nconst server = await payments.a2a.start({ port, basePath: '/a2a/', agentCard, executor })\n// A2A client\nconst client = payments.a2a.getClient({ agentBaseUrl, agentId, planId })\nawait client.sendMessage(\"Hello\", accessToken)\n\nPython (payments-py)\n# Initialize\npayments = Payments.get_instance(PaymentOptions(nvm_api_key=key, environment=\"sandbox\"))\n\n# Register agent + plan\nresult = payments.agents.register_agent_and_plan(\n agent_metadata, agent_api, plan_metadata, price_config, credits_config\n)\n\n# Subscriber: order plan and get token\npayments.plans.order_plan(plan_id)\nbalance = payments.plans.get_plan_balance(plan_id)\ntoken_res = payments.x402.get_x402_access_token(plan_id, agent_id)\n\n# Server: verify and settle\nverification = payments.facilitator.verify_permissions(\n payment_required=pr, x402_access_token=token, max_amount=str(credits)\n)\nsettlement = payments.facilitator.settle_permissions(\n payment_required=pr, x402_access_token=token, max_amount=str(credits_used)\n)\n\n# Helpers\nfrom payments_py.x402.helpers import build_payment_required\nfrom payments_py.x402.fastapi import PaymentMiddleware\nfrom payments_py.x402.strands import requires_payment\n\n# A2A server\nfrom payments_py.a2a.agent_card import build_payment_agent_card\nfrom payments_py.a2a.server import PaymentsA2AServer\nagent_card = build_payment_agent_card(base_card, { ... })\nserver = PaymentsA2AServer.start(agent_card=agent_card, executor=executor, payments_service=payments, port=3005)\n# A2A client\nclient = payments.a2a.get_client(agent_base_url=url, agent_id=agent_id, plan_id=plan_id)\n\nx402 Payment Headers\n\nAll x402 v2 integrations use these three HTTP headers:\n\nHeader\tDirection\tDescription\npayment-signature\tClient → Server\tx402 access token\npayment-required\tServer → Client (402)\tBase64-encoded JSON with plan requirements\npayment-response\tServer → Client (200)\tBase64-encoded JSON settlement receipt\n\nThe payment-required payload structure:\n\n{\n \"x402Version\": 2,\n \"accepts\": [{\n \"scheme\": \"nvm:erc4337\",\n \"network\": \"eip155:84532\",\n \"planId\": \"\",\n \"extra\": { \"agentId\": \"\" }\n }]\n}\n\nPayment Plan Types\n\nNevermined supports several plan types:\n\nCredits-based: prepaid balance, deducted per request (most common for APIs)\nTime-based: access for a fixed duration (e.g., 30 days unlimited)\nPay-as-you-go (PAYG): settle in USDC per request, no credit balance\nTrial: free limited access, one-time claim per user\nHybrid: combine credits with time expiry\n\nSee references/payment-plans.md for plan registration code.\n\nCommon Patterns\nExpress.js — Fixed credits per route\nimport { paymentMiddleware } from '@nevermined-io/payments/express'\n\napp.use(paymentMiddleware(payments, {\n 'POST /ask': { planId: PLAN_ID, credits: 1 },\n 'POST /generate': { planId: PLAN_ID, credits: 5 }\n}))\n\nFastAPI — Fixed credits per route\nfrom payments_py.x402.fastapi import PaymentMiddleware\n\napp.add_middleware(\n PaymentMiddleware,\n payments=payments,\n routes={\n \"POST /ask\": {\"plan_id\": PLAN_ID, \"credits\": 1},\n \"POST /generate\": {\"plan_id\": PLAN_ID, \"credits\": 5}\n }\n)\n\nExpress.js — Dynamic credits based on response\npaymentMiddleware(payments, {\n 'POST /generate': {\n planId: PLAN_ID,\n credits: (req, res) => {\n const tokens = res.locals.tokenCount || 100\n return Math.ceil(tokens / 100)\n }\n }\n})\n\nFastAPI — Dynamic credits based on request\nasync def calculate_credits(request: Request) -> int:\n body = await request.json()\n max_tokens = body.get(\"max_tokens\", 100)\n return max(1, max_tokens // 100)\n\napp.add_middleware(\n PaymentMiddleware,\n payments=payments,\n routes={\"POST /generate\": {\"plan_id\": PLAN_ID, \"credits\": calculate_credits}}\n)\n\nMCP Server — Register tool with paywall\npayments.mcp.registerTool(\n \"weather.today\",\n { title: \"Today's Weather\", inputSchema: z.object({ city: z.string() }) },\n async (args, extra, context) => ({\n content: [{ type: \"text\", text: `Weather in ${args.city}: Sunny, 25C` }]\n }),\n { credits: 5n }\n)\n\nconst { info, stop } = await payments.mcp.start({\n port: 3000,\n agentId: process.env.NVM_AGENT_ID!,\n serverName: \"my-server\"\n})\n\nStrands Agent — Decorator-based payment\nfrom strands import Agent, tool\nfrom payments_py.x402.strands import requires_payment\n\n@tool(context=True)\n@requires_payment(payments=payments, plan_id=PLAN_ID, credits=1)\ndef analyze_data(query: str, tool_context=None) -> dict:\n return {\"status\": \"success\", \"content\": [{\"text\": f\"Analysis: {query}\"}]}\n\nagent = Agent(tools=[analyze_data])\n\nGoogle A2A — Agent server with payment extension\nTypeScript\nconst agentCard = payments.a2a.buildPaymentAgentCard(baseAgentCard, {\n paymentType: \"dynamic\",\n credits: 1,\n planId: process.env.NVM_PLAN_ID!,\n agentId: process.env.NVM_AGENT_ID!,\n})\n\nconst server = await payments.a2a.start({\n port: 3005,\n basePath: '/a2a/',\n agentCard,\n executor: new MyExecutor(),\n})\n\nPython\nfrom payments_py.a2a.agent_card import build_payment_agent_card\nfrom payments_py.a2a.server import PaymentsA2AServer\n\nagent_card = build_payment_agent_card(base_agent_card, {\n \"paymentType\": \"dynamic\",\n \"credits\": 1,\n \"planId\": os.environ[\"NVM_PLAN_ID\"],\n \"agentId\": os.environ[\"NVM_AGENT_ID\"],\n})\n\nserver = PaymentsA2AServer.start(\n agent_card=agent_card,\n executor=MyExecutor(),\n payments_service=payments,\n port=3005,\n base_path=\"/a2a/\",\n)\n\nGoogle A2A — Client sending a paid task\nconst client = payments.a2a.getClient({\n agentBaseUrl: 'http://localhost:3005/a2a/',\n agentId: AGENT_ID,\n planId: PLAN_ID,\n})\n\nconst { accessToken } = await payments.x402.getX402AccessToken(PLAN_ID, AGENT_ID)\nconst response = await client.sendMessage(\"Analyze this data\", accessToken)\n\nGathering Developer Information Upfront\n\nWhen a developer asks you to integrate Nevermined payments, gather ALL required information in a single question before generating code. This avoids multiple back-and-forth interactions.\n\nAsk the developer once for:\n\nFramework: Express.js, FastAPI, MCP server, Strands agent, Google A2A, or generic HTTP?\nRoutes to protect: Which endpoints need payment protection and how many credits each? (e.g., POST /chat = 1 credit, POST /generate = 5 credits)\nPricing model: Fixed credits per request, or dynamic pricing based on request/response parameters?\nNevermined API Key: Do they already have an NVM_API_KEY? If not, direct them to nevermined.app → Settings → API Keys\nPlan ID: Do they already have a NVM_PLAN_ID? If not, do they need a registration script too?\nEnvironment: sandbox (testing) or live (production)?\n\nIf they need plan registration, also ask:\n\nPlan name and description: e.g., \"Starter Plan — 100 API requests\"\nPricing: How much in USDC? (e.g., 10 USDC for 100 credits)\nCredits per plan: Total credits included (e.g., 100)\nBuilder wallet address (BUILDER_ADDRESS): The wallet that receives payments\n\nExample combined prompt to offer the developer:\n\nI need to set up Nevermined payments. Here's my info:\n\nFramework: Express.js\nRoutes: POST /chat (1 credit), POST /summarize (3 credits)\nI need a registration script too\nPlan: \"Starter Plan\", 100 credits for 10 USDC\nEnvironment: sandbox\nMy API key is in the NVM_API_KEY env var\nMy wallet: 0x1234...\n\nWith this information, generate both the registration script and the payment-protected server in a single response.\n\nAgent and Plan Registration\nUsing the SDK (Recommended)\n\nRegister your agent and plan programmatically — see references/payment-plans.md for complete code.\n\n// TypeScript\nconst { agentId, planId } = await payments.agents.registerAgentAndPlan(\n { name: 'My Agent', description: 'AI service', tags: ['ai'], dateCreated: new Date() },\n { endpoints: [{ POST: 'https://your-api.com/query' }] },\n { name: 'Starter Plan', description: '100 requests for $10', dateCreated: new Date() },\n payments.plans.getERC20PriceConfig(10_000_000n, USDC_ADDRESS, process.env.BUILDER_ADDRESS!),\n payments.plans.getFixedCreditsConfig(100n, 1n)\n)\n\n# Python\nresult = payments.agents.register_agent_and_plan(\n agent_metadata={'name': 'My Agent', 'description': 'AI service', 'tags': ['ai']},\n agent_api={'endpoints': [{'POST': 'https://your-api.com/query'}]},\n plan_metadata={'name': 'Starter Plan', 'description': '100 requests for $10'},\n price_config=get_erc20_price_config(10_000_000, USDC_ADDRESS, os.environ['BUILDER_ADDRESS']),\n credits_config=get_fixed_credits_config(100, 1)\n)\n\nUsing the Nevermined App (No-Code)\nGo to nevermined.app and sign in\nClick \"My agents\" → register a new agent with metadata and endpoints\nCreate a payment plan: set pricing, credits, and duration\nLink the plan to your agent and publish\nCopy the agentId and planId for your .env file\nUsing the CLI\n# 1. Install CLI\nnpm install -g @nevermined-io/cli\n\n# 2. Configure (use sandbox for testing)\nnvm config init --api-key \"$NVM_API_KEY\" --environment sandbox\n\n# 3. Register agent and plan together\nnvm agents register-agent-and-plan \\\n --agent-metadata '{\"name\":\"My Agent\",\"description\":\"AI service\"}' \\\n --agent-api '{\"endpoints\":[{\"POST\":\"https://your-api.com/query\"}]}' \\\n --plan-metadata '{\"name\":\"Starter Plan\",\"description\":\"100 requests\"}' \\\n --price-config '{\"tokenAddress\":\"0x036CbD53842c5426634e7929541eC2318f3dCF7e\",\"price\":10000000,\"amountOfCredits\":100}' \\\n --credits-config '{\"minCreditsRequired\":1,\"minCreditsToCharge\":1,\"maxCreditsToCharge\":10}'\n\n# 4. List your plans\nnvm plans get-plans\n\n# 5. As a subscriber: order a plan and get an x402 token\nnvm plans order-plan $PLAN_ID\nnvm x402token get-x402-access-token $PLAN_ID --agent-id $AGENT_ID\n\n# 6. Test against your running server\ncurl -X POST http://localhost:3000/chat \\\n -H \"Content-Type: application/json\" \\\n -H \"payment-signature: $TOKEN\" \\\n -d '{\"message\": \"Hello\"}'\n\nTroubleshooting\nSymptom\tCause\tFix\nHTTP 402 returned\tNo payment-signature header or invalid/expired token\tGenerate a fresh token via getX402AccessToken\nMCP error -32003\tPayment Required — no token, invalid token, or insufficient credits\tCheck subscriber has purchased plan and has credits remaining\nMCP error -32002\tServer misconfiguration\tVerify NVM_API_KEY, NVM_PLAN_ID, and NVM_AGENT_ID are set correctly\nverification.isValid is false\tToken expired, wrong plan, or insufficient credits\tRe-order the plan or generate a new token\nCredits not deducting\tSettlement not called after request\tEnsure you call settlePermissions after processing (middleware does this automatically)\npayment-required header missing\tServer not returning 402 properly\tUse buildPaymentRequired() helper or framework middleware\nAdditional Resources\nDocumentation: nevermined.ai/docs\nNevermined App: nevermined.app — register agents, create plans, manage subscriptions\nMCP Search Server: https://docs.nevermined.app/mcp — search Nevermined docs from any MCP client\nTutorials: github.com/nevermined-io/tutorials\nDiscord: discord.com/invite/GZju2qScKq\nTypeScript SDK: @nevermined-io/payments on npm\nPython SDK: payments-py on PyPI" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/aaitor/nevermined-payments", "publisherUrl": "https://clawhub.ai/aaitor/nevermined-payments", "owner": "aaitor", "version": "0.1.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/nevermined-payments", "downloadUrl": "https://openagent3.xyz/downloads/nevermined-payments", "agentUrl": "https://openagent3.xyz/skills/nevermined-payments/agent", "manifestUrl": "https://openagent3.xyz/skills/nevermined-payments/agent.json", "briefUrl": "https://openagent3.xyz/skills/nevermined-payments/agent.md" } }