nevermined-io · aaitor · Feb 12, 2026 · Feb 12, 2026 · Feb 12, 2026 · Copilot
@@ -381,6 +381,7 @@ Before finalizing any documentation:
 - **Structure**: Overview → Setup → Method details → Examples → Error handling
 - **Tone**: Technical and precise
 - **Examples**: [api-reference/introduction.mdx](docs/api-reference/introduction.mdx)
+- **Source of Documentation**: All the documentation included in the "docs/api-reference" folder is sourced from different repositories. Don't modify it directly.
 
 ### 5. Integration Guides
 
@@ -578,6 +579,7 @@ description: "Register AI agents and create payment plans in 5 minutes using the
 - Link to broken or non-existent pages
 - Forget both TypeScript and Python examples
 - Write overly long paragraphs
+- Modify the "docs/api-reference/" folder documentation, that is sourced from different repos
 
 ---
 

@@ -50,13 +50,13 @@ nvm plans get-plans
 ### 3. Get Plan Details
 
 ```bash
-nvm plans get did:nvm:abc123
+nvm plans get-plan did:nvm:abc123
 ```
 
 ### 4. Get X402 Access Token
 
 ```bash
-nvm x402 get-token did:nvm:plan123
+nvm x402token get-x402-access-token did:nvm:plan123
 ```
 
 ## Usage
@@ -65,10 +65,10 @@ nvm x402 get-token did:nvm:plan123
 nvm [COMMAND]
 
 TOPICS
-  agents   Manage AI agents
-  config   Manage CLI configuration
-  plans    Manage payment plans
-  x402     X402 protocol operations
+  agents      Manage AI agents
+  config      Manage CLI configuration
+  plans       Manage payment plans
+  x402token   X402 protocol operations
 
 COMMANDS
   help     Display help for nvm
@@ -126,18 +126,19 @@ nvm plans get-plans --format quiet
 ### Plan Commands
 
 - `nvm plans get-plans` - List all payment plans
-- `nvm plans get <planId>` - Get details of a specific plan
-- `nvm plans register` - Register a new payment plan (see help for options)
+- `nvm plans get-plan <planId>` - Get details of a specific plan
+- `nvm plans register-credits-plan` - Register a new credits-based payment plan
+- `nvm plans register-time-plan` - Register a new time-based payment plan
 
 ### Agent Commands
 
-- `nvm agents list` - List all AI agents
-- `nvm agents get <agentId>` - Get details of a specific agent
-- `nvm agents register` - Register a new AI agent
+- `nvm agents get-agent <agentId>` - Get details of a specific agent
+- `nvm agents register-agent` - Register a new AI agent
+- `nvm agents get-agent-plans <agentId>` - Get plans associated with an agent
 
 ### X402 Commands
 
-- `nvm x402 get-token <planId>` - Get an X402 access token for a plan
+- `nvm x402token get-x402-access-token <planId>` - Get an X402 access token for a plan
 
 ## Examples
 
@@ -148,10 +149,10 @@ nvm plans get-plans --format quiet
 nvm config init
 
 # Get X402 token for a plan
-nvm x402 get-token did:nvm:abc123 --format json
+nvm x402token get-x402-access-token did:nvm:abc123 --format json
 
 # Get plan details
-nvm plans get did:nvm:abc123
+nvm plans get-plan did:nvm:abc123
 ```
 
 ### Using JSON Config Files

@@ -27,10 +27,21 @@ Choose your AI coding tool below for step-by-step installation instructions.
   <Tab title="Claude Code">
     ### Claude Code
 
-    **One-command install** from the Nevermined repository:
+    **Commands to install** from the Nevermined repository:
 
     ```bash
-    claude /install-skill https://github.com/nevermined-io/docs skills/nevermined-payments
+    mkdir -p ~/.claude/skills
+
+    tmpdir="$(mktemp -d)"
+    git clone --depth 1 --filter=blob:none --sparse https://github.com/nevermined-io/docs "$tmpdir"
+    cd "$tmpdir"
+    git sparse-checkout set skills/nevermined-payments
+
+    cp -R skills/nevermined-payments ~/.claude/skills/
+
+    cd -
+    rm -rf "$tmpdir"
+
     ```
 
     This downloads the `SKILL.md` and all reference files into your local Claude Code skills directory. Claude Code automatically loads the skill when it's relevant to your work.

@@ -6,7 +6,7 @@ icon: "magnifying-glass"
 
 Once a Payment Plan is purchased, user(s) can query all the AI Agents linked to that plan.
 
-For identifying the user as a valid subscriber, they need to send HTTP requests to the AI Agent via a Nevermined Proxy instance and include a valid **Access Token**. This is sent using the standard **HTTP Authorization header**.
+For identifying the user as a valid subscriber, they need to send HTTP requests to the AI Agent and include a valid **Access Token**. This is sent using the **`payment-signature`** HTTP header (per the x402 protocol).
 
 <Info>
   Nevermined Proxy instances are **standard HTTP Proxies** in charge of **authorizing users** trying to access AI Agents or Services.

@@ -128,12 +128,11 @@ For operations with variable costs, use the x402 flow:
     # Use in settlement
     cost = calculate_cost(request)
 
-    await facilitator.settle(payment_payload, PaymentRequirements(
-        plan_id=PLAN_ID,
-        agent_id=AGENT_ID,
-        max_amount=cost,
-        extra={'subscriber_address': address}
-    ))
+    await payments.facilitator.settle_permissions(
+        payment_required=payment_required,
+        x402_access_token=access_token,
+        max_amount=str(cost)
+    )
     ```
   </Tab>
 </Tabs>

