Add missing max_amount parameter to settle_permissions in AP2 integration docs

CLAUDE.md

@@ -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
 
 ---
 

docs/api-reference/cli/index.md

@@ -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

docs/development-guide/build-using-nvm-skill.mdx

@@ -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.

docs/development-guide/query-agents.mdx

@@ -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.

docs/integrate/patterns/charge-credits.mdx

@@ -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>

docs/integrations/google-a2a.mdx

@@ -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")

docs/integrations/mcp.mdx

@@ -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>

docs/integrations/nevermined-x402-ap2.mdx

@@ -1,23 +1,23 @@
 ---
 title: "Nevermined x402 and Google AP2"
 description: "Run the ADK demo to combine Nevermined x402 payments with Google AP2/A2A messaging—covering session tokens, facilitator verify/settle, and AP2 payment intents."
 icon: "sparkles"
 ---
 
 This guide shows how the ADK demo wires Nevermined x402 payments into Google AP2/A2A messaging. It reuses the core primitives (plan + agent + session token + facilitator) and transports them over AP2 messages between a client agent and a merchant server. Source: [ADK demo README](https://github.com/nevermined-io/a2a-x402/tree/feat/a2a-nvm/python/examples/adk-demo#readme).
 
 ## What this covers
 
 - Uses the `python/examples/adk-demo` from `a2a-x402` ([demo repo](https://github.com/nevermined-io/a2a-x402/tree/feat/a2a-nvm))
 - Client agent (subscriber) generates x402 session tokens
 - Merchant server verifies and settles via Nevermined facilitator over REST
 - AP2 carries `payment-required` and `payment-submitted` messages between agents
 - Real on-chain credit burns on Base Sepolia (sandbox)
 
 ## Prerequisites
 
 - Nevermined API keys: one for the merchant (`NVM_API_KEY_SERVER`), one for the subscriber (`NVM_API_KEY_CLIENT`)
 - A credits plan and agent registered in Nevermined (`NVM_CREDITS_PLAN_ID`, `NVM_AGENT_ID`)
 - Python 3.11+, `uv` (for the demo env)
 - Google GenAI API key (for the AP2/ADK flow)
 
@@ -46,9 +46,9 @@
 Key roles (from the README):
 
 - **Client Agent (subscriber)**: Generates x402 session tokens using `payments_py`.
 - **Merchant Server (agent)**: Serves AP2 `payment-required`, verifies/settles via Nevermined facilitator.
 - **Facilitator**: Nevermined service that enforces permissions and burns/orders credits.
 - **Blockchain**: Executes the settlement transactions (Base Sepolia in sandbox).
 
 ## Run it
 
@@ -67,21 +67,21 @@
 3) In the UI, trigger a purchase (e.g., “buy a laptop”). The flow:
 
 - Merchant replies with AP2 `payment-required` (plan/agent/amount/network)
 - Client **generates x402 session token** via Nevermined (`payments_py.x402.get_x402_access_token`)
 - Client sends `payment-submitted` carrying the x402 payload + Nevermined extension
 - Merchant **verifies** with facilitator → does the work → **settles** (burns credits)
 - Response includes receipt + transaction hash; balance decrements (e.g., 10 → 8)
 
 ## Message shapes (adapted from the README)
 
 - `payment-required`:
   - Includes plan_id, agent_id, amount, network, scheme, and any metadata the merchant wants to expose.
 - `payment-submitted`:
   - Carries the x402 payload with `session_key` plus the copied Nevermined extension.
 - `payment-completed`:
   - Contains the facilitator’s verification/settlement result and transaction hash.
 
 ## Key SDK touchpoints
 
 - Session token generation (subscriber):
 
@@ -93,18 +93,26 @@
 - 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)
+# Process request and settle credits
+payments.facilitator.settle_permissions(
+    payment_required=payment_required,
+    x402_access_token=access_token,
+    max_amount="2"  # Credits to burn (matches NVM_PAYMENT_AMOUNT from config)
+)
 ```
 
 ## When to use this pattern
 
 - You need AP2/A2A messaging but want enforceable on-chain payments
 - You want to keep REST facilitators for verification/settlement while agents talk over AP2
 - You need a working reference with real settlement (Base Sepolia) that mirrors the library E2E tests
 
 ## Links
 

docs/products/x402-facilitator/payment-models.mdx

@@ -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>