diff --git a/CLAUDE.md b/CLAUDE.md index 865d3c5..0b1a9b6 100644 --- a/CLAUDE.md +++ b/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 --- diff --git a/docs/api-reference/cli/index.md b/docs/api-reference/cli/index.md index 91e0160..2ac76eb 100644 --- a/docs/api-reference/cli/index.md +++ b/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 ` - Get details of a specific plan -- `nvm plans register` - Register a new payment plan (see help for options) +- `nvm plans get-plan ` - 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 ` - Get details of a specific agent -- `nvm agents register` - Register a new AI agent +- `nvm agents get-agent ` - Get details of a specific agent +- `nvm agents register-agent` - Register a new AI agent +- `nvm agents get-agent-plans ` - Get plans associated with an agent ### X402 Commands -- `nvm x402 get-token ` - Get an X402 access token for a plan +- `nvm x402token get-x402-access-token ` - 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 diff --git a/docs/development-guide/build-using-nvm-skill.mdx b/docs/development-guide/build-using-nvm-skill.mdx index d919eab..bfb1968 100644 --- a/docs/development-guide/build-using-nvm-skill.mdx +++ b/docs/development-guide/build-using-nvm-skill.mdx @@ -27,10 +27,21 @@ Choose your AI coding tool below for step-by-step installation instructions. ### 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. diff --git a/docs/development-guide/query-agents.mdx b/docs/development-guide/query-agents.mdx index fdacfa6..a537ee2 100644 --- a/docs/development-guide/query-agents.mdx +++ b/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). Nevermined Proxy instances are **standard HTTP Proxies** in charge of **authorizing users** trying to access AI Agents or Services. diff --git a/docs/integrate/patterns/charge-credits.mdx b/docs/integrate/patterns/charge-credits.mdx index d9df9ee..af9b9fc 100644 --- a/docs/integrate/patterns/charge-credits.mdx +++ b/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) + ) ``` diff --git a/docs/integrations/google-a2a.mdx b/docs/integrations/google-a2a.mdx index 2b43263..a935849 100644 --- a/docs/integrations/google-a2a.mdx +++ b/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 ```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="", environment="sandbox") @@ -364,8 +363,7 @@ sequenceDiagram ```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="", environment="sandbox") diff --git a/docs/integrations/mcp.mdx b/docs/integrations/mcp.mdx index d877765..e12b2c7 100644 --- a/docs/integrations/mcp.mdx +++ b/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 ```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")) + ) ``` diff --git a/docs/integrations/nevermined-x402-ap2.mdx b/docs/integrations/nevermined-x402-ap2.mdx index a93aeae..085e4e8 100644 --- a/docs/integrations/nevermined-x402-ap2.mdx +++ b/docs/integrations/nevermined-x402-ap2.mdx @@ -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 diff --git a/docs/products/x402-facilitator/payment-models.mdx b/docs/products/x402-facilitator/payment-models.mdx index e92ba56..da26e58 100644 --- a/docs/products/x402-facilitator/payment-models.mdx +++ b/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 + ) ```