@@ -88,8 +88,7 @@ If you already have a Google A2A agent, or you are building a new one, add the P
   </Tab>
   <Tab title="Python">
     ```python
-    from payments_py import Payments
-    from payments_py.common.types import PaymentOptions
+    from payments_py import Payments, PaymentOptions
 
     payments = Payments.get_instance(
         PaymentOptions(nvm_api_key="<YOUR_API_KEY>", environment="sandbox")
@@ -364,8 +363,7 @@ sequenceDiagram
   <Tab title="Python">
     ```python
     import httpx
-    from payments_py import Payments
-    from payments_py.common.types import PaymentOptions
+    from payments_py import Payments, PaymentOptions
 
     payments = Payments.get_instance(
         PaymentOptions(nvm_api_key="<SUBSCRIBER_API_KEY>", environment="sandbox")

@@ -15,7 +15,7 @@ Nevermined Payments Library provides robust tools to add a paywall to your [Mode
 
 The integration is designed to be seamless, whether you are using a high-level framework like the official MCP SDKs or a custom low-level JSON-RPC router.
 
-- **Paywall Protection**: Wrap your handlers with `withPaywall` to automatically verify `Authorization` tokens and check for valid subscriptions.
+- **Paywall Protection**: Wrap your handlers with `withPaywall` to automatically verify payment tokens and check for valid subscriptions.
 - **Credit Burning**: Automatically burn credits after a successful API call, with support for both fixed and dynamic costs.
 - **Declarative Registration**: Use the `attach` method to register and protect your tools in a single, clean step.
 - **Framework Agnostic**: Works with both high-level servers (like the official TypeScript SDK's `McpServer` or Python's `FastMCP`) and custom low-level ASGI/Express routers.
@@ -34,7 +34,7 @@ Think of MCP as a universal language that allows any AI agent to ask a server, "
 
 While MCP provides a powerful standard for *what* an AI agent can do, it doesn't specify *who* is allowed to do it or *how* those services are paid for. This is where Nevermined Payments Library comes in. By integrating Nevermined, you can transform your open MCP server into a secure, monetizable platform.
 
-The core idea is to place a "paywall" in front of your MCP handlers. This paywall acts as a gatekeeper, intercepting every incoming request to a tool, resource, or prompt. Before executing your logic, it checks the user's `Authorization` header to verify they have a valid subscription and sufficient credits through the Nevermined protocol. If they don't, the request is blocked. If they do, the request proceeds, and after your handler successfully completes, the paywall automatically deducts the configured number of credits.
+The core idea is to place a "paywall" in front of your MCP handlers. This paywall acts as a gatekeeper, intercepting every incoming request to a tool, resource, or prompt. Before executing your logic, it checks the user's payment token to verify they have a valid subscription and sufficient credits through the Nevermined protocol. If they don't, the request is blocked. If they do, the request proceeds, and after your handler successfully completes, the paywall automatically deducts the configured number of credits.
 
 This integration allows you to build a sustainable business model around your AI services. You can offer different subscription tiers (plans), charge dynamically based on usage, and maintain a complete audit trail of every transaction, all without cluttering your core application logic with complex payment code.
 
@@ -351,12 +351,11 @@ Initialize the Nevermined Payments SDK with your builder/agent owner API key and
   <Tab title="Python">
     ```python
     # payments_setup.py
-    from payments_py.payments import Payments
+    from payments_py import Payments, PaymentOptions
 
-    payments = Payments({
-        "nvm_api_key": os.environ["NVM_API_KEY"],
-        "environment": os.environ.get("NVM_ENV", "sandbox"),
-    })
+    payments = Payments.get_instance(
+        PaymentOptions(nvm_api_key=os.environ["NVM_API_KEY"], environment=os.environ.get("NVM_ENV", "sandbox"))
+    )
     ```
   </Tab>
 </Tabs>

@@ -93,11 +93,17 @@ session_key = token_res["accessToken"]
 - Facilitator verification + settlement (merchant):
 
 ```python
-verify = await facilitator.verify(payment_payload, requirements)
-if not verify.is_valid:
+verification = payments.facilitator.verify_permissions(
+    payment_required=payment_required,
+    x402_access_token=access_token,
+)
+if not verification.is_valid:
     raise Exception("Payment Required")
 
-await facilitator.settle(payment_payload, requirements)
+payments.facilitator.settle_permissions(
+    payment_required=payment_required,
+    x402_access_token=access_token,
+)
 ```
 
 ## When to use this pattern

@@ -224,12 +224,11 @@ Charge variable amounts based on request complexity. The x402 `max_amount` field
     )
 
     # During settlement, specify actual amount
-    await facilitator.settle(payment_payload, PaymentRequirements(
-        plan_id=plan_id,
-        agent_id=agent_id,
-        max_amount=actual_credits_used,  # 1-10 based on request
-        extra={'subscriber_address': address}
-    ))
+    await payments.facilitator.settle_permissions(
+        payment_required=payment_required,
+        x402_access_token=access_token,
+        max_amount=str(actual_credits_used),  # 1-10 based on request
+    )
     ```
   </Tab>
 </Tabs>