diff --git a/docs/api-reference/cli/ID_FORMAT_UPDATE.md b/docs/api-reference/cli/ID_FORMAT_UPDATE.md
new file mode 100644
index 00000000..145fdb18
--- /dev/null
+++ b/docs/api-reference/cli/ID_FORMAT_UPDATE.md
@@ -0,0 +1,78 @@
+# CLI Documentation ID Format Update
+
+## Issue
+PR feedback indicates that `planId` and `agentId` examples in documentation use incorrect format.
+
+## Current Format (Incorrect)
+```
+did:nvm:abc123
+did:nvm:plan1
+did:nvm:agent123
+```
+
+## Correct Format (BigInt)
+Plan IDs and Agent IDs are returned as large numeric strings (BigInt format):
+```
+"123456789012345678"
+"987654321098765432"
+```
+
+## Files to Update
+1. cli/docs/getting-started.md
+2. cli/docs/plans.md
+3. cli/docs/agents.md
+4. cli/docs/purchases.md
+5. cli/docs/querying.md
+6. cli/docs/other-commands.md
+7. cli/docs/README.md
+8. cli/docs/TESTING_NPM.md
+
+## Example Replacements
+
+### Plans Documentation
+**Before**:
+```bash
+nevermined plans get-plan did:nvm:abc123
+```
+
+**After**:
+```bash
+nevermined plans get-plan "123456789012345678"
+```
+
+### Agents Documentation
+**Before**:
+```bash
+nevermined agents get-agent did:nvm:agent123
+```
+
+**After**:
+```bash
+nevermined agents get-agent "987654321098765432"
+```
+
+### Variable Assignments
+**Before**:
+```bash
+PLAN_ID="did:nvm:abc123"
+```
+
+**After**:
+```bash
+PLAN_ID="123456789012345678"
+```
+
+## Implementation Strategy
+1. Replace all `did:nvm:abc123` and similar patterns with numeric BigInt strings
+2. Use distinct numbers for different entities to avoid confusion
+3. Keep examples consistent across documentation
+4. Maintain quotes around numeric strings in shell examples
+
+## Standard Example IDs
+- Basic plan: `"123456789012345678"`
+- Pro plan: `"234567890123456789"`
+- Enterprise plan: `"345678901234567890"`
+- Trial plan: `"456789012345678901"`
+- Agent 1: `"987654321098765432"`
+- Agent 2: `"876543210987654321"`
+- Agent 3: `"765432109876543210"`
diff --git a/docs/api-reference/cli/README.md b/docs/api-reference/cli/README.md
new file mode 100644
index 00000000..fc2fcd90
--- /dev/null
+++ b/docs/api-reference/cli/README.md
@@ -0,0 +1,401 @@
+# Nevermined Payments CLI Documentation
+
+Complete documentation for the Nevermined Payments CLI (`nevermined`).
+
+## Overview
+
+The Nevermined Payments CLI is a command-line interface for interacting with the Nevermined Payments Protocol. It enables developers to:
+
+- Create and manage payment plans
+- Register AI agents with pay-per-use billing
+- Purchase and manage subscriptions
+- Query agents using X402 access tokens
+- Verify and settle permissions
+- Manage organizations and members
+
+## Documentation
+
+### Getting Started
+
+**[Getting Started Guide](./getting-started.md)**
+
+Everything you need to install and configure the CLI:
+- Prerequisites and system requirements
+- Getting your NVM API key
+- Installation methods (npm, npx, from source)
+- Configuration setup and profiles
+- Environment selection guide
+- Common installation issues
+
+### Core Functionality
+
+**[Managing Payment Plans](./plans.md)**
+
+Create and manage payment plans for your services:
+- Listing and viewing plans
+- Creating credits-based, time-based, and service plans
+- Updating plan metadata and pricing
+- Checking balances and credits
+- Plan files and transfers
+- Advanced plan operations
+
+**[Managing AI Agents](./agents.md)**
+
+Register and configure AI agents:
+- Listing and viewing agents
+- Registering new agents with payment plans
+- Updating agent metadata and endpoints
+- Managing payment plan associations
+- Agent files and resources
+- Access control configuration
+
+**[Making Purchases](./purchases.md)**
+
+Order plans and manage subscriptions:
+- Ordering payment plans
+- Checking credit balances
+- Managing subscriptions
+- Refilling credits
+- Transaction history and analytics
+- Automated purchasing and budgeting
+
+**[Querying Agents](./querying.md)**
+
+Access agents using X402 tokens:
+- Generating X402 access tokens
+- Making HTTP requests with tokens
+- Verifying and settling requests
+- Complete query workflows
+- Batch queries and rate limiting
+- Monitoring credit usage
+
+**[Other Commands](./other-commands.md)**
+
+Additional CLI features and utilities:
+- Configuration management
+- Facilitator operations (verify/settle)
+- Organization member management
+- X402 token commands
+- Global flags and options
+- Scripting and automation examples
+
+## Quick Links
+
+### Installation
+
+```bash
+# Global installation
+npm install -g @nevermined-io/cli
+
+# Using npx
+npx @nevermined-io/cli --help
+```
+
+### First Steps
+
+```bash
+# Authenticate via browser (recommended)
+nevermined login
+
+# Or initialize configuration manually
+nevermined config init
+
+# List available plans
+nevermined plans get-plans
+
+# Get plan details
+nevermined plans get-plan <plan-id>
+
+# Order a plan
+nevermined plans order-plan <plan-id>
+
+# Get access token
+nevermined x402token get-x402-access-token <plan-id>
+```
+
+### Common Commands
+
+```bash
+# Authentication
+nevermined login                    # Authenticate via browser
+nevermined logout                   # Remove API key from config
+
+# Configuration
+nevermined config init              # Initialize configuration
+nevermined config show              # Display current config
+nevermined config set <key> <value> # Update configuration
+
+# Plans
+nevermined plans get-plans                          # List all plans
+nevermined plans get-plan <plan-id>            # Get plan details
+nevermined plans get-plan-balance <plan-id>    # Check balance
+nevermined plans order-plan <plan-id>          # Purchase plan
+
+# Agents
+nevermined agents get-agent <agent-id>         # Get agent details
+nevermined agents get-agent-plans <agent-id>   # List agent's plans
+nevermined agents register-agent \             # Register new agent
+  --agent-metadata metadata.json \
+  --agent-api "https://api.example.com" \
+  --payment-plans "plan-id-1,plan-id-2"
+
+# X402 Tokens
+nevermined x402token get-x402-access-token <plan-id>  # Get access token
+
+# Organizations
+nevermined organizations get-members                          # List members
+nevermined organizations create-member <user-id>              # Add member
+nevermined organizations connect-stripe-account \             # Connect Stripe
+  --user-email "user@example.com" \
+  --user-country-code "US" \
+  --return-url "https://yourapp.com/callback"
+```
+
+## Global Flags
+
+All commands support these global flags:
+
+- `-f, --format <format>` - Output format: table, json, quiet (default: table)
+- `-p, --profile <profile>` - Configuration profile to use
+- `-v, --verbose` - Verbose output with detailed logging
+- `-h, --help` - Display help for command
+
+## Output Formats
+
+### Table (Default)
+
+Human-readable table output for interactive use:
+
+```bash
+nevermined plans get-plans
+```
+
+### JSON
+
+Machine-readable JSON for scripting:
+
+```bash
+nevermined plans get-plans --format json
+```
+
+### Quiet
+
+Minimal output for automation:
+
+```bash
+nevermined plans get-plans --format quiet
+```
+
+## Configuration Profiles
+
+Use profiles to manage multiple environments:
+
+```bash
+# Create production profile
+nevermined config set profiles.production.nvmApiKey live:eyJxxxxaaaabbbbbbbb
+nevermined config set profiles.production.environment live
+
+# Use production profile
+nevermined --profile production plans get-plans
+
+# Switch active profile
+nevermined config set activeProfile production
+```
+
+## Environment Guide
+
+| Environment | Use Case | Blockchain | Payments |
+|-------------|----------|------------|----------|
+| `sandbox` | Development, testing | Test network | Test credits |
+| `live` | Production | Mainnet | Real payments |
+
+## Examples
+
+### Complete Workflow
+
+```bash
+#!/bin/bash
+# Complete workflow: Setup -> Purchase -> Query
+
+# 1. Initialize configuration
+nevermined config init
+
+# 2. List available plans
+nevermined plans get-plans
+
+# 3. Get plan details
+PLAN_ID="123456789012345678"
+nevermined plans get-plan $PLAN_ID
+
+# 4. Purchase plan
+nevermined plans order-plan $PLAN_ID
+
+# 5. Check balance
+nevermined plans get-plan-balance $PLAN_ID
+
+# 6. Get access token
+TOKEN=$(nevermined x402token get-x402-access-token $PLAN_ID --format json | jq -r '.token')
+
+# 7. Query agent
+curl -H "payment-signature: $TOKEN" https://agent-api.example.com/query
+```
+
+### Agent Registration
+
+```bash
+#!/bin/bash
+# Register an AI agent with payment plan
+
+# 1. Create payment plan
+PLAN_ID=$(nevermined plans register-credits-plan \
+  --plan-metadata plan.json \
+  --price-config price.json \
+  --credits-config credits.json \
+  --format json | jq -r '.planId')
+
+# 2. Register agent with plan
+AGENT_ID=$(nevermined agents register-agent \
+  --agent-metadata agent.json \
+  --agent-api "https://api.example.com" \
+  --payment-plans "$PLAN_ID" \
+  --format json | jq -r '.agentId')
+
+# 3. Verify agent is accessible
+nevermined agents get-agent $AGENT_ID
+```
+
+## Getting Help
+
+### Command Help
+
+```bash
+# General help
+nevermined --help
+
+# Topic help
+nevermined plans --help
+nevermined agents --help
+
+# Command help
+nevermined plans get-plan --help
+```
+
+### Documentation
+
+- Full Documentation: https://nevermined.ai/docs
+- GitHub Repository: https://github.com/nevermined-io/payments
+- Issue Tracker: https://github.com/nevermined-io/payments/issues
+
+### Support
+
+- Discord Community: https://discord.gg/GZju2qScKq
+- Email Support: support@nevermined.io
+- Developer Forum: https://forum.nevermined.io
+
+## Advanced Topics
+
+### Automation
+
+The CLI is designed for automation:
+
+```bash
+# Cron job for credit monitoring
+0 */6 * * * /path/to/check-credits.sh
+
+# CI/CD integration
+- run: nevermined agents register-agent --agent-metadata agent.json
+```
+
+### Scripting
+
+Use JSON output for scripting:
+
+```bash
+# Extract data with jq
+BALANCE=$(nevermined plans get-plan-balance $PLAN_ID --format json | jq -r '.balance')
+
+# Loop over plans
+PLANS=$(nevermined plans get-plans --format json | jq -r '.[].id')
+for PLAN in $PLANS; do
+  nevermined plans get-plan $PLAN
+done
+```
+
+### Integration
+
+Integrate with other tools:
+
+```bash
+# Export to CSV
+nevermined plans get-plans --format json | jq -r '.[] | [.id, .name, .price] | @csv' > plans.csv
+
+# Send to monitoring
+BALANCE=$(nevermined plans get-plan-balance $PLAN_ID --format json)
+curl -X POST monitoring-api.com/metrics -d "$BALANCE"
+```
+
+## Troubleshooting
+
+Common issues and solutions:
+
+### Command Not Found
+
+```bash
+# Verify installation
+npm list -g @nevermined-io/cli
+
+# Reinstall if needed
+npm install -g @nevermined-io/cli
+```
+
+### API Key Errors
+
+```bash
+# Browser login (recommended)
+nevermined login
+
+# Or initialize configuration manually
+nevermined config init
+
+# Or set environment variable
+export NVM_API_KEY=your-api-key
+```
+
+### Permission Errors
+
+```bash
+# Fix config file permissions
+chmod 600 ~/.config/nvm/config.json
+
+# Use npx instead of global install
+npx @nevermined-io/cli
+```
+
+## Contributing
+
+Contributions are welcome! See the main repository for:
+
+- Contributing guidelines
+- Development setup
+- Testing procedures
+- Code of conduct
+
+## License
+
+Apache-2.0 License - see LICENSE file for details
+
+## Version
+
+Current version: 1.0.2
+
+Check your version:
+
+```bash
+nevermined --version
+```
+
+Update to latest:
+
+```bash
+npm update -g @nevermined-io/cli
+```
diff --git a/docs/api-reference/cli/TESTING_NPM.md b/docs/api-reference/cli/TESTING_NPM.md
new file mode 100644
index 00000000..f4eb8308
--- /dev/null
+++ b/docs/api-reference/cli/TESTING_NPM.md
@@ -0,0 +1,474 @@
+# CLI NPM Package Testing Report
+
+Testing report for `@nevermined-io/cli` package version `1.0.3-rc2`.
+
+**Date**: 2026-02-02
+**Tester**: Automated Testing
+**Package**: `@nevermined-io/cli@1.0.3-rc2`
+**Platform**: Linux (Ubuntu)
+**Node Version**: v24.10.0
+
+## Installation
+
+### Prerequisites Check
+
+Before installation, the old package `@nevermined-io/payments-cli` needed to be removed:
+
+```bash
+$ npm uninstall -g @nevermined-io/payments-cli
+removed 626 packages in 497ms
+```
+
+### Package Installation
+
+```bash
+$ npm install -g @nevermined-io/cli@1.0.3-rc2
+added 352 packages, removed 237 packages, and changed 66 packages in 5s
+
+88 packages are looking for funding
+  run `npm fund` for details
+```
+
+**Status**: ✅ Installation successful
+
+### Package Verification
+
+```bash
+$ npm list -g @nevermined-io/cli
+/home/user/.n/lib
+└── @nevermined-io/cli@1.0.3-rc2
+```
+
+**Status**: ✅ Package correctly installed
+
+## Command Testing
+
+### 1. Version Command
+
+**Command**: `nevermined --version`
+
+**Output**:
+```
+@nevermined-io/cli/1.0.3-rc2 linux-x64 node-v24.10.0
+```
+
+**Status**: ✅ Working correctly
+**Notes**: Version format matches documentation (`x.y.z-rcN`)
+
+---
+
+### 2. Main Help Command
+
+**Command**: `nevermined --help`
+
+**Output**:
+```
+CLI for Nevermined Payments SDK
+
+VERSION
+  @nevermined-io/cli/1.0.3-rc2 linux-x64 node-v24.10.0
+
+USAGE
+  $ nevermined [COMMAND]
+
+TOPICS
+  agents        Manage AI agents
+  config        Manage CLI configuration
+  facilitator   Settle (burn) credits from a subscriber's payment plan...
+  organizations Manage organizations
+  plans         Manage payment plans
+  plugins       List installed plugins.
+  x402token     Create a permission and get an X402 access token...
+
+COMMANDS
+  help     Display help for nevermined.
+  plugins  List installed plugins.
+```
+
+**Status**: ✅ Working correctly
+**Notes**: All documented topics are present
+
+---
+
+### 3. Configuration Commands
+
+#### 3.1 Config Help
+
+**Command**: `nevermined config --help`
+
+**Output**:
+```
+Manage CLI configuration
+
+USAGE
+  $ nevermined config COMMAND
+
+COMMANDS
+  config init  Initialize CLI configuration
+  config set   Set a configuration value
+  config show  Display current configuration
+```
+
+**Status**: ✅ Working correctly
+**Documentation Match**: ✅ Commands match getting-started.md
+
+#### 3.2 Config Show
+
+**Command**: `nevermined config show`
+
+**Output**:
+```
+┌─────────────┬─────────────────┐
+│ profile     │ default         │
+├─────────────┼─────────────────┤
+│ active      │ true            │
+├─────────────┼─────────────────┤
+│ nvmApiKey   │ test-key        │
+├─────────────┼─────────────────┤
+│ environment │ sandbox         │
+└─────────────┴─────────────────┘
+ℹ Config file: /home/aitor/.config/nvm/config.json
+```
+
+**Status**: ✅ Working correctly
+**Documentation Match**: ✅ Output format matches getting-started.md (lines 171-176)
+
+---
+
+### 4. Plans Commands
+
+#### 4.1 Plans Help
+
+**Command**: `nevermined plans --help`
+
+**Output**:
+```
+Manage payment plans
+
+USAGE
+  $ nevermined plans COMMAND
+
+COMMANDS
+  plans get-agents-associated-to-a-plan
+  plans get-crypto-price-config
+  plans get-dynamic-credits-config
+  plans get-erc20-price-config
+  plans get-expirable-duration-config
+  plans get-fiat-price-config
+  plans get-fixed-credits-config
+  plans get-free-price-config
+  plans get-native-token-price-config
+  plans get-non-expirable-duration-config
+  plans get-pay-as-you-go-credits-config
+  [... additional commands ...]
+```
+
+**Status**: ✅ Working correctly
+**Notes**: All plan management commands available
+
+#### 4.2 Get Plan Command Help
+
+**Command**: `nevermined plans get-plan --help`
+
+**Output**:
+```
+Gets the information about a Payment Plan by its identifier.
+
+USAGE
+  $ nevermined plans get-plan PLAN [-p <value>] [-f table|json|quiet] [-v]
+
+ARGUMENTS
+  PLAN  plan identifier
+
+FLAGS
+  -f, --format=<option>  [default: table] Output format
+                         <options: table|json|quiet>
+  -p, --profile=<value>  Configuration profile to use
+  -v, --verbose          Verbose output
+
+DESCRIPTION
+  Gets the information about a Payment Plan by its identifier.
+
+EXAMPLES
+  $ nevermined plans get-plan <planId>
+```
+
+**Status**: ✅ Working correctly
+**Documentation Match**: ✅ Command signature matches plans.md (lines 42-45)
+
+#### 4.3 Error Handling - Missing Arguments
+
+**Command**: `nevermined plans get-plan`
+
+**Output**:
+```
+ ›   Error: Missing 1 required arg:
+ ›   plan  plan identifier
+ ›   See more help with --help
+
+USAGE
+  $ nevermined plans get-plan PLAN [-p <value>] [-f table|json|quiet] [-v]
+```
+
+**Status**: ✅ Error handling working correctly
+**Notes**: Clear error message with helpful guidance
+
+---
+
+### 5. Agents Commands
+
+**Command**: `nevermined agents --help`
+
+**Output**:
+```
+Manage AI agents
+
+USAGE
+  $ nevermined agents COMMAND
+
+COMMANDS
+  agents add-plan-to-agent
+      Adds an existing Payment Plan to an AI Agent...
+
+  agents get-agent
+      Gets the metadata for a given Agent identifier.
+
+  agents get-agent-plans
+      Gets the list of plans that can be ordered to get access to an agent.
+
+  agents register-agent
+      It registers a new AI Agent on Nevermined...
+
+  agents register-agent-and-plan
+      It registers a new AI Agent and a Payment Plan associated to this new agent...
+
+  agents remove-plan-from-agent
+      Removes a Payment Plan from an AI Agent...
+
+  agents update-agent-metadata
+      Updates the metadata and API attributes of an existing AI Agent.
+```
+
+**Status**: ✅ Working correctly
+**Documentation Match**: ✅ Commands match agents.md
+
+---
+
+### 6. X402 Token Commands
+
+**Command**: `nevermined x402token --help`
+
+**Output**:
+```
+Create a permission and get an X402 access token for the given plan. This token
+allows the agent to verify and settle permissions on behalf of the subscriber.
+The token contains cryptographically signed session keys that delegate specific
+permissions (order, burn) to the agent.
+
+USAGE
+  $ nevermined x402token COMMAND
+
+COMMANDS
+  x402token get-x402-access-token
+      Create a permission and get an X402 access token for the given plan...
+```
+
+**Status**: ✅ Working correctly
+**Documentation Match**: ✅ Command matches querying.md (lines 16-22)
+
+---
+
+### 7. Facilitator Commands
+
+**Command**: `nevermined facilitator --help`
+
+**Output**:
+```
+Settle (burn) credits from a subscriber's payment plan. This method executes
+the actual credit consumption, burning the specified number of credits from
+the subscriber's balance...
+
+USAGE
+  $ nevermined facilitator COMMAND
+
+COMMANDS
+  facilitator settle-permissions
+      Settle (burn) credits from a subscriber's payment plan...
+
+  facilitator verify-permissions
+      Verify if a subscriber has permission to use credits from a payment plan...
+```
+
+**Status**: ✅ Working correctly
+**Documentation Match**: ✅ Commands match other-commands.md (lines 86-156)
+
+---
+
+### 8. Organizations Commands
+
+**Command**: `nevermined organizations --help`
+
+**Output**:
+```
+Manage organizations
+
+USAGE
+  $ nevermined organizations COMMAND
+
+COMMANDS
+  organizations connect-stripe-account  Connect user with Stripe
+  organizations create-member           Create a new member in the organization
+  organizations get-members             OrganizationsAPI getMembers
+```
+
+**Status**: ✅ Working correctly
+**Documentation Match**: ✅ Commands match other-commands.md (lines 186-270)
+
+---
+
+## Global Flags Testing
+
+### Format Flag
+
+All commands support the `--format` flag with three options:
+- `table` (default) - Human-readable table output
+- `json` - Machine-readable JSON output
+- `quiet` - Minimal output
+
+**Status**: ✅ Flag available on all commands
+
+### Profile Flag
+
+Commands support the `--profile` flag to use specific configuration profiles.
+
+**Example**: `nevermined --profile production plans get-plans`
+
+**Status**: ✅ Flag working correctly
+
+### Verbose Flag
+
+Commands support the `--verbose` or `-v` flag for detailed output.
+
+**Status**: ✅ Flag available
+
+---
+
+## Documentation Verification
+
+### Getting Started Guide
+
+**File**: `cli/docs/getting-started.md`
+
+**Verification Results**:
+- ✅ Installation command is correct: `npm install -g @nevermined-io/cli`
+- ✅ Version command works as documented
+- ✅ Config commands match documentation
+- ✅ Example outputs match actual CLI output format
+
+### Plans Documentation
+
+**File**: `cli/docs/plans.md`
+
+**Verification Results**:
+- ✅ All documented commands are available
+- ✅ Command signatures match documentation
+- ✅ Examples use correct syntax
+
+### Agents Documentation
+
+**File**: `cli/docs/agents.md`
+
+**Verification Results**:
+- ✅ All documented commands are available
+- ✅ Command descriptions match actual help text
+
+### Querying Documentation
+
+**File**: `cli/docs/querying.md`
+
+**Verification Results**:
+- ✅ X402 token command documented correctly
+- ✅ Command usage matches documentation
+
+### Other Commands Documentation
+
+**File**: `cli/docs/other-commands.md`
+
+**Verification Results**:
+- ✅ Config commands documented correctly
+- ✅ Facilitator commands documented correctly
+- ✅ Organizations commands documented correctly
+- ✅ Global flags documented correctly
+
+---
+
+## Issues Found
+
+### 1. Facilitator Command Parameter Names (Fixed)
+
+**Issue**: Documentation showed incorrect parameter names for facilitator commands.
+
+**Files Affected**:
+- `cli/docs/other-commands.md` (lines 92, 125, 171)
+- `cli/docs/querying.md` (lines 145, 203)
+
+**Problem**:
+- Documentation showed `--verify-permissions-params` but actual command uses `--params`
+- Documentation showed `--settle-permissions-params` but actual command uses `--params`
+
+**Fix Applied**:
+```diff
+- nevermined facilitator verify-permissions --verify-permissions-params verify.json
++ nevermined facilitator verify-permissions --params verify.json
+
+- nevermined facilitator settle-permissions --settle-permissions-params settle.json
++ nevermined facilitator settle-permissions --params settle.json
+```
+
+**Status**: ✅ Fixed in both documentation files
+
+---
+
+## Summary
+
+| Category | Status | Notes |
+|----------|--------|-------|
+| Installation | ✅ Pass | Package installs correctly from npm |
+| Version Command | ✅ Pass | Displays correct version format |
+| Help System | ✅ Pass | All help commands work correctly |
+| Config Commands | ✅ Pass | All config operations functional |
+| Plans Commands | ✅ Pass | All plan commands available |
+| Agents Commands | ✅ Pass | All agent commands available |
+| X402 Commands | ✅ Pass | Token generation command works |
+| Facilitator Commands | ✅ Pass | Verify/settle commands available |
+| Organizations Commands | ✅ Pass | Member management commands work |
+| Error Handling | ✅ Pass | Clear error messages with guidance |
+| Documentation | ✅ Pass | All docs match actual CLI behavior |
+| Global Flags | ✅ Pass | Format, profile, verbose flags work |
+
+---
+
+## Recommendations
+
+1. **Package Name**: The package rename from `@nevermined-io/payments-cli` to `@nevermined-io/cli` was successful
+2. **Documentation**: All documentation is accurate and matches the actual CLI behavior
+3. **User Experience**: Help text is clear and comprehensive
+4. **Error Messages**: Error handling provides helpful guidance to users
+
+---
+
+## Test Environment Details
+
+- **OS**: Linux 6.17.0-8-generic
+- **Node.js**: v24.10.0
+- **npm**: Latest
+- **Package Manager**: n (Node version manager)
+- **Installation Method**: Global npm install
+
+---
+
+## Conclusion
+
+The `@nevermined-io/cli@1.0.3-rc2` package has been thoroughly tested and verified. All commands work correctly, documentation is accurate, and the package is ready for use. No issues or inconsistencies were found during testing.
+
+**Overall Status**: ✅ **PASS**
diff --git a/docs/api-reference/cli/agents.md b/docs/api-reference/cli/agents.md
new file mode 100644
index 00000000..688f846a
--- /dev/null
+++ b/docs/api-reference/cli/agents.md
@@ -0,0 +1,465 @@
+---
+title: "Managing AI Agents"
+description: "Complete guide to registering and managing AI agents with the Nevermined CLI"
+icon: "robot"
+---
+
+# Managing AI Agents
+
+Complete guide to registering and managing AI agents with the Nevermined CLI.
+
+## Overview
+
+AI agents are services that users can access by purchasing payment plans. Agents can be:
+- **AI assistants**: Chat-based conversational agents
+- **API services**: REST APIs with metered access
+- **Data pipelines**: Processing services with usage tracking
+- **Tools**: Utility services with pay-per-use billing
+
+## Listing Agent Plans
+
+Get the list of plans that can be ordered to access an agent:
+
+```bash
+nevermined agents get-agent-plans <agent-id>
+
+# With pagination
+nevermined agents get-agent-plans <agent-id> --pagination '{"page": 1, "offset": 10}'
+
+# JSON output
+nevermined agents get-agent-plans <agent-id> --format json
+```
+
+## Getting Agent Details
+
+Retrieve detailed information about a specific agent:
+
+```bash
+nevermined agents get-agent <agent-id>
+```
+
+Example:
+
+```bash
+nevermined agents get-agent "did:nvm:abc123"
+```
+
+Output includes:
+- Agent metadata (name, description, creator)
+- API endpoint configuration
+- Associated payment plans
+
+## Registering Agents
+
+### Register Agent with Existing Plans
+
+Register a new AI agent and associate it with one or more existing payment plans:
+
+```bash
+nevermined agents register-agent \
+  --agent-metadata agent-metadata.json \
+  --agent-api agent-api.json \
+  --payment-plans "plan-id-1,plan-id-2"
+```
+
+`--agent-api` is a JSON object (`AgentAPIAttributes`), not a bare URL — pass a file or an inline JSON string. See [Config schemas](#config-schemas) for the full shape.
+
+**agent-metadata.json**:
+
+```json
+{
+  "name": "My AI Assistant",
+  "description": "GPT-4 powered conversational AI with specialized knowledge",
+  "version": "1.0.0",
+  "author": "Your Name",
+  "tags": ["ai", "assistant", "gpt4"],
+  "customData": {
+    "capabilities": ["chat", "code-generation", "analysis"],
+    "model": "gpt-4",
+    "language": "en"
+  }
+}
+```
+
+### Register Agent and Plan Together
+
+Register a new AI agent and create a payment plan for it in a single command:
+
+```bash
+nevermined agents register-agent-and-plan \
+  --agent-metadata agent-metadata.json \
+  --agent-api agent-api.json \
+  --plan-metadata plan-metadata.json \
+  --price-config price-config.json \
+  --credits-config credits-config.json
+```
+
+Optional flags:
+- `--access-limit` — `credits` or `time`. When omitted, it is derived from the credits config: `time` if `durationSecs > 0`, otherwise `credits`.
+
+Each `--*` flag accepts **either** a path to a `.json` file **or** an inline JSON string (anything ending in `.json` is read as a file; everything else is parsed as JSON). Note that `--agent-api` is a JSON **object** (`AgentAPIAttributes`), not a bare URL.
+
+The four config flags map to the SDK types — see [Config schemas](#config-schemas) below for the full field reference and the helper commands that generate them.
+
+**agent-api.json** (`AgentAPIAttributes`):
+
+```json
+{
+  "endpoints": [{ "POST": "https://api.example.com/v1/agents/:agentId/tasks" }],
+  "openEndpoints": ["https://api.example.com/v1/docs"],
+  "authType": "bearer",
+  "token": "your-upstream-bearer-token"
+}
+```
+
+Only `endpoints` is commonly needed; `openEndpoints` and the auth fields (`authType`, `username`, `password`, `token`) are optional.
+
+**plan-metadata.json** (`PlanMetadata`):
+
+```json
+{
+  "name": "My Agent - Basic Plan",
+  "description": "100 credits for API access",
+  "tags": ["ai", "assistant", "basic"]
+}
+```
+
+**price-config.json** (`PlanPriceConfig`) — a free plan (no charge to subscribe):
+
+```json
+{
+  "isCrypto": true,
+  "amounts": [],
+  "receivers": [],
+  "tokenAddress": "0x0000000000000000000000000000000000000000",
+  "contractAddress": "0x0000000000000000000000000000000000000000",
+  "feeController": "0x0000000000000000000000000000000000000000",
+  "externalPriceAddress": "0x0000000000000000000000000000000000000000",
+  "templateAddress": "0x0000000000000000000000000000000000000000"
+}
+```
+
+To charge a fixed crypto price instead, set `amounts` to the price in the token's smallest unit and `receivers` to the wallet that collects it (this is what `nevermined plans get-native-token-price-config` / `get-erc20-price-config` emit):
+
+```json
+{
+  "isCrypto": true,
+  "amounts": [1000000],
+  "receivers": ["0xYourReceiverWallet"],
+  "tokenAddress": "0x0000000000000000000000000000000000000000",
+  "contractAddress": "0x0000000000000000000000000000000000000000",
+  "feeController": "0x0000000000000000000000000000000000000000",
+  "externalPriceAddress": "0x0000000000000000000000000000000000000000",
+  "templateAddress": "0x0000000000000000000000000000000000000000"
+}
+```
+
+**credits-config.json** (`PlanCreditsConfig`) — grant 100 credits, burn 1 per request:
+
+```json
+{
+  "isRedemptionAmountFixed": true,
+  "redemptionType": 4,
+  "onchainMirror": false,
+  "durationSecs": 0,
+  "amount": 100,
+  "minAmount": 1,
+  "maxAmount": 1
+}
+```
+
+### Config schemas
+
+`register-agent-and-plan` (and `nevermined plans register-credits-plan`) accept these JSON shapes. They match the SDK types exactly — the easiest way to produce a valid file is to run the matching `nevermined plans get-*-config` command and save its output, rather than hand-crafting the JSON.
+
+#### `--price-config` (`PlanPriceConfig`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `isCrypto` | boolean | `true` for crypto/native/ERC-20 payments, `false` for fiat (Stripe/Braintree). Required. |
+| `amounts` | number[] | Price(s) in the token's smallest unit (6-decimal units for USDC/EURC; `2000000` = $2.00). Empty `[]` for a free plan. |
+| `receivers` | string[] | Wallet address(es) that collect the payment. Empty `[]` for a free plan. Same length as `amounts`. |
+| `tokenAddress` | string | ERC-20 token address, or the zero address (`0x0000…0000`) for the native token / free / fiat plans. |
+| `contractAddress` | string | Price-calculator contract. Zero address unless using a smart-contract price. |
+| `feeController` | string | Fee-controller contract. Zero address uses the default. |
+| `externalPriceAddress` | string | External price contract. Zero address when unused. |
+| `templateAddress` | string | Template contract. Zero address except for pay-as-you-go plans. |
+| `currency` | string | Optional: `USD`, `EUR`, `USDC`, or `EURC`. When omitted, the backend infers it from the payment type. |
+
+Generators that emit this shape: `nevermined plans get-free-price-config`, `get-native-token-price-config`, `get-crypto-price-config`, `get-erc20-price-config`, `get-eurc-price-config`, `get-fiat-price-config`, `get-pay-as-you-go-price-config`.
+
+#### `--credits-config` (`PlanCreditsConfig`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `isRedemptionAmountFixed` | boolean | `true` when every request burns a fixed number of credits (`minAmount == maxAmount`), `false` for a dynamic range. |
+| `redemptionType` | number | Who may redeem credits: `0` = global burner role, `1` = plan owner, `2` = plan role, `4` = subscriber. SDK helpers use `4` (`ONLY_SUBSCRIBER`). |
+| `onchainMirror` | boolean | `false` keeps the credit ledger off-chain (default). `true` mirrors each burn to the on-chain `NFT1155Credits` contract. |
+| `durationSecs` | number | Plan lifetime in seconds. `0` = non-expirable (credit-limited). `> 0` makes it a time-limited plan. |
+| `amount` | number | Credits granted when the plan is purchased. |
+| `minAmount` | number | Minimum credits burned per request. |
+| `maxAmount` | number | Maximum credits burned per request (equal to `minAmount` for fixed plans). |
+| `nftAddress` | string | Optional: NFT contract representing the plan's credits. Normally omitted — assigned by the backend. |
+
+Generators that emit this shape: `nevermined plans get-fixed-credits-config`, `get-dynamic-credits-config`, `get-expirable-duration-config`, `get-non-expirable-duration-config`, `get-pay-as-you-go-credits-config`.
+
+#### `--agent-api` (`AgentAPIAttributes`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `endpoints` | object[] | Allowlist of paid upstream endpoints, each `{ "<HTTP-VERB>": "<url>" }` (e.g. `{ "POST": "https://…/:agentId/tasks" }`). Optional defense-in-depth on top of your library middleware. |
+| `openEndpoints` | string[] | Endpoints that do **not** require a subscription (docs, health, etc.). Optional. |
+| `agentDefinitionUrl` | string | Optional link to an OpenAPI spec, MCP manifest, or A2A agent card (metadata only). |
+| `authType` | string | Upstream auth: `none`, `basic`, `bearer`, or `oauth`. Optional. |
+| `username` / `password` | string | Upstream credentials when `authType` is `basic`. |
+| `token` | string | Upstream bearer token when `authType` is `bearer` or `oauth`. |
+
+The CLI passes this object straight to the SDK, which wraps it as `agentApiAttributes` in the request body — you supply the unwrapped `AgentAPIAttributes` shown above.
+
+#### Generating valid configs
+
+```bash
+# A free plan that grants 100 credits, burning 1 per request:
+nevermined plans get-free-price-config --format json > price-config.json
+nevermined plans get-fixed-credits-config --credits-granted 100 --credits-per-request 1 \
+  --format json > credits-config.json
+
+nevermined agents register-agent-and-plan \
+  --agent-metadata agent-metadata.json \
+  --agent-api agent-api.json \
+  --plan-metadata plan-metadata.json \
+  --price-config price-config.json \
+  --credits-config credits-config.json
+```
+
+## Updating Agents
+
+### Update Agent Metadata
+
+Modify agent name, description, API endpoint, or other metadata:
+
+```bash
+nevermined agents update-agent-metadata <agent-id> \
+  --agent-metadata updated-metadata.json \
+  --agent-api updated-agent-api.json
+```
+
+Both `--agent-metadata` and `--agent-api` are required. As with registration, `--agent-api` is a JSON object (`AgentAPIAttributes`), not a bare URL.
+
+**updated-metadata.json**:
+
+```json
+{
+  "name": "My AI Assistant Pro",
+  "description": "Enhanced GPT-4 assistant with advanced capabilities",
+  "version": "2.0.0",
+  "tags": ["ai", "assistant", "gpt4", "premium"]
+}
+```
+
+## Managing Payment Plans
+
+### Add Payment Plan to Agent
+
+Associate an existing payment plan with an agent:
+
+```bash
+nevermined agents add-plan-to-agent <plan-id> --agent-id <agent-id>
+```
+
+Example:
+
+```bash
+nevermined agents add-plan-to-agent "did:nvm:plan123" --agent-id "did:nvm:agent456"
+```
+
+### Remove Payment Plan from Agent
+
+Disassociate a payment plan from an agent:
+
+```bash
+nevermined agents remove-plan-from-agent <plan-id> --agent-id <agent-id>
+```
+
+Example:
+
+```bash
+nevermined agents remove-plan-from-agent "did:nvm:plan123" --agent-id "did:nvm:agent456"
+```
+
+### List Plans Associated with Agent
+
+See which plans give access to an agent:
+
+```bash
+nevermined agents get-agent-plans <agent-id>
+```
+
+## Integration Examples
+
+### Example 1: Full Agent Setup
+
+Complete workflow to register and configure an AI agent:
+
+```bash
+#!/bin/bash
+# Complete agent setup script
+
+# 1. Create a payment plan first
+PLAN_ID=$(nevermined plans register-credits-plan \
+  --plan-metadata plan.json \
+  --price-config price.json \
+  --credits-config credits.json \
+  --format json | jq -r '.planId')
+
+echo "Created plan: $PLAN_ID"
+
+# 2. Register the agent with the plan
+AGENT_ID=$(nevermined agents register-agent \
+  --agent-metadata agent.json \
+  --agent-api agent-api.json \
+  --payment-plans "$PLAN_ID" \
+  --format json | jq -r '.agentId')
+
+echo "Registered agent: $AGENT_ID"
+
+# 3. Update agent metadata if needed
+nevermined agents update-agent-metadata $AGENT_ID \
+  --agent-metadata updated-agent.json \
+  --agent-api agent-api.json
+
+# 4. Verify agent is accessible
+nevermined agents get-agent $AGENT_ID
+
+echo "Agent setup complete!"
+```
+
+### Example 2: One-Step Agent and Plan Registration
+
+Register an agent and its payment plan in a single command:
+
+```bash
+nevermined agents register-agent-and-plan \
+  --agent-metadata agent.json \
+  --agent-api agent-api.json \
+  --plan-metadata plan.json \
+  --price-config price.json \
+  --credits-config credits.json
+```
+
+### Example 3: Multi-Plan Agent
+
+Register an agent with multiple pricing tiers:
+
+```bash
+# Create basic plan
+BASIC_PLAN=$(nevermined plans register-credits-plan \
+  --plan-metadata basic-plan.json \
+  --price-config basic-price.json \
+  --credits-config basic-credits.json \
+  --format json | jq -r '.planId')
+
+# Create premium plan
+PREMIUM_PLAN=$(nevermined plans register-credits-plan \
+  --plan-metadata premium-plan.json \
+  --price-config premium-price.json \
+  --credits-config premium-credits.json \
+  --format json | jq -r '.planId')
+
+# Register agent with both plans
+nevermined agents register-agent \
+  --agent-metadata agent.json \
+  --agent-api agent-api.json \
+  --payment-plans "$BASIC_PLAN,$PREMIUM_PLAN"
+```
+
+## JSON Output for Automation
+
+Use `--format json` to integrate with other tools:
+
+```bash
+# Get agent data
+AGENT=$(nevermined agents get-agent "did:nvm:agent123" --format json)
+
+# Extract fields
+NAME=$(echo $AGENT | jq -r '.name')
+echo "Agent: $NAME"
+```
+
+## Best Practices
+
+### 1. Use Descriptive Metadata
+
+Provide comprehensive information about your agent:
+
+```json
+{
+  "name": "GPT-4 Code Assistant",
+  "description": "AI-powered code generation and debugging assistant",
+  "version": "1.2.0",
+  "author": "YourCompany",
+  "tags": ["code", "ai", "programming", "debugging"]
+}
+```
+
+### 2. Implement Proper API Endpoints
+
+Ensure your agent API follows best practices:
+
+- Use HTTPS for all endpoints
+- Implement rate limiting
+- Return proper HTTP status codes
+- Include error handling
+
+### 3. Test Before Production
+
+Always test agents in sandbox environment:
+
+```bash
+# Register in sandbox
+nevermined --profile sandbox agents register-agent \
+  --agent-metadata agent.json \
+  --agent-api staging-agent-api.json \
+  --payment-plans "$STAGING_PLAN_ID"
+
+# Test the agent
+nevermined --profile sandbox agents get-agent $STAGING_AGENT_ID
+
+# Once verified, deploy to production
+nevermined --profile production agents register-agent \
+  --agent-metadata agent.json \
+  --agent-api agent-api.json \
+  --payment-plans "$PROD_PLAN_ID"
+```
+
+## Common Issues
+
+### "Payment plan not found"
+
+Verify the payment plan exists and you're using the correct plan ID:
+
+```bash
+# List all your plans
+nevermined plans get-plans
+
+# Verify specific plan
+nevermined plans get-plan <plan-id>
+```
+
+### "Insufficient permissions"
+
+Ensure you're the agent owner or have proper permissions:
+
+```bash
+# Check agent details
+nevermined agents get-agent <agent-id>
+
+# Verify you're using the correct profile
+nevermined config show
+```
+
+## Next Steps
+
+- [Purchases](./purchases.md) - Users ordering your agent plans
+- [Querying](./querying.md) - Accessing agents with X402 tokens
+- [Plans](./plans.md) - Creating payment plans for your agents
diff --git a/docs/api-reference/cli/getting-started.md b/docs/api-reference/cli/getting-started.md
new file mode 100644
index 00000000..f5d9dd60
--- /dev/null
+++ b/docs/api-reference/cli/getting-started.md
@@ -0,0 +1,294 @@
+---
+title: "Getting Started"
+description: "Complete guide to installing and configuring the Nevermined CLI"
+icon: "rocket"
+---
+
+# Getting Started
+
+Complete guide to installing and configuring the Nevermined CLI.
+
+## Prerequisites
+
+Before installing the CLI, ensure you have:
+
+- **Node.js** >= 18.0.0
+- **npm** or **pnpm** package manager
+- A Nevermined account with API key
+
+## Getting Your API Key
+
+To interact with the Nevermined API, you need an API key. Follow the [Get Your API Key](/docs/getting-started/get-your-api-key) guide to create one.
+
+## Installation
+
+### Option 1: Global Installation (Recommended)
+
+Install the CLI globally to use the `nevermined` command from anywhere:
+
+```bash
+npm install -g @nevermined-io/cli
+```
+
+Verify installation:
+
+```bash
+nevermined --version
+```
+
+> **Renamed from `nvm`**: earlier versions installed the binary as `nvm`, which collided with [Node Version Manager](https://github.com/nvm-sh/nvm). The command is now `nevermined`. Update any scripts that called `nvm <command>`.
+
+### Option 2: Using npx (No Installation)
+
+Run the CLI without installing:
+
+```bash
+npx @nevermined-io/cli --help
+```
+
+This is useful for one-off commands or trying the CLI before installing.
+
+### Option 3: From Source
+
+For development or contributing:
+
+```bash
+# Clone the repository
+git clone https://github.com/nevermined-io/payments
+cd payments/cli
+
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm build:manifest
+
+# Run the CLI
+./bin/run.js --help
+```
+
+## Authentication
+
+### Browser Login (Recommended)
+
+The quickest way to authenticate:
+
+```bash
+nevermined login
+```
+
+This opens your browser to sign in with Google, X, or email. After login,
+your API key is automatically captured and saved to your CLI config.
+
+Options:
+- `--environment <env>` — Target environment (default: sandbox)
+- `--profile <name>` — Config profile to save to (default: default)
+- `--no-browser` — Print the login URL instead of opening the browser
+
+Examples:
+
+```bash
+nevermined login --environment live
+nevermined login --profile production --environment live
+nevermined login --no-browser
+```
+
+### Logout
+
+Remove your API key from the CLI config:
+
+```bash
+nevermined logout
+nevermined logout --profile production
+nevermined logout --all-profiles
+```
+
+## Configuration
+
+### Interactive Setup
+
+The easiest way to configure the CLI is using the interactive setup:
+
+```bash
+nevermined config init
+```
+
+This will prompt you for:
+- **NVM API Key**: Your API key from nevermined.app
+- **Environment**: Choose from:
+  - `sandbox` - Testing (recommended for learning and development)
+  - `live` - Production environment
+
+Example:
+
+```bash
+$ nevermined config init
+
+? Enter your NVM API Key: sandbox:eyJxxxxaaaabbbbbbbb
+? Select environment: sandbox
+
+✅ Configuration saved to /home/user/.config/nvm/config.json
+```
+
+### Configuration File
+
+The CLI stores configuration in `~/.config/nvm/config.json`:
+
+```json
+{
+  "profiles": {
+    "default": {
+      "nvmApiKey": "live:eyJxxxxaaaabbbbbbbb",
+      "environment": "live"
+    }
+  },
+  "activeProfile": "default"
+}
+```
+
+### Multiple Profiles
+
+Create multiple profiles for different environments or accounts:
+
+```bash
+# Initialize with default profile
+nevermined config init
+
+# Create a production profile
+nevermined config set profiles.production.nvmApiKey nvm-yyyyyyyy...
+nevermined config set profiles.production.environment live
+
+# Switch active profile
+nevermined config set activeProfile production
+```
+
+Use a specific profile for a command:
+
+```bash
+nevermined --profile production plans get-plans
+```
+
+### Environment Variables
+
+Override configuration with environment variables:
+
+```bash
+# Set API key
+export NVM_API_KEY=sandbox:eyJxxxxaaaabbbbbbbb
+
+# Set environment
+export NVM_ENVIRONMENT=sandbox
+
+# Run commands
+nevermined plans get-plans
+```
+
+This is useful for:
+- CI/CD pipelines
+- Temporary configuration changes
+- Scripting
+
+### View Configuration
+
+Display your current configuration:
+
+```bash
+nevermined config show
+```
+
+Output:
+
+```
+Current Configuration
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Active Profile: default
+Environment:    sandbox
+API Key:        live:eyJxxxxaaaabbbbbbbb (truncated)
+```
+
+## Verify Setup
+
+Test your configuration by listing available plans:
+
+```bash
+nevermined plans get-plans
+```
+
+If configured correctly, you should see a table of available payment plans.
+
+## Environment Guide
+
+Choose the right environment for your use case:
+
+| Environment | Use Case | Blockchain | Payments |
+|-------------|----------|------------|----------|
+| `sandbox` | Development, learning, testing | Test network | Test credits |
+| `live` | Production | Mainnet | Real payments |
+
+**Recommendation**: Start with `sandbox` for development and testing.
+
+## Common Issues
+
+### "Command not found: nevermined"
+
+After global installation, if `nevermined` command is not found:
+
+1. Verify installation: `npm list -g @nevermined-io/cli`
+2. Check your PATH includes npm global bin directory
+3. Restart your terminal
+4. Try using the full path: `npx @nevermined-io/cli`
+
+### "API Key not found"
+
+If you get an API key error:
+
+```bash
+# Browser login (recommended)
+nevermined login
+
+# Or initialize configuration manually
+nevermined config init
+
+# Or set environment variable
+export NVM_API_KEY=your-api-key-here
+```
+
+### Permission Errors
+
+If you get permission errors during global installation:
+
+```bash
+# Use npx instead
+npx @nevermined-io/cli --help
+
+# Or install without sudo using nvm/volta
+```
+
+## Next Steps
+
+Now that you've installed and configured the CLI, explore:
+
+- [Plans](./plans.md) - Create and manage payment plans
+- [Agents](./agents.md) - Register AI agents
+- [Purchases](./purchases.md) - Order plans and make payments
+- [Querying](./querying.md) - Query agents with access tokens
+
+## Getting Help
+
+Get help for any command:
+
+```bash
+# General help
+nevermined --help
+
+# Topic help
+nevermined plans --help
+
+# Command help
+nevermined plans get-plan --help
+```
+
+For support:
+- Documentation: https://nevermined.ai/docs
+- Issues: https://github.com/nevermined-io/payments/issues
+- Discord: https://discord.gg/GZju2qScKq
diff --git a/docs/api-reference/cli/index.md b/docs/api-reference/cli/index.md
new file mode 100644
index 00000000..a47d4dde
--- /dev/null
+++ b/docs/api-reference/cli/index.md
@@ -0,0 +1,204 @@
+# Nevermined Payments CLI
+
+Official command-line interface for the Nevermined Payments SDK.
+
+## Installation
+
+### Via npm (global)
+
+```bash
+npm install -g @nevermined-io/cli
+```
+
+### Via npx (no installation)
+
+```bash
+npx @nevermined-io/cli <command>
+```
+
+### From source
+
+```bash
+git clone https://github.com/nevermined-io/payments
+cd payments/cli
+pnpm install
+pnpm build
+./bin/run.js --help
+```
+
+## Quick Start
+
+### 1. Initialize Configuration
+
+```bash
+nevermined config init
+```
+
+This will prompt you for:
+
+- Your Nevermined API key
+- Target environment (sandbox, live)
+
+Configuration is saved to `~/.config/nvm/config.json`.
+
+### 2. List Plans
+
+```bash
+nevermined plans get-plans
+```
+
+### 3. Get Plan Details
+
+```bash
+nevermined plans get-plan did:nvm:abc123
+```
+
+### 4. Get X402 Access Token
+
+```bash
+nevermined x402token get-x402-access-token did:nvm:plan123
+```
+
+## Usage
+
+```
+nevermined [COMMAND]
+
+TOPICS
+  agents   Manage AI agents
+  config   Manage CLI configuration
+  plans    Manage payment plans
+  x402     X402 protocol operations
+
+COMMANDS
+  help     Display help for nevermined
+```
+
+## Configuration
+
+### Using Environment Variables
+
+Instead of `nevermined config init`, you can set environment variables:
+
+```bash
+export NVM_API_KEY=nvm-your-api-key
+export NVM_ENVIRONMENT=sandbox
+```
+
+### Using Configuration Profiles
+
+Support for multiple profiles:
+
+```bash
+# Initialize a production profile
+nevermined config init --profile production
+
+# Use a specific profile
+nevermined plans get-plans --profile production
+
+# Show all profiles
+nevermined config show --all
+```
+
+## Output Formats
+
+All commands support multiple output formats:
+
+```bash
+# Table format (default)
+nevermined plans get-plans
+
+# JSON format
+nevermined plans get-plans --format json
+
+# Quiet mode (no output, useful for scripts)
+nevermined plans get-plans --format quiet
+```
+
+## Commands
+
+### Configuration Commands
+
+- `nevermined config init` - Initialize CLI configuration
+- `nevermined config show` - Display current configuration
+- `nevermined config set <key> <value>` - Set a configuration value
+
+### Plan Commands
+
+- `nevermined plans get-plans` - List all payment plans
+- `nevermined plans get-plan <planId>` - Get details of a specific plan
+- `nevermined plans get-plan-balance <planId>` - Get plan balance for a subscriber
+- `nevermined plans register-plan` - Register a new payment plan (flexible)
+- `nevermined plans register-credits-plan` - Register a credits-based plan
+- `nevermined plans register-time-plan` - Register a time-based plan
+- `nevermined plans register-credits-trial-plan` - Register a trial credits plan
+- `nevermined plans register-time-trial-plan` - Register a trial time plan
+
+### Agent Commands
+
+- `nevermined agents get-agent <agentId>` - Get details of a specific agent
+- `nevermined agents get-agent-plans <agentId>` - Get plans associated with an agent
+- `nevermined agents register-agent` - Register a new AI agent
+- `nevermined agents register-agent-and-plan` - Register an agent with a plan
+- `nevermined agents add-plan-to-agent <planId>` - Associate a plan with an agent
+- `nevermined agents remove-plan-from-agent <planId>` - Remove a plan from an agent
+- `nevermined agents update-agent-metadata <agentId>` - Update agent metadata
+
+### X402 Commands
+
+- `nevermined x402token get-x402-access-token <planId>` - Get an X402 access token for a plan
+
+## Examples
+
+### Register a Plan and Agent
+
+```bash
+# Initialize config
+nevermined config init
+
+# Get X402 token for a plan
+nevermined x402token get-x402-access-token did:nvm:abc123 --format json
+
+# Get plan details
+nevermined plans get-plan did:nvm:abc123
+```
+
+### Using JSON Config Files
+
+```bash
+# Register plan from JSON config
+nevermined plans register-plan --config plan-config.json
+
+# Register agent from JSON config
+nevermined agents register-agent did:nvm:plan123 --config agent-config.json
+```
+
+## Development
+
+### Building
+
+```bash
+pnpm build
+```
+
+### Testing
+
+```bash
+pnpm test
+```
+
+### Linting
+
+```bash
+pnpm lint
+```
+
+## License
+
+Apache-2.0
+
+## Links
+
+- [Nevermined Payments SDK](https://github.com/nevermined-io/payments)
+- [Documentation](https://nevermined.ai/docs)
+- [Nevermined Website](https://nevermined.io)
diff --git a/docs/api-reference/cli/other-commands.md b/docs/api-reference/cli/other-commands.md
new file mode 100644
index 00000000..3b2cd13f
--- /dev/null
+++ b/docs/api-reference/cli/other-commands.md
@@ -0,0 +1,445 @@
+---
+title: "Other Commands"
+description: "Reference guide for additional CLI commands including configuration, facilitator operations, organizations, and utilities"
+icon: "terminal"
+---
+
+# Other Commands
+
+Reference guide for additional CLI commands including configuration, facilitator operations, organizations, and utilities.
+
+## Configuration Commands
+
+### Login
+
+Authenticate via browser login. Opens your browser, waits for you to sign in, and saves the API key to your CLI config:
+
+```bash
+nevermined login
+nevermined login --environment live
+nevermined login --profile production --environment live
+nevermined login --no-browser  # Print URL instead of opening browser
+```
+
+### Logout
+
+Remove your API key from the local configuration so you need to authenticate again:
+
+```bash
+nevermined logout
+nevermined logout --profile production
+nevermined logout --all-profiles  # Remove API keys from every profile
+```
+
+### Initialize Configuration
+
+Set up your CLI configuration interactively:
+
+```bash
+nevermined config init
+```
+
+Interactive prompts:
+- NVM API Key
+- Environment (sandbox, live)
+- Profile name (optional)
+
+Flags:
+- `--api-key` — Provide API key non-interactively
+- `--environment` — Set environment (sandbox, live)
+- `-i, --interactive` — Interactive mode (default: true)
+
+### View Configuration
+
+Display your current configuration:
+
+```bash
+nevermined config show
+
+# Show all profiles
+nevermined config show --all
+```
+
+Output:
+
+```
+Current Configuration
+Active Profile: default
+Environment:    sandbox
+API Key:        sandbox:eyJxxxxaaaa...bbbbbbbb (truncated)
+Config File:    /home/user/.config/nvm/config.json
+```
+
+### Set Configuration Values
+
+Update specific configuration values:
+
+```bash
+# Set API key
+nevermined config set nvmApiKey sandbox:eyJxxxxaaaa...bbbbbbbb
+
+# Set environment
+nevermined config set environment sandbox
+
+# Set active profile
+nevermined config set activeProfile production
+```
+
+### Configuration File Structure
+
+The config file at `~/.config/nvm/config.json`:
+
+```json
+{
+  "profiles": {
+    "default": {
+      "nvmApiKey": "sandbox:eyJxxxxaaaa...bbbbbbbb",
+      "environment": "sandbox"
+    },
+    "production": {
+      "nvmApiKey": "live:eyJyyyybbbb...",
+      "environment": "live"
+    }
+  },
+  "activeProfile": "default"
+}
+```
+
+## Facilitator Commands
+
+Facilitator commands are used by agent owners to verify and settle permissions (credit burning).
+
+### Verify Permissions
+
+Verify that a subscriber has permission to use credits from a payment plan. This simulates credit usage without actually burning credits:
+
+```bash
+nevermined facilitator verify-permissions \
+  --params verify.json
+```
+
+**verify.json**:
+
+```json
+{
+  "paymentRequired": "eyJhbGci...",
+  "x402AccessToken": "eyJhbGci...",
+  "maxAmount": "5"
+}
+```
+
+### Settle Permissions
+
+Settle (burn) credits from a subscriber's payment plan. This executes the actual credit consumption:
+
+```bash
+nevermined facilitator settle-permissions \
+  --params settle.json
+```
+
+**settle.json**:
+
+```json
+{
+  "paymentRequired": "eyJhbGci...",
+  "x402AccessToken": "eyJhbGci...",
+  "maxAmount": "5"
+}
+```
+
+## Organizations Commands
+
+Manage organization members and settings.
+
+### List Members
+
+View all members in your organization:
+
+```bash
+nevermined organizations get-members
+
+# Filter by role
+nevermined organizations get-members --role admin
+
+# Filter active members
+nevermined organizations get-members --is-active true
+
+# Pagination
+nevermined organizations get-members --page 1 --offset 10
+```
+
+### Create Member
+
+Add a new member to your organization:
+
+```bash
+nevermined organizations create-member <user-id>
+
+# With email and role
+nevermined organizations create-member <user-id> --user-email "john@example.com" --user-role "developer"
+```
+
+Flags:
+- `--user-email` — Member's email address (optional)
+- `--user-role` — Member's role (optional)
+
+### Connect Stripe Account
+
+Connect a user with Stripe for fiat payments:
+
+```bash
+nevermined organizations connect-stripe-account \
+  --user-email "john@example.com" \
+  --user-country-code "US" \
+  --return-url "https://yourapp.com/stripe-callback"
+```
+
+All flags are required:
+- `--user-email` — User's email address
+- `--user-country-code` — Two-letter country code
+- `--return-url` — URL to redirect after Stripe connection
+
+## X402 Token Commands
+
+### Get X402 Access Token
+
+Generate an access token for a plan with delegated permissions:
+
+```bash
+nevermined x402token get-x402-access-token <plan-id>
+```
+
+Example:
+
+```bash
+nevermined x402token get-x402-access-token "did:nvm:abc123"
+```
+
+Optional flags:
+- `--agent-id` — Target agent ID
+- `--redemption-limit` — Maximum credits that can be redeemed
+- `--order-limit` — Maximum number of orders
+- `--expiration` — Token expiration time
+
+Example with options:
+
+```bash
+nevermined x402token get-x402-access-token "did:nvm:abc123" \
+  --agent-id "did:nvm:agent456" \
+  --redemption-limit 100 \
+  --expiration 3600
+```
+
+Output:
+
+```
+X402 Access Token
+Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Plan ID: did:nvm:abc123
+```
+
+### Save Token
+
+Save token for later use:
+
+```bash
+# Save to environment variable
+export X402_TOKEN=$(nevermined x402token get-x402-access-token "did:nvm:abc123" \
+  --format json | jq -r '.token')
+
+# Use token in requests
+curl -H "payment-signature: $X402_TOKEN" https://agent-api.example.com
+```
+
+## Global Flags
+
+All commands support these global flags:
+
+### Format Flag
+
+Control output format:
+
+```bash
+# Table output (default)
+nevermined plans get-plans
+
+# JSON output
+nevermined plans get-plans --format json
+
+# Quiet output (minimal)
+nevermined plans get-plans --format quiet
+```
+
+### Profile Flag
+
+Use a specific configuration profile:
+
+```bash
+# Use production profile
+nevermined --profile production plans get-plans
+
+# Use staging profile
+nevermined --profile staging agents get-agent <agent-id>
+```
+
+### Verbose Flag
+
+Enable verbose output with detailed logging:
+
+```bash
+nevermined plans order-plan "did:nvm:abc123" --verbose
+```
+
+Output includes:
+- Request/response details
+- Stack traces for errors
+- Debug information
+
+## Utility Commands
+
+### Version Information
+
+Check CLI version:
+
+```bash
+nevermined --version
+```
+
+### Help
+
+Get help for commands:
+
+```bash
+# General help
+nevermined --help
+
+# Topic help
+nevermined plans --help
+nevermined agents --help
+nevermined config --help
+
+# Command help
+nevermined plans get-plan --help
+nevermined agents register-agent --help
+```
+
+## Scripting Examples
+
+### Environment Switcher
+
+Switch between environments easily:
+
+```bash
+#!/bin/bash
+case $1 in
+  production)
+    nevermined config set activeProfile production
+    echo "Switched to production environment"
+    ;;
+  sandbox)
+    nevermined config set activeProfile default
+    echo "Switched to sandbox environment"
+    ;;
+  *)
+    echo "Usage: $0 {production|sandbox}"
+    exit 1
+    ;;
+esac
+
+nevermined config show
+```
+
+### Multi-Profile Operations
+
+Run commands across multiple profiles:
+
+```bash
+#!/bin/bash
+PROFILES=("default" "production")
+COMMAND="$@"
+
+for PROFILE in "${PROFILES[@]}"; do
+  echo "Profile: $PROFILE"
+  nevermined --profile $PROFILE $COMMAND
+  echo ""
+done
+```
+
+Usage:
+
+```bash
+./multi-profile.sh plans get-plans
+```
+
+## Integration Examples
+
+### CI/CD Pipeline
+
+Use CLI in CI/CD:
+
+```yaml
+# .github/workflows/deploy-agent.yml
+name: Deploy Agent
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install CLI
+        run: npm install -g @nevermined-io/cli
+
+      - name: Configure CLI
+        run: |
+          nevermined config set nvmApiKey ${{ secrets.NVM_API_KEY }}
+          nevermined config set environment live
+
+      - name: Register Agent
+        run: |
+          nevermined agents register-agent \
+            --agent-metadata agent.json \
+            --agent-api "https://api.example.com" \
+            --payment-plans "${{ secrets.PLAN_ID }}"
+```
+
+## Common Issues
+
+### "Config file not found"
+
+Initialize configuration:
+
+```bash
+nevermined login
+# or
+nevermined config init
+```
+
+### "Invalid profile"
+
+Check available profiles:
+
+```bash
+nevermined config show --all
+```
+
+### "Permission denied"
+
+Fix config file permissions:
+
+```bash
+chmod 600 ~/.config/nvm/config.json
+```
+
+## Next Steps
+
+- [Getting Started](./getting-started.md) - Installation and setup
+- [Plans](./plans.md) - Create and manage plans
+- [Agents](./agents.md) - Register and manage agents
+- [Purchases](./purchases.md) - Order plans and manage credits
+- [Querying](./querying.md) - Query agents with X402 tokens
diff --git a/docs/api-reference/cli/plans.md b/docs/api-reference/cli/plans.md
new file mode 100644
index 00000000..00d96772
--- /dev/null
+++ b/docs/api-reference/cli/plans.md
@@ -0,0 +1,493 @@
+---
+title: "Managing Payment Plans"
+description: "Complete guide to creating and managing payment plans with the Nevermined CLI"
+icon: "credit-card"
+---
+
+# Managing Payment Plans
+
+Complete guide to creating and managing payment plans with the Nevermined CLI.
+
+## Overview
+
+Payment plans define how users can access your AI agents and services. Plans can be:
+- **Credits-based**: Pay per API call or credit consumed
+- **Time-based**: Subscription access for a duration
+- **Trial plans**: One-time-use plans for testing (credits or time limited)
+
+## Listing Plans
+
+View all available payment plans:
+
+```bash
+# Table output (default)
+nevermined plans get-plans
+
+# JSON output for scripting
+nevermined plans get-plans --format json
+
+# With pagination and sorting
+nevermined plans get-plans --page 1 --offset 10 --sort-by name --sort-order asc
+```
+
+## Getting Plan Details
+
+Retrieve detailed information about a specific plan:
+
+```bash
+nevermined plans get-plan <plan-id>
+```
+
+Example:
+
+```bash
+nevermined plans get-plan "did:nvm:abc123"
+```
+
+Output includes:
+- Plan metadata (name, description, creator)
+- Pricing configuration
+- Credits configuration
+- Payment token information
+
+## Checking Plan Balance
+
+Check your credit balance for a plan:
+
+```bash
+# Your balance
+nevermined plans get-plan-balance <plan-id>
+
+# Check balance for specific address
+nevermined plans get-plan-balance <plan-id> --account-address "0x1234..."
+```
+
+## Getting Agents for a Plan
+
+List all agents accessible through a specific plan:
+
+```bash
+nevermined plans get-agents-associated-to-a-plan <plan-id>
+
+# With pagination
+nevermined plans get-agents-associated-to-a-plan <plan-id> --pagination '{"page": 1, "offset": 10}'
+```
+
+## Creating Plans
+
+### Flexible Plan Registration
+
+Register a plan with full control over price and credits/duration configuration:
+
+```bash
+nevermined plans register-plan \
+  --plan-metadata plan-metadata.json \
+  --price-config price-config.json \
+  --credits-config credits-config.json
+```
+
+Optional flags:
+- `--nonce` — Custom nonce value
+- `--access-limit` — Maximum number of times the plan can be ordered
+
+### Credits Plan
+
+Create a pay-per-use plan with credits:
+
+```bash
+nevermined plans register-credits-plan \
+  --plan-metadata plan-metadata.json \
+  --price-config price-config.json \
+  --credits-config credits-config.json
+```
+
+**plan-metadata.json**:
+
+```json
+{
+  "name": "My AI Agent - Basic Plan",
+  "description": "100 credits for API access",
+  "tags": ["ai", "assistant", "basic"],
+  "customData": {
+    "category": "AI Assistant"
+  }
+}
+```
+
+**price-config.json** (`PlanPriceConfig`) — charge a fixed crypto price; `amounts` is in the token's smallest unit (e.g. `1000000` = 1 USDC at 6 decimals) and `receivers` collects it (this is what `nevermined plans get-erc20-price-config` / `get-native-token-price-config` emit):
+
+```json
+{
+  "isCrypto": true,
+  "amounts": [1000000],
+  "receivers": ["0xYourReceiverWallet"],
+  "tokenAddress": "0x0000000000000000000000000000000000000000",
+  "contractAddress": "0x0000000000000000000000000000000000000000",
+  "feeController": "0x0000000000000000000000000000000000000000",
+  "externalPriceAddress": "0x0000000000000000000000000000000000000000",
+  "templateAddress": "0x0000000000000000000000000000000000000000"
+}
+```
+
+**credits-config.json** (`PlanCreditsConfig`) — grant 100 credits, burn 1 per request (what `nevermined plans get-fixed-credits-config` emits):
+
+```json
+{
+  "isRedemptionAmountFixed": true,
+  "redemptionType": 4,
+  "onchainMirror": false,
+  "durationSecs": 0,
+  "amount": 100,
+  "minAmount": 1,
+  "maxAmount": 1
+}
+```
+
+### Time-Based Plan
+
+Create a subscription plan with time-limited access:
+
+```bash
+nevermined plans register-time-plan \
+  --plan-metadata plan-metadata.json \
+  --price-config price-config.json \
+  --credits-config credits-config.json
+```
+
+**credits-config.json** (for time plan) (`PlanCreditsConfig`) — a time-limited plan sets `durationSecs > 0` (what `nevermined plans get-expirable-duration-config` emits):
+
+```json
+{
+  "isRedemptionAmountFixed": false,
+  "redemptionType": 4,
+  "onchainMirror": false,
+  "durationSecs": 2592000,
+  "amount": 1,
+  "minAmount": 1,
+  "maxAmount": 1
+}
+```
+
+`durationSecs` is in seconds (2592000 = 30 days).
+
+### Trial Plans
+
+Trial plans can only be purchased once per user and are useful for letting users test your agents.
+
+**Credits trial** (limited by credits):
+
+```bash
+nevermined plans register-credits-trial-plan \
+  --plan-metadata plan-metadata.json \
+  --price-config price-config.json \
+  --credits-config credits-config.json
+```
+
+**Time trial** (limited by duration):
+
+```bash
+nevermined plans register-time-trial-plan \
+  --plan-metadata plan-metadata.json \
+  --price-config price-config.json \
+  --credits-config credits-config.json
+```
+
+## Ordering Plans
+
+### Crypto Payment
+
+Purchase a plan with cryptocurrency:
+
+```bash
+nevermined plans order-plan <plan-id>
+```
+
+### Fiat Payment
+
+Initiate a plan purchase with fiat payment. Returns a URL where the user can complete the payment:
+
+```bash
+nevermined plans order-fiat-plan <plan-id>
+```
+
+## Minting Credits
+
+### Mint Credits
+
+Add credits to a plan and transfer them to a receiver (plan owner only):
+
+```bash
+nevermined plans mint-plan-credits <plan-id> \
+  --credits-amount 1000 \
+  --credits-receiver "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
+```
+
+### Mint Expirable Credits
+
+Add time-limited credits:
+
+```bash
+nevermined plans mint-plan-expirable <plan-id> \
+  --credits-amount 1000 \
+  --credits-receiver "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" \
+  --credits-duration 2592000
+```
+
+The `--credits-duration` flag is optional and specifies duration in seconds.
+
+## Redeeming Credits
+
+Credit redemption (burning credits after a paid request) is performed via the x402 facilitator, not via a dedicated `plans` command. The legacy `nevermined plans redeem-credits` command was removed because the backend exposes no direct redeem endpoint — the only burn path is `POST /api/v1/x402/settle`.
+
+Migration (subscriber side — get an access token):
+
+```bash
+nevermined x402token get-x402-access-token <plan-id> --format json
+# → { "accessToken": "eyJ4NDAyVm..." }
+```
+
+Migration (agent side — verify and settle):
+
+```bash
+# Build the params JSON once
+cat > /tmp/settle-params.json <<EOF
+{
+  "paymentRequired": {
+    "x402Version": 2,
+    "resource": { "url": "https://your-agent.example.com/task" },
+    "accepts": [{
+      "scheme": "nvm:erc4337",
+      "network": "eip155:84532",
+      "planId": "<plan-id>",
+      "extra": { "version": "1" }
+    }],
+    "extensions": {}
+  },
+  "x402AccessToken": "<accessToken from previous step>",
+  "agentRequestId": "<id from verify-permissions response>",
+  "maxAmount": "5"
+}
+EOF
+
+nevermined facilitator verify-permissions --params "$(cat /tmp/settle-params.json)" --format json
+nevermined facilitator settle-permissions --params "$(cat /tmp/settle-params.json)" --format json
+# → { "success": true, "creditsRedeemed": "5", "remainingBalance": "...", ... }
+```
+
+`settle-permissions` is idempotent on `agentRequestId` — replaying the same id returns the same transaction id without double-burning.
+
+## Price Configuration Helpers
+
+The CLI provides helper commands to build price configuration objects:
+
+```bash
+# Free (no payment required)
+nevermined plans get-free-price-config
+
+# Fiat price
+nevermined plans get-fiat-price-config --amount 1000 --receiver "0x123..."
+
+# Crypto price
+nevermined plans get-crypto-price-config --amount 1000 --receiver "0x123..."
+
+# Crypto with specific token
+nevermined plans get-crypto-price-config --amount 1000 --receiver "0x123..." --token-address "0xToken..."
+
+# Native token price
+nevermined plans get-native-token-price-config --amount 1000 --receiver "0x123..."
+
+# ERC20 token price
+nevermined plans get-erc20-price-config --amount 1000 --receiver "0x123..." --token-address "0xToken..."
+
+# EURC (Euro stablecoin) price
+nevermined plans get-eurc-price-config --amount 1000 --receiver "0x123..."
+
+# Pay-as-you-go price
+nevermined plans get-pay-as-you-go-price-config --amount 1000 --receiver "0x123..."
+```
+
+## Credits Configuration Helpers
+
+Helper commands to build credits configuration objects:
+
+```bash
+# Fixed credits (same amount per request)
+nevermined plans get-fixed-credits-config --credits-granted 100 --credits-per-request 1
+
+# Dynamic credits (range per request)
+nevermined plans get-dynamic-credits-config --credits-granted 100 \
+  --min-credits-per-request 1 --max-credits-per-request 10
+
+# Pay-as-you-go credits
+nevermined plans get-pay-as-you-go-credits-config
+
+# Expirable duration
+nevermined plans get-expirable-duration-config --duration-of-plan 2592000
+
+# Non-expirable
+nevermined plans get-non-expirable-duration-config
+```
+
+## Advanced Operations
+
+### Set Onchain Mirror
+
+Mark whether burns of these credits are mirrored on-chain:
+
+```bash
+nevermined plans set-onchain-mirror \
+  --credits-config credits-config.json \
+  --onchain-mirror
+```
+
+### Set Redemption Type
+
+Set the redemption type in a credits configuration:
+
+```bash
+nevermined plans set-redemption-type \
+  --credits-config credits-config.json \
+  --redemption-type "fixed"
+```
+
+## JSON Output for Scripting
+
+Use `--format json` for machine-readable output:
+
+```bash
+# Get plan details as JSON
+PLAN_DATA=$(nevermined plans get-plan "did:nvm:abc123" --format json)
+
+# Extract specific field with jq
+PLAN_NAME=$(echo $PLAN_DATA | jq -r '.name')
+
+echo "Plan: $PLAN_NAME"
+```
+
+## Examples
+
+### Example 1: Create a Basic AI Agent Plan
+
+```bash
+# 1. Create plan metadata file
+cat > plan.json << EOF
+{
+  "name": "ChatBot Basic",
+  "description": "100 API calls for $10",
+  "tags": ["chatbot", "ai"]
+}
+EOF
+
+# 2. Create price configuration (PlanPriceConfig)
+cat > price.json << EOF
+{
+  "isCrypto": true,
+  "amounts": [10000000],
+  "receivers": ["0xYourReceiverWallet"],
+  "tokenAddress": "0x0000000000000000000000000000000000000000",
+  "contractAddress": "0x0000000000000000000000000000000000000000",
+  "feeController": "0x0000000000000000000000000000000000000000",
+  "externalPriceAddress": "0x0000000000000000000000000000000000000000",
+  "templateAddress": "0x0000000000000000000000000000000000000000"
+}
+EOF
+
+# 3. Create credits configuration (PlanCreditsConfig) — 100 credits, burn 1-5 per request
+cat > credits.json << EOF
+{
+  "isRedemptionAmountFixed": false,
+  "redemptionType": 4,
+  "onchainMirror": false,
+  "durationSecs": 0,
+  "amount": 100,
+  "minAmount": 1,
+  "maxAmount": 5
+}
+EOF
+
+# 4. Register the plan
+nevermined plans register-credits-plan \
+  --plan-metadata plan.json \
+  --price-config price.json \
+  --credits-config credits.json
+```
+
+### Example 2: Monitor Plan Balance
+
+```bash
+#!/bin/bash
+PLAN_ID="did:nvm:abc123"
+MIN_CREDITS=10
+
+BALANCE=$(nevermined plans get-plan-balance $PLAN_ID --format json | jq -r '.balance')
+
+if [ "$BALANCE" -lt "$MIN_CREDITS" ]; then
+  echo "Low balance: $BALANCE credits remaining"
+else
+  echo "Balance healthy: $BALANCE credits"
+fi
+```
+
+## Best Practices
+
+### 1. Use Descriptive Metadata
+
+Make your plans discoverable with clear names and descriptions:
+
+```json
+{
+  "name": "GPT-4 API Access - Starter",
+  "description": "1000 GPT-4 API calls per month with 24/7 support",
+  "tags": ["gpt4", "ai", "api", "starter"]
+}
+```
+
+### 2. Set Appropriate Credit Limits
+
+Configure the min/max credits burned per request to prevent abuse (fields of `PlanCreditsConfig`):
+
+```json
+{
+  "minAmount": 1,
+  "maxAmount": 10
+}
+```
+
+### 3. Test in Sandbox First
+
+Always test new plans in sandbox before going live:
+
+```bash
+# Test in sandbox
+nevermined --profile sandbox plans register-credits-plan \
+  --plan-metadata metadata.json \
+  --price-config price.json \
+  --credits-config credits.json
+
+# Verify it works
+nevermined --profile sandbox plans get-plan <plan-id>
+```
+
+## Common Issues
+
+### "Insufficient balance"
+
+When registering plans, ensure you have enough credits or tokens in your account.
+
+### "Plan not found"
+
+Ensure you're using the correct environment and plan ID:
+
+```bash
+# Check which environment you're using
+nevermined config show
+
+# Try the correct profile
+nevermined --profile sandbox plans get-plan <plan-id>
+```
+
+## Next Steps
+
+- [Agents](./agents.md) - Register agents with your plans
+- [Purchases](./purchases.md) - Order plans and make payments
+- [Querying](./querying.md) - Query agents with access tokens
diff --git a/docs/api-reference/cli/purchases.md b/docs/api-reference/cli/purchases.md
new file mode 100644
index 00000000..9ae677e2
--- /dev/null
+++ b/docs/api-reference/cli/purchases.md
@@ -0,0 +1,269 @@
+---
+title: "Making Purchases"
+description: "Complete guide to ordering payment plans and managing credits with the Nevermined CLI"
+icon: "cart-shopping"
+---
+
+# Making Purchases
+
+Complete guide to ordering payment plans and managing credits with the Nevermined CLI.
+
+## Overview
+
+Purchasing a payment plan gives you access to AI agents and services. Once you order a plan, you receive credits or time-based access that you can use to query agents.
+
+## Ordering a Plan
+
+### Crypto Payment
+
+Purchase a payment plan with cryptocurrency:
+
+```bash
+nevermined plans order-plan <plan-id>
+```
+
+Example:
+
+```bash
+nevermined plans order-plan "did:nvm:abc123"
+```
+
+Output:
+
+```
+Plan Order Success
+Plan ID: did:nvm:abc123
+Credits Purchased: 100
+Transaction Hash: 0x1234567890abcdef...
+Status: Confirmed
+```
+
+### Fiat Payment
+
+Initiate a plan purchase with fiat. This returns a URL where you can complete the payment:
+
+```bash
+nevermined plans order-fiat-plan <plan-id>
+```
+
+Example:
+
+```bash
+nevermined plans order-fiat-plan "did:nvm:abc123"
+```
+
+## Checking Your Credits
+
+### View Plan Balance
+
+Check how many credits you have remaining:
+
+```bash
+# Your balance
+nevermined plans get-plan-balance <plan-id>
+
+# Balance for specific address
+nevermined plans get-plan-balance <plan-id> --account-address "0x123..."
+```
+
+Example output:
+
+```
+Plan Balance
+Plan ID: did:nvm:abc123
+Credits Remaining: 75
+```
+
+### Monitor Multiple Plans
+
+Check balances for all your plans:
+
+```bash
+#!/bin/bash
+PLANS=("did:nvm:plan1" "did:nvm:plan2" "did:nvm:plan3")
+
+for PLAN in "${PLANS[@]}"; do
+  echo "Checking balance for $PLAN..."
+  nevermined plans get-plan-balance $PLAN
+  echo ""
+done
+```
+
+## Refilling Credits
+
+### Purchase Additional Credits
+
+Re-order a plan to add more credits to your existing balance:
+
+```bash
+nevermined plans order-plan <plan-id>
+```
+
+### Bulk Credit Purchase
+
+Order multiple plans at once:
+
+```bash
+#!/bin/bash
+PLANS=("did:nvm:plan1" "did:nvm:plan2")
+
+for PLAN in "${PLANS[@]}"; do
+  echo "Ordering $PLAN..."
+  nevermined plans order-plan $PLAN
+done
+```
+
+## Credit Usage
+
+### Set Up Balance Monitoring
+
+Create a script to alert when credits run low:
+
+```bash
+#!/bin/bash
+PLAN_ID="did:nvm:abc123"
+MIN_CREDITS=10
+
+BALANCE=$(nevermined plans get-plan-balance $PLAN_ID --format json | jq -r '.balance')
+
+if [ "$BALANCE" -lt "$MIN_CREDITS" ]; then
+  echo "LOW CREDITS ALERT"
+  echo "Plan: $PLAN_ID"
+  echo "Remaining: $BALANCE credits"
+fi
+```
+
+### Auto-Refill Script
+
+Automatically refill credits when low:
+
+```bash
+#!/bin/bash
+# Run as cron job: 0 */6 * * * /path/to/auto-refill.sh
+
+PLAN_ID="did:nvm:abc123"
+MIN_CREDITS=20
+
+BALANCE=$(nevermined plans get-plan-balance $PLAN_ID --format json | jq -r '.balance')
+
+if [ "$BALANCE" -lt "$MIN_CREDITS" ]; then
+  echo "$(date): Credits low ($BALANCE), ordering more..."
+  nevermined plans order-plan $PLAN_ID
+
+  if [ $? -eq 0 ]; then
+    NEW_BALANCE=$(nevermined plans get-plan-balance $PLAN_ID --format json | jq -r '.balance')
+    echo "$(date): New balance: $NEW_BALANCE credits"
+  else
+    echo "$(date): ERROR - Failed to order credits"
+  fi
+else
+  echo "$(date): Balance healthy: $BALANCE credits"
+fi
+```
+
+## Examples
+
+### Example 1: Complete Purchase Flow
+
+```bash
+#!/bin/bash
+
+# 1. Browse available plans
+echo "Available Plans:"
+nevermined plans get-plans
+
+# 2. Get details about a specific plan
+PLAN_ID="did:nvm:abc123"
+nevermined plans get-plan $PLAN_ID
+
+# 3. Check current balance
+echo "Current balance:"
+nevermined plans get-plan-balance $PLAN_ID
+
+# 4. Purchase the plan
+echo "Purchasing plan..."
+nevermined plans order-plan $PLAN_ID
+
+# 5. Verify purchase
+echo "New balance:"
+nevermined plans get-plan-balance $PLAN_ID
+
+# 6. Get access token for using the service
+echo "Getting access token..."
+nevermined x402token get-x402-access-token $PLAN_ID
+```
+
+### Example 2: Team Credit Management
+
+```bash
+#!/bin/bash
+TEAM_PLANS=("did:nvm:plan1" "did:nvm:plan2" "did:nvm:plan3")
+
+# Purchase for entire team
+for PLAN in "${TEAM_PLANS[@]}"; do
+  echo "Ordering $PLAN for team..."
+  nevermined plans order-plan $PLAN
+done
+
+# Generate team usage report
+echo "Team Balances:"
+for PLAN in "${TEAM_PLANS[@]}"; do
+  nevermined plans get-plan-balance $PLAN --format json | jq '{plan: .planId, remaining: .balance}'
+done
+```
+
+## Best Practices
+
+### 1. Monitor Credit Levels
+
+Set up monitoring to avoid service interruptions:
+
+```bash
+# Daily cron job
+0 9 * * * /path/to/check-credits.sh
+```
+
+### 2. Plan Ahead
+
+Purchase credits before you need them to avoid delays.
+
+### 3. Use Automation
+
+Implement auto-refill to ensure continuous service:
+
+```bash
+# Check every 6 hours
+0 */6 * * * /path/to/auto-refill.sh
+```
+
+### 4. Use JSON Output for Scripting
+
+Always use `--format json` in scripts:
+
+```bash
+BALANCE=$(nevermined plans get-plan-balance $PLAN_ID --format json | jq -r '.balance')
+```
+
+## Common Issues
+
+### "Insufficient funds"
+
+Ensure your wallet has enough balance for crypto payments.
+
+### "Plan not available"
+
+The plan may be sold out or no longer active:
+
+```bash
+# Verify plan status
+nevermined plans get-plan <plan-id>
+
+# Look for alternative plans
+nevermined plans get-plans
+```
+
+## Next Steps
+
+- [Querying](./querying.md) - Use your credits to query agents
+- [Plans](./plans.md) - Learn about different plan types
+- [Agents](./agents.md) - Discover available agents
diff --git a/docs/api-reference/cli/querying.md b/docs/api-reference/cli/querying.md
new file mode 100644
index 00000000..d06ec206
--- /dev/null
+++ b/docs/api-reference/cli/querying.md
@@ -0,0 +1,586 @@
+---
+title: "Querying Agents"
+description: "Complete guide to accessing AI agents using x402 access tokens and the payment-signature header with the Nevermined CLI"
+icon: "messages"
+---
+
+# Querying Agents
+
+Complete guide to accessing AI agents using X402 access tokens with the Nevermined CLI.
+
+## Overview
+
+After purchasing a payment plan, you can query AI agents using X402 access tokens. The X402 protocol enables pay-per-use access with automatic credit deduction.
+
+## Getting an Access Token
+
+### Generate X402 Token
+
+Get an access token for a purchased plan:
+
+```bash
+nevermined x402token get-x402-access-token <plan-id>
+```
+
+Example:
+
+```bash
+nevermined x402token get-x402-access-token "did:nvm:abc123"
+```
+
+Optional flags:
+- `--agent-id` — Target agent ID
+- `--redemption-limit` — Maximum credits that can be redeemed
+- `--order-limit` — Maximum number of orders
+- `--expiration` — Token expiration time
+
+Example with options:
+
+```bash
+nevermined x402token get-x402-access-token "did:nvm:abc123" \
+  --agent-id "did:nvm:agent456" \
+  --redemption-limit 100 \
+  --expiration 3600
+```
+
+Output:
+
+```
+X402 Access Token
+Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Plan ID: did:nvm:abc123
+
+Use this token in the payment-signature header:
+  curl -H "payment-signature: eyJhbGci..." https://agent-api.example.com
+```
+
+### Token Format
+
+The token is a JWT containing:
+- Plan ID
+- Subscriber address
+- Credits information
+- Signature for verification
+
+### Save Token for Reuse
+
+Store the token for multiple requests:
+
+```bash
+# Get token and save to file
+TOKEN=$(nevermined x402token get-x402-access-token "did:nvm:abc123" --format json | jq -r '.token')
+echo $TOKEN > ~/.nvm-token
+
+# Use token from file
+curl -H "payment-signature: $(cat ~/.nvm-token)" https://agent-api.example.com/query
+```
+
+## Using X402 Tokens
+
+### HTTP Requests with curl
+
+Query an agent using curl:
+
+```bash
+# Get access token
+TOKEN=$(nevermined x402token get-x402-access-token "did:nvm:abc123" --format json | jq -r '.token')
+
+# Make request with payment-signature header
+curl -X POST https://agent-api.example.com/v1/chat \
+  -H "Content-Type: application/json" \
+  -H "payment-signature: $TOKEN" \
+  -d '{
+    "message": "Hello, AI assistant!",
+    "temperature": 0.7
+  }'
+```
+
+### With JavaScript/TypeScript
+
+```javascript
+// Get token from CLI
+const { execSync } = require('child_process')
+
+const planId = 'did:nvm:abc123'
+const tokenCmd = `nevermined x402token get-x402-access-token ${planId} --format json`
+const result = JSON.parse(execSync(tokenCmd).toString())
+const token = result.token
+
+// Make API request
+const response = await fetch('https://agent-api.example.com/v1/chat', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'payment-signature': token
+  },
+  body: JSON.stringify({
+    message: 'Hello, AI assistant!',
+    temperature: 0.7
+  })
+})
+
+const data = await response.json()
+console.log(data)
+```
+
+### With Python
+
+```python
+import subprocess
+import json
+import requests
+
+# Get token from CLI
+plan_id = 'did:nvm:abc123'
+cmd = f'nevermined x402token get-x402-access-token {plan_id} --format json'
+result = subprocess.run(cmd.split(), capture_output=True, text=True)
+token_data = json.loads(result.stdout)
+token = token_data['token']
+
+# Make API request
+response = requests.post(
+    'https://agent-api.example.com/v1/chat',
+    headers={
+        'Content-Type': 'application/json',
+        'payment-signature': token
+    },
+    json={
+        'message': 'Hello, AI assistant!',
+        'temperature': 0.7
+    }
+)
+
+print(response.json())
+```
+
+## Verifying Requests
+
+### Manual Verification
+
+Verify that a request is valid before processing (for agent owners):
+
+```bash
+nevermined facilitator verify-permissions \
+  --params verify.json
+```
+
+**verify.json**:
+
+```json
+{
+  "paymentRequired": "eyJhbGci...",
+  "x402AccessToken": "eyJhbGci...",
+  "maxAmount": "5"
+}
+```
+
+### Automatic Verification (SDK)
+
+For agent implementations, use the SDK for automatic verification:
+
+```typescript
+import { Payments, buildPaymentRequired } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox'
+})
+
+// Build payment requirements for your plan/agent
+const paymentRequired = buildPaymentRequired({
+  planId: 'did:nvm:abc123',
+  endpoint: '/v1/chat',
+  agentId: process.env.NVM_AGENT_ID!,
+  httpVerb: 'POST'
+})
+
+// Verify incoming request
+const verification = await payments.facilitator.verifyPermissions({
+  paymentRequired,
+  x402AccessToken: req.headers['payment-signature'] as string,
+  maxAmount: BigInt(5)
+})
+
+if (!verification.isValid) {
+  return res.status(402).json({ error: 'Payment required' })
+}
+```
+
+## Settling Credits
+
+### Burn Credits After Use
+
+After processing a request, burn the credits (agent owners):
+
+```bash
+nevermined facilitator settle-permissions \
+  --params settle.json
+```
+
+**settle.json**:
+
+```json
+{
+  "paymentRequired": "eyJhbGci...",
+  "x402AccessToken": "eyJhbGci...",
+  "maxAmount": "5"
+}
+```
+
+### Automatic Settlement (SDK)
+
+Integrate settlement into your agent:
+
+```typescript
+// After processing request
+await payments.facilitator.settlePermissions({
+  paymentRequired,
+  x402AccessToken: req.headers['payment-signature'] as string,
+  maxAmount: BigInt(5)
+})
+```
+
+## Complete Query Workflow
+
+### End-to-End Example
+
+Complete flow from purchase to query:
+
+```bash
+#!/bin/bash
+# Complete agent query workflow
+
+PLAN_ID="did:nvm:abc123"
+AGENT_API="https://agent-api.example.com/v1/chat"
+
+# 1. Purchase plan if needed
+echo "Checking balance..."
+BALANCE=$(nevermined plans get-plan-balance $PLAN_ID --format json | jq -r '.balance')
+
+if [ "$BALANCE" -lt "10" ]; then
+  echo "Low balance, purchasing plan..."
+  nevermined plans order-plan $PLAN_ID
+fi
+
+# 2. Get X402 access token
+echo "Getting access token..."
+TOKEN=$(nevermined x402token get-x402-access-token $PLAN_ID --format json | jq -r '.token')
+
+# 3. Query the agent
+echo "Querying agent..."
+RESPONSE=$(curl -s -X POST $AGENT_API \
+  -H "Content-Type: application/json" \
+  -H "payment-signature: $TOKEN" \
+  -d '{
+    "message": "Explain quantum computing in simple terms",
+    "temperature": 0.7
+  }')
+
+echo "Response:"
+echo $RESPONSE | jq '.'
+
+# 4. Check updated balance
+echo "Updated balance:"
+nevermined plans get-plan-balance $PLAN_ID
+```
+
+## Advanced Usage
+
+### Batch Queries
+
+Process multiple queries efficiently:
+
+```bash
+#!/bin/bash
+# Batch query script
+
+PLAN_ID="did:nvm:abc123"
+AGENT_API="https://agent-api.example.com/v1/chat"
+
+# Get token once
+TOKEN=$(nevermined x402token get-x402-access-token $PLAN_ID --format json | jq -r '.token')
+
+# Array of questions
+QUESTIONS=(
+  "What is machine learning?"
+  "Explain neural networks"
+  "What is deep learning?"
+)
+
+# Query each
+for QUESTION in "${QUESTIONS[@]}"; do
+  echo "Query: $QUESTION"
+
+  RESPONSE=$(curl -s -X POST $AGENT_API \
+    -H "Content-Type: application/json" \
+    -H "payment-signature: $TOKEN" \
+    -d "{\"message\": \"$QUESTION\"}")
+
+  echo "Answer: $(echo $RESPONSE | jq -r '.answer')"
+  echo "Credits used: $(echo $RESPONSE | jq -r '.creditsUsed')"
+  echo "---"
+done
+
+# Check final balance
+nevermined plans get-plan-balance $PLAN_ID
+```
+
+### Rate-Limited Queries
+
+Respect rate limits:
+
+```bash
+#!/bin/bash
+# Rate-limited query script
+
+PLAN_ID="did:nvm:abc123"
+AGENT_API="https://agent-api.example.com/v1/chat"
+RATE_LIMIT=10  # requests per minute
+DELAY=$(echo "60 / $RATE_LIMIT" | bc -l)
+
+TOKEN=$(nevermined x402token get-x402-access-token $PLAN_ID --format json | jq -r '.token')
+
+for i in {1..50}; do
+  echo "Request $i..."
+
+  curl -s -X POST $AGENT_API \
+    -H "Content-Type: application/json" \
+    -H "payment-signature: $TOKEN" \
+    -d "{\"message\": \"Query $i\"}"
+
+  # Respect rate limit
+  sleep $DELAY
+done
+```
+
+### Error Handling
+
+Handle common errors gracefully:
+
+```bash
+#!/bin/bash
+# Robust query script with error handling
+
+query_agent() {
+  local plan_id=$1
+  local message=$2
+  local max_retries=3
+  local retry_count=0
+
+  while [ $retry_count -lt $max_retries ]; do
+    # Get fresh token
+    TOKEN=$(nevermined x402token get-x402-access-token $plan_id --format json 2>&1)
+
+    if [ $? -ne 0 ]; then
+      echo "Error getting token: $TOKEN"
+      return 1
+    fi
+
+    TOKEN=$(echo $TOKEN | jq -r '.token')
+
+    # Make request
+    RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
+      https://agent-api.example.com/v1/chat \
+      -H "Content-Type: application/json" \
+      -H "payment-signature: $TOKEN" \
+      -d "{\"message\": \"$message\"}")
+
+    HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+    BODY=$(echo "$RESPONSE" | head -n-1)
+
+    case $HTTP_CODE in
+      200)
+        echo "$BODY"
+        return 0
+        ;;
+      402)
+        echo "Insufficient credits. Purchasing more..."
+        nevermined plans order-plan $plan_id
+        ;;
+      429)
+        echo "Rate limit exceeded. Waiting..."
+        sleep 60
+        ;;
+      *)
+        echo "Error $HTTP_CODE: $BODY"
+        ;;
+    esac
+
+    retry_count=$((retry_count + 1))
+    sleep 2
+  done
+
+  echo "Max retries exceeded"
+  return 1
+}
+
+# Usage
+query_agent ""did:nvm:abc123"" "Hello, agent!"
+```
+
+## Monitoring Usage
+
+### Track Credit Consumption
+
+Monitor how credits are used per query:
+
+```bash
+#!/bin/bash
+# Credit usage tracking
+
+PLAN_ID="did:nvm:abc123"
+LOG_FILE="credit-usage.log"
+
+# Get initial balance
+INITIAL=$(nevermined plans get-plan-balance $PLAN_ID --format json | jq -r '.balance')
+
+# Make query
+TOKEN=$(nevermined x402token get-x402-access-token $PLAN_ID --format json | jq -r '.token')
+RESPONSE=$(curl -s -X POST https://agent-api.example.com/v1/chat \
+  -H "payment-signature: $TOKEN" \
+  -d '{"message": "test query"}')
+
+# Get new balance
+FINAL=$(nevermined plans get-plan-balance $PLAN_ID --format json | jq -r '.balance')
+
+# Calculate usage
+USED=$((INITIAL - FINAL))
+
+# Log
+echo "$(date)|Query: test query|Credits used: $USED|Remaining: $FINAL" >> $LOG_FILE
+echo "Credits used: $USED"
+echo "Remaining: $FINAL"
+```
+
+### Usage Reports
+
+Generate usage reports:
+
+```bash
+#!/bin/bash
+# Generate usage report from logs
+
+echo "Credit Usage Report"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Total credits used
+TOTAL_USED=$(awk -F'|' '{sum+=$3} END {print sum}' credit-usage.log | cut -d: -f2)
+echo "Total Credits Used: $TOTAL_USED"
+
+# Average per query
+NUM_QUERIES=$(wc -l < credit-usage.log)
+AVG=$(echo "$TOTAL_USED / $NUM_QUERIES" | bc -l | xargs printf "%.2f")
+echo "Average per Query: $AVG"
+
+# Queries by date
+echo "
+echo "Queries by Date:"
+awk -F'|' '{print substr($1, 1, 10)}' credit-usage.log | sort | uniq -c
+```
+
+## Best Practices
+
+### 1. Token Refresh
+
+Tokens may expire, always get fresh tokens for new sessions:
+
+```bash
+# Don't reuse old tokens
+TOKEN=$(nevermined x402token get-x402-access-token $PLAN_ID --format json | jq -r '.token')
+```
+
+### 2. Credit Management
+
+Monitor balance before queries:
+
+```bash
+BALANCE=$(nevermined plans get-plan-balance $PLAN_ID --format json | jq -r '.balance')
+if [ "$BALANCE" -lt "10" ]; then
+  echo "Low credits, refilling..."
+  nevermined plans order-plan $PLAN_ID
+fi
+```
+
+### 3. Error Recovery
+
+Implement retries with exponential backoff:
+
+```bash
+retry_with_backoff() {
+  local max_attempts=5
+  local timeout=1
+  local attempt=1
+
+  while [ $attempt -le $max_attempts ]; do
+    if "$@"; then
+      return 0
+    fi
+
+    echo "Attempt $attempt failed. Retrying in ${timeout}s..."
+    sleep $timeout
+    timeout=$((timeout * 2))
+    attempt=$((attempt + 1))
+  done
+
+  return 1
+}
+```
+
+### 4. Secure Token Storage
+
+Never commit tokens to version control:
+
+```bash
+# Use environment variables
+export X402_TOKEN=$(nevermined x402token get-x402-access-token $PLAN_ID --format json | jq -r '.token')
+
+# Or secure file storage
+chmod 600 ~/.nvm-token
+```
+
+### 5. Rate Limiting
+
+Respect API rate limits to avoid 429 errors:
+
+```bash
+# Add delays between requests
+sleep 0.1  # 100ms between requests
+```
+
+## Common Issues
+
+### "Invalid token"
+
+Token may be expired or malformed:
+
+```bash
+# Get a fresh token
+nevermined x402token get-x402-access-token $PLAN_ID
+```
+
+### "Insufficient credits"
+
+Your balance is too low:
+
+```bash
+# Check balance
+nevermined plans get-plan-balance $PLAN_ID
+
+# Purchase more
+nevermined plans order-plan $PLAN_ID
+```
+
+### "402 Payment Required"
+
+The agent requires payment but token is invalid or missing:
+
+```bash
+# Ensure payment-signature header is included
+curl -H "payment-signature: $TOKEN" https://agent-api.example.com
+```
+
+## Next Steps
+
+- [Other Commands](./other-commands.md) - Additional CLI features
+- [Purchases](./purchases.md) - Managing your credits
+- [Agents](./agents.md) - Discover more agents
diff --git a/docs/api-reference/openclaw-plugin/commands.md b/docs/api-reference/openclaw-plugin/commands.md
new file mode 100644
index 00000000..d9d36edd
--- /dev/null
+++ b/docs/api-reference/openclaw-plugin/commands.md
@@ -0,0 +1,285 @@
+---
+title: "API Reference"
+description: "All available tools and slash commands in the Nevermined OpenClaw plugin"
+icon: "terminal"
+---
+
+# API Reference
+
+The plugin provides slash commands for chat channels and tools that agents can invoke on behalf of users. Slash commands are triggered directly by users with the `/` prefix, while tools are called by the AI agent in response to natural language requests.
+
+## Authentication Commands
+
+### Log In — `/nvm_login`
+
+Authenticate with the Nevermined platform to enable all payment tools. The plugin supports three authentication flows: automatic browser login, environment selection, and direct API key input.
+
+When using browser login, the plugin starts a temporary local server, opens your default browser to the Nevermined login page, and captures the API key automatically after you sign in. On headless servers where no browser is available, paste your API key directly.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `environment` | string | No | `sandbox` | `sandbox` or `live` |
+
+> **Example prompt:** "Log me in to Nevermined"
+
+```
+/nvm_login
+/nvm_login live
+/nvm_login sandbox:eyJhbG...
+```
+
+---
+
+### Log Out — `/nvm_logout`
+
+End your Nevermined session and remove the stored API key from memory. After logging out, all payment tools will be unavailable until you authenticate again. Use this when switching accounts or when you want to revoke the current session for security.
+
+---
+
+## Subscriber Tools
+
+These tools are designed for users who consume paid AI agent services. They handle the full lifecycle of subscribing to a plan, paying for access, and querying agents.
+
+### Check Credit Balance — `nevermined_checkBalance`
+
+Retrieve the current credit balance for a payment plan. This is useful to verify how many credits remain before making requests, or to confirm that a recent purchase was credited to your account. The response includes the plan name, remaining balance, and whether you are an active subscriber.
+
+If a `planId` is configured in the plugin settings, it is used by default. You can override it per call.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `planId` | string | No | Config `planId` | The payment plan ID to check |
+
+**Example prompt:**
+> How many credits do I have left on my Weather Forecast plan?
+
+**Returns:**
+```json
+{
+  "planId": "did:nv:abc123...",
+  "planName": "Basic Plan",
+  "balance": "95",
+  "isSubscriber": true
+}
+```
+
+---
+
+### Get Access Token — `nevermined_getAccessToken`
+
+Generate an x402 access token that authorizes requests to a paid Nevermined agent. The token is cryptographically signed and contains delegated permissions (order, burn) that allow the agent to verify and settle payments on your behalf.
+
+This tool supports two payment schemes. **Crypto** (the default) uses the `nvm:erc4337` on-chain scheme with session keys and smart accounts. **Fiat** uses the `nvm:card-delegation` scheme, which charges a previously enrolled credit card via Stripe delegation. When using fiat, the plugin automatically looks up your enrolled payment methods and selects the first one unless you specify a `paymentMethodId`.
+
+Most users will not need to call this tool directly — `nevermined_queryAgent` handles token acquisition automatically. Use this tool when you need the raw token for custom integrations or debugging.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `planId` | string | No | Config `planId` | The payment plan ID |
+| `agentId` | string | No | Config `agentId` | The agent ID |
+| `paymentType` | string | No | Config `paymentType` or `"crypto"` | `"crypto"` (nvm:erc4337 scheme) or `"fiat"` (nvm:card-delegation scheme) |
+| `paymentMethodId` | string | No | Auto-selects first enrolled card | Stripe payment method ID (`pm_...`). Only used for fiat. |
+| `spendingLimitCents` | number | No | Config `defaultSpendingLimitCents` or `1000` | Max spend in cents. Only used for fiat. |
+| `delegationDurationSecs` | number | No | Config `defaultDelegationDurationSecs` or `3600` | Delegation duration in seconds. Only used for fiat. |
+
+**Example prompt:**
+> Get me an access token for the Weather Oracle agent so I can call it from my script.
+
+> **Example prompt:** "Get me an access token for the translation agent"
+
+**Returns:**
+```json
+{
+  "accessToken": "eyJhbG..."
+}
+```
+
+---
+
+### Purchase a Crypto Plan — `nevermined_orderPlan`
+
+Purchase a payment plan using cryptocurrency. This initiates an on-chain transaction that transfers the plan's price to the builder's wallet and credits your account with the plan's allotted credits. The transaction is processed through the Nevermined Protocol smart contracts.
+
+Use this for plans priced in native tokens (ETH, MATIC) or ERC-20 tokens (USDC). For plans priced in fiat currency, use `nevermined_orderFiatPlan` instead.
+
+> ⚠️ **Two-step confirmation flow.** This tool spends real money. The first call returns a *quote* — `planId`, `name`, `price`, `credits`, `paymentType`, `environment`, plus the literal `"Re-call with confirm: true to proceed."`. The agent must show that quote to the user and only call again with `confirm: true` once the user has explicitly approved.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `planId` | string | No | Config `planId` | The plan ID to purchase |
+| `confirm` | boolean | No | `false` | Set to `true` only after the user has approved the quote returned by the first call. |
+
+**Example prompt:**
+> Buy the Weather Forecast plan so I can start querying the agent.
+
+**Returns:**
+- Without `confirm: true`: `{ planId, name, price, credits, paymentType, environment, requiresConfirmation: true, message: "Re-call with confirm: true to proceed." }`
+- With `confirm: true`: order confirmation with transaction hash.
+
+---
+
+### Purchase a Fiat Plan — `nevermined_orderFiatPlan`
+
+Purchase a payment plan using fiat currency (USD). Instead of executing an on-chain transaction, this tool returns a Stripe checkout URL where you complete the payment in a browser. Once the payment is confirmed, credits are added to your account.
+
+Use this for plans that have been created with `pricingType: fiat`. For crypto-priced plans, use `nevermined_orderPlan` instead.
+
+> ⚠️ **Two-step confirmation flow.** Same as `nevermined_orderPlan`: the first call returns a quote, the second call (with `confirm: true`) issues the Stripe checkout URL.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `planId` | string | No | Config `planId` | The plan ID to purchase |
+| `confirm` | boolean | No | `false` | Set to `true` only after the user has approved the quote returned by the first call. |
+
+**Example prompt:**
+> I want to subscribe to the Premium Agent plan using my credit card.
+
+**Returns:**
+- Without `confirm: true`: `{ planId, name, price, credits, paymentType: "fiat", environment, requiresConfirmation: true, message: "Re-call with confirm: true to proceed." }`
+- With `confirm: true`:
+```json
+{
+  "result": {
+    "checkoutUrl": "https://checkout.stripe.com/..."
+  }
+}
+```
+
+---
+
+### List Payment Methods — `nevermined_listPaymentMethods`
+
+Retrieve the list of credit cards you have enrolled for fiat payments. Cards are enrolled through the [Nevermined App](https://nevermined.app) under Settings > Payment Methods. Each entry includes the card brand, last four digits, and expiration date.
+
+This is useful to verify which cards are available before making a fiat payment, or to find the `paymentMethodId` for a specific card when you have multiple cards enrolled.
+
+No parameters required.
+
+**Example prompt:**
+> Which credit cards do I have on file for Nevermined payments?
+
+**Returns:**
+```json
+[
+  {
+    "id": "pm_...",
+    "brand": "visa",
+    "last4": "4242",
+    "expMonth": 12,
+    "expYear": 2027
+  }
+]
+```
+
+---
+
+### Query a Paid Agent — `nevermined_queryAgent`
+
+Send a prompt to a paid Nevermined AI agent and get the response. This is the main tool for interacting with agents — it handles the full payment lifecycle in a single call:
+
+1. Acquires an x402 access token (crypto or fiat, depending on `paymentType`)
+2. Sends the prompt to the agent's URL with the `payment-signature` header
+3. Returns the agent's response
+
+If the agent returns a 402 (Payment Required) response, the tool returns an error suggesting you purchase credits first. This typically means your plan has run out of credits or you haven't subscribed yet.
+
+Like `nevermined_getAccessToken`, this tool supports both crypto and fiat payment types. When using fiat, it automatically resolves your enrolled card and builds the delegation config.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `agentUrl` | string | **Yes** | — | The URL of the agent to query |
+| `prompt` | string | **Yes** | — | The prompt to send to the agent |
+| `planId` | string | No | Config `planId` | The payment plan ID |
+| `agentId` | string | No | Config `agentId` | The agent ID |
+| `method` | string | No | `POST` | HTTP method |
+| `paymentType` | string | No | Config `paymentType` or `"crypto"` | `"crypto"` (nvm:erc4337 scheme) or `"fiat"` (nvm:card-delegation scheme) |
+| `paymentMethodId` | string | No | Auto-selects first enrolled card | Stripe payment method ID (`pm_...`). Only used for fiat. |
+| `spendingLimitCents` | number | No | Config `defaultSpendingLimitCents` or `1000` | Max spend in cents. Only used for fiat. |
+| `delegationDurationSecs` | number | No | Config `defaultDelegationDurationSecs` or `3600` | Delegation duration in seconds. Only used for fiat. |
+
+**Example prompts:**
+> Ask the Weather Oracle at https://weather.example.com/agent what the forecast is for Barcelona.
+
+> Query the translation agent at https://translate.example.com/tasks to translate "hello world" into French, and pay with my credit card.
+
+---
+
+## Builder Tools
+
+These tools are designed for agent builders who want to register their AI agents on the Nevermined marketplace and create payment plans that subscribers can purchase.
+
+### Register an Agent — `nevermined_registerAgent`
+
+Register a new AI agent on Nevermined and create an associated payment plan in a single operation. This publishes your agent to the Nevermined marketplace, making it discoverable and purchasable by subscribers.
+
+The tool creates both the agent record (with its endpoint URL) and a payment plan (with pricing and credit allocation). The `pricingType` parameter controls how the plan is priced: `"crypto"` for native blockchain tokens, `"erc20"` for stablecoins like USDC, or `"fiat"` for USD pricing via Stripe.
+
+After registration, the returned `agentId` and `planId` should be saved in your plugin config for the paid endpoint to work.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | **Yes** | Agent name |
+| `description` | string | No | Agent description |
+| `agentUrl` | string | **Yes** | The endpoint URL for the agent |
+| `planName` | string | **Yes** | Name for the payment plan |
+| `priceAmounts` | string | **Yes** | Comma-separated price amounts in wei (crypto) or cents (fiat) |
+| `priceReceivers` | string | **Yes** | Comma-separated receiver addresses |
+| `creditsAmount` | number | **Yes** | Number of credits in the plan |
+| `tokenAddress` | string | No | ERC20 token address (e.g. USDC). Omit for native token. |
+| `pricingType` | string | No | `"crypto"` (default), `"erc20"`, or `"fiat"` |
+
+**Example prompt:**
+> Register a new agent called "Code Review Bot" at https://my-server.com/nevermined/agent with a plan named "Code Review" priced at 1000000 (1 USDC) to address 0xABC... with token 0x036CbD...  granting 10 credits.
+
+> **Example prompt:** "Register my translation agent hosted at https://agent.example.com with a plan named 'Translation Plan' that costs 1000000 wei (1 USDC) sent to address 0x123... for 100 credits"
+
+**Returns:**
+```json
+{
+  "agentId": "did:nv:...",
+  "planId": "did:nv:...",
+  "txHash": "0x..."
+}
+```
+
+---
+
+### Create a Payment Plan — `nevermined_createPlan`
+
+Create a standalone payment plan without associating it with an agent. This is useful when you want to manage plans separately from agents, or when a single plan should grant access to multiple agents.
+
+The plan can be priced in three ways: `"fiat"` sets the price in USD cents (e.g. `"100"` = $1.00) and subscribers pay via Stripe, `"erc20"` sets the price in an ERC-20 token's smallest unit (e.g. `"1000000"` = 1 USDC) and requires a `tokenAddress`, and `"crypto"` (the default) sets the price in the blockchain's native token.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | **Yes** | Plan name |
+| `description` | string | No | Plan description |
+| `priceAmount` | string | **Yes** | Price in cents for fiat (e.g. "100" = $1.00), in token smallest unit for crypto |
+| `receiver` | string | **Yes** | Receiver wallet address (0x...) |
+| `creditsAmount` | number | **Yes** | Number of credits in the plan |
+| `pricingType` | string | No | `"fiat"` for Stripe/USD, `"erc20"` for ERC20 tokens, `"crypto"` for native token (default) |
+| `accessLimit` | string | No | `"credits"` (default) or `"time"` |
+| `tokenAddress` | string | No | ERC20 token contract address. Required when pricingType is "erc20". |
+
+**Example prompt:**
+> Create a fiat payment plan called "Pro Tier" at $5.00 (500 cents) to wallet 0xABC... with 50 credits.
+
+**Returns:**
+```json
+{
+  "planId": "did:nv:..."
+}
+```
+
+---
+
+### List My Plans — `nevermined_listPlans`
+
+Retrieve all payment plans owned by the authenticated builder. This returns the full list of plans you have created, including their IDs, names, and configuration. Useful for finding a `planId` to use with other tools or to review your current offerings.
+
+No parameters required.
+
+**Example prompt:**
+> Show me all the payment plans I've created on Nevermined.
+
+**Returns:** Array of plan objects.
diff --git a/docs/api-reference/openclaw-plugin/getting-started.md b/docs/api-reference/openclaw-plugin/getting-started.md
new file mode 100644
index 00000000..d4e8a292
--- /dev/null
+++ b/docs/api-reference/openclaw-plugin/getting-started.md
@@ -0,0 +1,90 @@
+---
+title: "Getting Started"
+description: "Install and configure the Nevermined OpenClaw plugin in minutes"
+icon: "rocket"
+---
+
+# Getting Started
+
+The Nevermined OpenClaw plugin exposes AI agent payment operations as gateway tools callable from any OpenClaw channel — Telegram, Discord, WhatsApp, and more.
+
+## Prerequisites
+
+- An [OpenClaw](https://openclaw.ai) gateway instance
+- Node.js >= 18.0.0
+- A [Nevermined account](https://nevermined.app) (free to create)
+
+## Installation
+
+Install the plugin from your OpenClaw gateway:
+
+```bash
+openclaw plugin install @nevermined-io/openclaw-plugin@^1.1
+```
+
+The plugin requires `@nevermined-io/payments@^1.1` as a peer dependency. Pin both packages and commit your lockfile so SDK upgrades are explicit.
+
+## Authentication
+
+<Note>
+To interact with the Nevermined API, you need an API key. Follow the [Get Your API Key](/docs/getting-started/get-your-api-key) guide to create one.
+</Note>
+
+### Option A: Browser login (recommended)
+
+Use the `/nvm_login` command from any connected chat channel:
+
+```
+/nvm_login
+```
+
+This opens a browser window where you authenticate with Nevermined. The API key is captured automatically and stored in your gateway config.
+
+To target the live environment:
+
+```
+/nvm_login live
+```
+
+To use a specific API key:
+
+```
+/nvm_login sandbox:eyJhbG...
+```
+
+### Option B: Manual configuration
+
+Add your API key directly to `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "nvmApiKey": "sandbox:eyJhbG...",
+          "environment": "sandbox"
+        }
+      }
+    }
+  }
+}
+```
+
+## Quick Test
+
+After authenticating, verify the plugin is working:
+
+1. **Check your balance** — from any chat channel, the agent can ask `Example prompt: “How many credits do I have left on my plan?”` to verify connectivity.
+
+2. **List plans** — you can ask `Example prompt: Show me all my payment plans”` to see available payment plans.
+
+## Fiat Payments
+
+The plugin also supports fiat payments via credit card delegation. Enroll a card at [nevermined.app](https://nevermined.app), then use `paymentType: fiat` with any token or query tool. See the [guide](./guide.md#fiat-payments-credit-card) for details.
+
+## Next Steps
+
+- [Setup](/docs/api-reference/openclaw-plugin/setup) — full configuration reference
+- [Commands](/docs/api-reference/openclaw-plugin/commands) — all available tools and slash commands
diff --git a/docs/api-reference/openclaw-plugin/guide.md b/docs/api-reference/openclaw-plugin/guide.md
new file mode 100644
index 00000000..0e7fca00
--- /dev/null
+++ b/docs/api-reference/openclaw-plugin/guide.md
@@ -0,0 +1,294 @@
+---
+title: "Building a Paid AI Agent with OpenClaw and Nevermined"
+description: "Step-by-step guide to building, monetizing, and querying a paid AI agent using the Nevermined OpenClaw plugin"
+icon: "book-open"
+---
+
+# Building a Paid AI Agent with OpenClaw and Nevermined
+
+The Nevermined OpenClaw plugin lets you monetize AI agents directly from chat channels. Subscribers pay per-request using the [x402 payment protocol](https://nevermined.ai/docs/api-reference/typescript/x402-protocol), and builders collect revenue automatically through on-chain payment plans.
+
+This guide walks through building a **Weather Oracle** — a paid agent that serves weather forecasts and charges 1 credit per request.
+
+## What You Get
+
+The plugin adds 9 payment tools and 2 slash commands to your OpenClaw gateway:
+
+**Subscriber tools** — for users who consume paid services:
+
+| Tool | Purpose |
+|------|---------|
+| `nevermined_checkBalance` | Check remaining credits on a plan |
+| `nevermined_getAccessToken` | Get an x402 token for authenticating requests (crypto or fiat) |
+| `nevermined_orderPlan` | Purchase a crypto payment plan |
+| `nevermined_orderFiatPlan` | Purchase a fiat payment plan (returns Stripe checkout URL) |
+| `nevermined_listPaymentMethods` | List enrolled credit cards for fiat payments |
+| `nevermined_queryAgent` | Send a paid query to an agent (crypto or fiat) |
+
+**Builder tools** — for developers who create paid services:
+
+| Tool | Purpose |
+|------|---------|
+| `nevermined_registerAgent` | Register an agent with a payment plan (crypto or fiat) |
+| `nevermined_createPlan` | Create a standalone payment plan |
+| `nevermined_listPlans` | List your payment plans |
+
+**Slash commands**: `/nvm_login` and `/nvm_logout` for authentication.
+
+**Paid HTTP endpoint**: An x402-compatible endpoint on the gateway that handles payment verification, request processing, and credit settlement automatically.
+
+## Prerequisites
+
+- An [OpenClaw](https://openclaw.ai) gateway instance (v2026.2+)
+- Node.js >= 18
+- A [Nevermined account](https://nevermined.app) with an API key
+
+> 🔐 **Security expectations.** This plugin issues `payment-signature` bearer tokens that authorise spending against your plan. In production:
+>
+> - **Use HTTPS for every `agentUrl`** passed to `nevermined_queryAgent`. The tool warns when the URL is not `https://` (loopback hosts excepted for local dev).
+> - **Validate agent cards** at `<agentUrl>/.well-known/agent.json` before issuing a paid request — confirm `agentId` and supported X402 schemes match what you expect.
+> - **Never log payment tokens** — redact the `payment-signature` header in pino, winston, OpenTelemetry, and any sentry/datadog/log-shipping layer.
+> - **Confirm before ordering** — `nevermined_orderPlan` and `nevermined_orderFiatPlan` are gated by a `confirm: true` parameter so the agent must show the user the price/credits/environment first.
+
+## Step 1: Install the Plugin
+
+From your OpenClaw gateway server:
+
+```bash
+openclaw plugin install @nevermined-io/openclaw-plugin@^1.1
+```
+
+Or install manually by placing the package in `~/.openclaw/extensions/nevermined/`. Pin the major version and commit your lockfile so SDK upgrades are explicit.
+
+After installation, restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+You should see in the logs:
+
+```
+Registered 9 Nevermined payment tools
+```
+
+## Step 2: Authenticate
+
+Send `/nvm_login` from any connected chat channel (Telegram, Discord, etc.). The plugin supports two flows:
+
+**Browser login** (if your server has a display):
+
+```
+/nvm_login
+```
+
+A browser window opens for Nevermined authentication. The API key is captured automatically.
+
+**Manual login** (headless servers):
+
+```
+/nvm_login sandbox:eyJhbGciOiJFUzI1NksifQ...
+```
+
+Paste your API key directly. Get one from [Nevermined App](https://nevermined.app) under Settings > API Keys.
+
+Use `sandbox` for testing, `live` for production.
+
+## Step 3: Register Your Agent and Payment Plan
+
+Ask your Claw to register an agent. In any chat channel, send a message like:
+
+> Register a Nevermined agent called "Weather Oracle" at URL `https://my-gateway.example.com/nevermined/agent` with a plan named "Weather Forecast" priced at 1000000 (1 USDC) to address `0xYourWalletAddress` with token `0x036CbD53842c5426634e7929541eC2318f3dCF7e` granting 5 credits.
+
+The agent will call `nevermined_registerAgent` with these parameters:
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `name` | Weather Oracle | Display name on Nevermined |
+| `agentUrl` | `https://my-gateway.example.com/nevermined/agent` | Public URL of your paid endpoint |
+| `planName` | Weather Forecast | Name for the payment plan |
+| `priceAmounts` | `1000000` | Price in token units (1 USDC = 1,000,000 wei) |
+| `priceReceivers` | `0xYourWalletAddress` | Your wallet that receives payments |
+| `creditsAmount` | `5` | Credits granted per purchase |
+| `tokenAddress` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` | USDC on Base Sepolia. Omit for native token. |
+
+The tool returns the `agentId` and `planId` — save these for the next step.
+
+## Step 4: Enable the Paid Endpoint
+
+Add the returned IDs and enable the paid endpoint in your gateway config (`~/.openclaw/openclaw.json`):
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "nvmApiKey": "sandbox:eyJhbG...",
+          "environment": "sandbox",
+          "planId": "<your-plan-id>",
+          "agentId": "<your-agent-id>",
+          "enablePaidEndpoint": true,
+          "agentEndpointPath": "/nevermined/agent",
+          "creditsPerRequest": 1
+        }
+      }
+    }
+  }
+}
+```
+
+Restart the gateway. You should see:
+
+```
+Registered 9 Nevermined payment tools
+Registered paid endpoint at /nevermined/agent
+```
+
+The paid endpoint handles the full x402 lifecycle:
+
+1. Extracts the `payment-signature` header from incoming requests
+2. Calls `verifyPermissions` to check the subscriber has credits
+3. Processes the request (runs your agent handler)
+4. Calls `settlePermissions` to burn credits
+5. Returns the response with a `payment-response` header
+
+### Configuration Reference
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `nvmApiKey` | No | — | API key (set via `/nvm_login` or config) |
+| `environment` | No | `sandbox` | `sandbox` for testing, `live` for production |
+| `planId` | No | — | Default plan ID for tools and the paid endpoint |
+| `agentId` | No | — | Default agent ID |
+| `creditsPerRequest` | No | `1` | Credits burned per request |
+| `enablePaidEndpoint` | No | `false` | Enable the x402 paid HTTP endpoint |
+| `agentEndpointPath` | No | `/nevermined/agent` | Path for the paid endpoint |
+
+## Step 5: Test as a Subscriber
+
+From the same gateway (or a different one with a subscriber API key), test the full flow:
+
+### Order the plan
+
+> Order the Weather Oracle plan `<plan-id>`
+
+The Claw calls `nevermined_orderPlan`. You receive 5 credits.
+
+### Check your balance
+
+> Check my Nevermined balance for plan `<plan-id>`
+
+Should show 5 credits.
+
+### Query the agent
+
+> Ask the Weather Oracle at `http://localhost:18789/nevermined/agent` about the weather in Barcelona
+
+The Claw calls `nevermined_queryAgent`, which:
+1. Acquires an x402 access token
+2. Sends the prompt with a `payment-signature` header
+3. The paid endpoint verifies, processes, and settles
+4. Returns the weather forecast
+
+### Verify credit burn
+
+> Check my balance again
+
+Should show 4 credits — one was consumed.
+
+## Fiat Payments (Credit Card)
+
+The plugin supports fiat payments via credit card delegation, allowing users who have enrolled a card through the [Nevermined App](https://nevermined.app) to pay for agent queries without cryptocurrency.
+
+### 1. Enroll a card
+
+Users enroll a credit card via the Nevermined App under Settings > Payment Methods.
+
+### 2. List enrolled cards
+
+> List my payment methods
+
+The Claw calls `nevermined_listPaymentMethods` and returns the enrolled cards with brand, last 4 digits, and expiration.
+
+### 3. Order a fiat plan
+
+> Order the fiat plan `<plan-id>`
+
+The Claw calls `nevermined_orderFiatPlan`, which returns a Stripe checkout URL. The user completes payment in a browser.
+
+### 4. Query an agent with fiat
+
+> Ask the Weather Oracle at `http://localhost:18789/nevermined/agent` about the weather in Paris, pay with my credit card
+
+The Claw calls `nevermined_queryAgent` with `paymentType: fiat`. The plugin:
+1. Looks up enrolled payment methods (or uses the specified `paymentMethodId`)
+2. Gets an x402 access token using the `nvm:card-delegation` scheme
+3. Sends the request with the `payment-signature` header
+4. The agent verifies and settles as usual
+
+You can also set `paymentType: fiat` in the plugin config to make fiat the default for all calls.
+
+## Custom Agent Handlers
+
+The plugin includes a mock weather handler for demonstration. To use your own logic, pass a custom `agentHandler` when registering the plugin:
+
+```typescript
+import neverminedPlugin from '@nevermined-io/openclaw-plugin'
+
+neverminedPlugin.register(api, {
+  agentHandler: async (body) => {
+    const response = await myAIModel.generate(body.prompt)
+    return { result: response }
+  },
+})
+```
+
+The handler receives `{ prompt: string }` and returns any JSON-serializable object.
+
+## Credit Balance Awareness
+
+When the plugin is authenticated and a `planId` is configured, it automatically injects the current credit balance into the agent's context before each prompt. This means your Claw can proactively warn users when credits are running low:
+
+> "You have 2 credits remaining on the Weather Forecast plan. Consider ordering more credits."
+
+The balance is cached for 60 seconds to avoid excessive API calls.
+
+## How It Works
+
+The plugin implements the [x402 payment protocol](https://nevermined.ai/docs/api-reference/typescript/x402-protocol) for agent-to-agent payments. It supports two payment schemes:
+
+- **Crypto** (`nvm:erc4337`) — on-chain payments using session keys and smart accounts
+- **Fiat** (`nvm:card-delegation`) — credit card payments via Stripe delegation
+
+Both schemes follow the same token flow:
+
+```
+Subscriber Claw                    Builder Claw (Gateway)
+      │                                     │
+      │  1. getX402AccessToken(planId,       │
+      │     tokenOptions)                    │
+      │─────────────────────────────────────>│  Nevermined API
+      │<─────────────────────────────────────│  returns token
+      │                                     │
+      │  2. POST /nevermined/agent           │
+      │     Header: payment-signature: token │
+      │     Body: { prompt: "..." }          │
+      │─────────────────────────────────────>│
+      │                                     │  3. verifyPermissions()
+      │                                     │  4. Process request
+      │                                     │  5. settlePermissions()
+      │  6. Response + payment-response hdr  │
+      │<─────────────────────────────────────│
+```
+
+For crypto, credits are managed on-chain through the Nevermined Protocol. For fiat, credits are charged against the delegated card via Stripe. In both cases, `verifyPermissions` checks the subscriber's balance without consuming credits, and `settlePermissions` consumes them only after successful processing.
+
+## Next Steps
+
+- [Commands Reference](./commands.md) — full parameter documentation for all tools
+- [Setup Reference](./setup.md) — detailed configuration options
+- [Nevermined Docs](https://nevermined.ai/docs) — platform documentation
+- [x402 Protocol](https://nevermined.ai/docs/api-reference/typescript/x402-protocol) — payment protocol specification
+- [OpenClaw Plugin Development](https://docs.openclaw.ai/tools/plugin) — building OpenClaw plugins
diff --git a/docs/api-reference/openclaw-plugin/index.md b/docs/api-reference/openclaw-plugin/index.md
new file mode 100644
index 00000000..b649050e
--- /dev/null
+++ b/docs/api-reference/openclaw-plugin/index.md
@@ -0,0 +1,120 @@
+# @nevermined-io/openclaw-plugin
+
+OpenClaw plugin for [Nevermined](https://nevermined.io) — exposes AI agent payment operations as gateway tools callable from any OpenClaw channel (Telegram, Discord, WhatsApp, etc.).
+
+## Official source & provenance
+
+This plugin is published from the [`nevermined-io/payments`](https://github.com/nevermined-io/payments) monorepo (subdirectory `openclaw/`) by Nevermined AG.
+
+| | |
+|---|---|
+| **npm package** | [`@nevermined-io/openclaw-plugin`](https://www.npmjs.com/package/@nevermined-io/openclaw-plugin) — published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) attestations from this repo's `release.yml` workflow. |
+| **GitHub repository** | https://github.com/nevermined-io/payments (subdirectory [`openclaw/`](https://github.com/nevermined-io/payments/tree/main/openclaw)) |
+| **License** | Apache-2.0 |
+| **Security policy** | https://github.com/nevermined-io/payments/security/policy |
+| **Issue tracker** | https://github.com/nevermined-io/payments/issues |
+
+> ✅ **Official ClawHub listing.** The official skill lives at [`clawhub.ai/nevermined-io/nevermined`](https://clawhub.ai/nevermined-io/nevermined) under the `nevermined-io` org publisher. Treat any other ClawHub publisher as a third-party mirror until further notice. The canonical npm package is [`@nevermined-io/openclaw-plugin`](https://www.npmjs.com/package/@nevermined-io/openclaw-plugin).
+>
+> 🔐 **Never log payment tokens.** x402 access tokens (the `payment-signature` header) are bearer credentials. Treat them like API keys: redact them in any debug output, log pipeline, or telemetry exporter (pino, winston, OpenTelemetry, etc.).
+
+## Installation
+
+```bash
+openclaw plugin install @nevermined-io/openclaw-plugin@^1.1
+```
+
+The plugin requires `@nevermined-io/payments@^1.1` as a peer dependency. Pin both packages in production deployments (lockfiles, container images) so SDK upgrades are explicit and reviewable.
+
+## Authentication
+
+The plugin supports two ways to provide your Nevermined API key:
+
+### Option A: Slash command (recommended)
+
+Use the `/nvm_login` command from any chat channel. This opens a browser window where you authenticate with Nevermined, and the API key is captured automatically.
+
+```
+/nvm_login              # Login to sandbox (default)
+/nvm_login live         # Login to live environment
+/nvm_login <api-key>    # Paste an API key directly
+/nvm_logout             # Remove stored API key
+```
+
+On headless servers where a browser can't open, the command provides manual instructions with a login URL.
+
+### Option B: Manual configuration
+
+Add your API key directly to `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "nvmApiKey": "sandbox:eyJhbG...",
+          "environment": "sandbox",
+          "planId": "<your-plan-id>",
+          "agentId": "<your-agent-id>",
+          "creditsPerRequest": 1,
+          "enablePaidEndpoint": false,
+          "agentEndpointPath": "/nevermined/agent"
+        }
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `nvmApiKey` | No | — | Your Nevermined API key (or use `/nvm_login`) |
+| `environment` | No | `sandbox` | `sandbox` or `live` |
+| `planId` | No | — | Default plan ID for subscriber tools |
+| `agentId` | No | — | Default agent ID for multi-agent plans |
+| `creditsPerRequest` | No | `1` | Credits consumed per request |
+| `enablePaidEndpoint` | No | `false` | Enable the x402 paid HTTP endpoint on the gateway |
+| `agentEndpointPath` | No | `/nevermined/agent` | HTTP path for the paid agent endpoint |
+
+## Available Tools
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/nvm_login [environment]` | Authenticate via browser login or paste an API key |
+| `/nvm_logout` | Remove stored API key |
+
+### Subscriber Tools
+
+| Tool | Description | Key Params |
+|------|-------------|------------|
+| `nevermined_checkBalance` | Check credit balance for a plan | `planId` |
+| `nevermined_getAccessToken` | Get an x402 access token | `planId`, `agentId` |
+| `nevermined_orderPlan` | Purchase a crypto payment plan (two-step: returns a quote until `confirm: true` is passed) | `planId`, `confirm` |
+| `nevermined_orderFiatPlan` | Order a fiat payment plan (two-step: returns a quote until `confirm: true` is passed) | `planId`, `confirm` |
+| `nevermined_queryAgent` | Query an agent end-to-end (HTTPS recommended) | `agentUrl`, `prompt`, `planId`, `agentId` |
+
+### Builder Tools
+
+| Tool | Description | Key Params |
+|------|-------------|------------|
+| `nevermined_registerAgent` | Register an agent with a plan | `name`, `agentUrl`, `planName`, `priceAmounts`, `priceReceivers`, `creditsAmount`, `tokenAddress` |
+| `nevermined_createPlan` | Create a payment plan | `name`, `priceAmounts`, `priceReceivers`, `creditsAmount`, `tokenAddress` |
+| `nevermined_listPlans` | List your plans | — |
+
+## Documentation
+
+- [User Guide](./guide.md) — step-by-step tutorial building a paid Weather Oracle agent
+- [Commands Reference](./commands.md) — full parameter documentation for all tools
+- [Setup Reference](./setup.md) — detailed configuration options
+- [Nevermined Docs](https://nevermined.ai/docs)
+- [Payments SDK](https://github.com/nevermined-io/payments)
+
+## License
+
+Apache-2.0
diff --git a/docs/api-reference/openclaw-plugin/setup.md b/docs/api-reference/openclaw-plugin/setup.md
new file mode 100644
index 00000000..62ad325b
--- /dev/null
+++ b/docs/api-reference/openclaw-plugin/setup.md
@@ -0,0 +1,79 @@
+---
+title: "Setup"
+description: "Full configuration reference for the Nevermined OpenClaw plugin"
+icon: "gear"
+---
+
+# Setup
+
+## Configuration
+
+The plugin reads its configuration from the `plugins.openclaw-plugin` section of your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "nvmApiKey": "sandbox:eyJhbG...",
+          "environment": "sandbox",
+          "planId": "did:nv:abc123...",
+          "agentId": "did:nv:def456...",
+          "creditsPerRequest": 1,
+          "enablePaidEndpoint": false,
+          "agentEndpointPath": "/nevermined/agent",
+          "paymentType": "crypto",
+          "defaultSpendingLimitCents": 1000,
+          "defaultDelegationDurationSecs": 3600
+        }
+      }
+    }
+  }
+}
+```
+
+### Configuration Fields
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `nvmApiKey` | No | — | Your Nevermined API key. Can be set via `/nvm_login` instead. |
+| `environment` | No | `sandbox` | Target environment: `sandbox` for testing, `live` for production. |
+| `planId` | No | — | Default payment plan ID. When set, subscriber tools use this plan automatically. |
+| `agentId` | No | — | Default agent ID. Required for plans with multiple agents. |
+| `creditsPerRequest` | No | `1` | Number of credits consumed per request. |
+| `enablePaidEndpoint` | No | `false` | Enable the x402 paid HTTP endpoint on the gateway. |
+| `agentEndpointPath` | No | `/nevermined/agent` | HTTP path for the paid agent endpoint. |
+| `paymentType` | No | `crypto` | Default payment type: `crypto` (nvm:erc4337) or `fiat` (nvm:card-delegation). |
+| `defaultSpendingLimitCents` | No | `1000` | Default max spend in cents ($10) for fiat payments. |
+| `defaultDelegationDurationSecs` | No | `3600` | Default delegation duration in seconds (1 hour) for fiat payments. |
+
+### Environment Details
+
+| Environment | Description | Use Case |
+|-------------|-------------|----------|
+| `sandbox` | Test environment on Base Sepolia | Development, testing, integration |
+| `live` | Production environment on Base Mainnet | Live deployments with real payments |
+
+## Authentication Flow
+
+The plugin supports a browser-based login flow identical to the [Nevermined CLI](/docs/api-reference/cli/getting-started):
+
+1. User sends `/nvm_login` in any chat channel
+2. The plugin starts a local HTTP server on a random port
+3. A browser window opens to the Nevermined login page
+4. After authentication, Nevermined redirects back with the API key
+5. The key is stored in the plugin's in-memory config for the current session
+
+The login times out after 5 minutes if no authentication is received.
+
+### Logging Out
+
+Send `/nvm_logout` or call `nvm_logout` to remove the stored API key. All payment tools will require re-authentication after logout.
+
+## Default Values
+
+When `planId` and `agentId` are set in the config, all subscriber tools (`checkBalance`, `getAccessToken`, `orderPlan`, `queryAgent`) use them as defaults. You can always override them per-call by passing the parameter explicitly.
+
+This is useful for gateways that serve a single plan — configure it once and all tools work without extra parameters.
diff --git a/docs/api-reference/typescript/a2a-integration.md b/docs/api-reference/typescript/a2a-integration.md
new file mode 100644
index 00000000..696629dc
--- /dev/null
+++ b/docs/api-reference/typescript/a2a-integration.md
@@ -0,0 +1,646 @@
+---
+title: "A2A Integration"
+description: "Enable agent-to-agent communication with payment-protected streaming and task execution"
+icon: "share-nodes"
+---
+
+# A2A Integration
+
+The Agent-to-Agent (A2A) protocol integration enables AI agents to communicate with each other using payment-protected message streams. The Nevermined Payments Library provides complete A2A server functionality with automatic payment handling.
+
+## Overview of A2A Integration
+
+The A2A integration provides:
+- **Agent Card**: Payment metadata extension for discovery
+- **Streaming Support**: Real-time task updates via Server-Sent Events
+- **Task Management**: Async execution with status tracking
+- **Credit Burning**: Automatic credit settlement after task completion
+- **EventBus Pattern**: Clean event-driven architecture for task execution
+
+## Build Payment Agent Card
+
+The agent card is published at the canonical `/.well-known/agent-card.json` (A2A 0.3+), with the legacy `/.well-known/agent.json` kept as a backward-compat alias. It includes payment metadata. Before sending a paid request, **clients should fetch and validate the target agent's card** to confirm the expected `agentId`, the `capabilities`, and the supported X402 schemes — this protects against routing payment tokens to a typosquatted or unauthorised endpoint:
+
+```typescript
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1'])
+
+const cardUrl = new URL('/.well-known/agent-card.json', agentUrl)
+const card = await fetch(cardUrl, { method: 'GET' }).then((r) => r.json())
+
+if (card.agentId !== expectedAgentId) {
+  throw new Error(`Agent card mismatch: expected ${expectedAgentId}, got ${card.agentId}`)
+}
+if (cardUrl.protocol !== 'https:' && !LOOPBACK_HOSTS.has(cardUrl.hostname)) {
+  console.warn(`Agent card fetched over ${cardUrl.protocol} — production traffic must use HTTPS.`)
+}
+```
+
+
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Build agent card with payment extension
+const agentCard = Payments.a2a.buildPaymentAgentCard(
+  {
+    name: 'Weather AI Agent',
+    description: 'Real-time weather forecasts and analysis',
+    version: '1.0.0',
+    protocolVersion: '0.3.0',
+    url: 'http://localhost:6000/a2a/',
+    capabilities: {
+      streaming: true,
+      pushNotifications: false,
+    },
+    defaultInputModes: ['text'],
+    defaultOutputModes: ['text'],
+    skills: [],
+  },
+  {
+    agentId: process.env.NVM_AGENT_ID!,
+    planId: process.env.NVM_PLAN_ID!,
+    credits: 5,                      // Fixed credit cost
+    paymentType: 'fixed',            // 'fixed' or 'dynamic'
+    costDescription: '5 credits per request (optional)',
+  }
+)
+```
+
+## Payment Extension Structure
+
+The agent card declares two extensions in `capabilities.extensions`: the Nevermined payment extension (pricing metadata) and the official a2a-x402 extension (`https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2`), which signals support for the standards-compliant in-band x402 v2 flow (see below). Both are emitted for one release; `urn:nevermined:payment` will be dropped once clients migrate to v0.2 only.
+
+```json
+{
+  "capabilities": {
+    "streaming": true,
+    "extensions": [
+      {
+        "uri": "urn:nevermined:payment",
+        "required": false,
+        "params": {
+          "paymentType": "fixed",
+          "credits": 5,
+          "agentId": "did:nv:agent-123",
+          "planId": "plan-456",
+          "costDescription": "5 credits per request"
+        }
+      },
+      {
+        "uri": "https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2",
+        "required": false
+      }
+    ]
+  }
+}
+```
+
+## x402 v2 In-Band Payments (Standards Flow)
+
+Payment is signalled **in band** following the [Coinbase x402 v2 A2A transport spec](https://github.com/coinbase/x402/blob/main/specs/transports-v2/a2a.md) and the official [a2a-x402 extension](https://github.com/google-agentic-commerce/a2a-x402). No HTTP 402 is involved — the whole handshake rides on A2A task/message metadata, correlated by `taskId`. This is automatic when you use `payments.a2a.start`; nothing changes in your executor.
+
+Lifecycle:
+
+1. **Payment required** — a payment-gated `message/send` arrives with no payment. The server returns a Task with `status.state = "input-required"` and `status.message.metadata`:
+
+   ```json
+   {
+     "x402.payment.status": "payment-required",
+     "x402.payment.required": { /* X402PaymentRequired (accepts[] of plans) */ }
+   }
+   ```
+
+2. **Payment submitted** — the client sends a follow-up `message/send` whose `message.metadata` carries the payload, correlated via `message.taskId`:
+
+   ```json
+   {
+     "x402.payment.status": "payment-submitted",
+     "x402.payment.payload": { /* PaymentPayload */ }
+   }
+   ```
+
+3. **Completed / failed** — on success the final Task carries `x402.payment.status: "payment-completed"` plus `x402.payment.receipts` (array of settle receipts). On failure it is `failed` / `x402.payment.status: "payment-failed"` with the error under `x402.payment.error`, and paid content is suppressed.
+
+Metadata keys: `x402.payment.status`, `x402.payment.required`, `x402.payment.payload`, `x402.payment.receipts`, `x402.payment.error`.
+
+> **Batch (deferred) settlement.** If the server settles credits in batch, a successful call returns `x402.payment.status: "payment-verified"` (not `payment-completed`) plus the Nevermined marker `x402.payment.settlement: "deferred"` — the payment was verified but settled out-of-band, so there is no in-band receipt. Spec-only clients ignore the unknown key.
+
+> ⚠️ **Header flow deprecated.** The legacy `payment-signature` HTTP header still works but is now a **deprecated fallback, kept for one release**. New integrations should rely on the in-band metadata flow above.
+
+## Implement Executor
+
+The executor contains your agent's business logic and emits events via the EventBus:
+
+```typescript
+const executor = {
+  async execute(context, eventBus) {
+    const taskId = context.task?.id
+
+    // Emit working status
+    eventBus.publish({
+      kind: 'status-update',
+      taskId,
+      status: { state: 'working' },
+      final: false,
+    })
+
+    try {
+      // Process the task
+      const userMessage = context.history?.[0]
+      const prompt = userMessage?.parts?.find(p => p.kind === 'text')?.text
+
+      const result = await processPrompt(prompt)
+
+      // Emit completion with credits used
+      eventBus.publish({
+        kind: 'status-update',
+        taskId,
+        status: {
+          state: 'completed',
+          message: {
+            role: 'agent',
+            parts: [{ kind: 'text', text: result }],
+          },
+        },
+        final: true,
+        metadata: { creditsUsed: 5 },  // Report credits consumed
+      })
+
+    } catch (error) {
+      // Emit failure
+      eventBus.publish({
+        kind: 'status-update',
+        taskId,
+        status: {
+          state: 'failed',
+          message: {
+            role: 'agent',
+            parts: [{ kind: 'text', text: `Error: ${error.message}` }],
+          },
+        },
+        final: true,
+      })
+    }
+
+    // Signal completion
+    eventBus.finished()
+  },
+
+  async cancelTask(taskId, eventBus) {
+    // Handle task cancellation
+    eventBus.publish({
+      kind: 'status-update',
+      taskId,
+      status: { state: 'canceled' },
+      final: true,
+    })
+    eventBus.finished()
+  },
+}
+```
+
+## EventBus Events
+
+The executor communicates via event publishing:
+
+### Task Event
+
+```typescript
+eventBus.publish({
+  kind: 'task',
+  id: taskId,
+  contextId: contextId,
+  status: { state: 'working' },
+  history: [userMessage],
+})
+```
+
+### Status Update Event
+
+```typescript
+eventBus.publish({
+  kind: 'status-update',
+  taskId,
+  status: {
+    state: 'completed',  // or 'working', 'failed', 'canceled'
+    message: {
+      role: 'agent',
+      parts: [{ kind: 'text', text: 'Result here' }],
+    },
+  },
+  final: true,           // Set true when task is done
+  metadata: {
+    creditsUsed: 5,      // Required for credit settlement
+  },
+})
+```
+
+### Message Event (Streaming)
+
+```typescript
+eventBus.publish({
+  kind: 'message',
+  messageId: generateId(),
+  role: 'agent',
+  parts: [{ kind: 'text', text: 'Partial result...' }],
+})
+```
+
+### Signal Completion
+
+```typescript
+eventBus.finished()  // Must call when done
+```
+
+## Start A2A Server
+
+Start the complete A2A server with payment integration:
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Build agent card
+const agentCard = Payments.a2a.buildPaymentAgentCard(
+  {
+    name: 'Weather Agent',
+    description: 'Weather forecasts and analysis',
+    version: '1.0.0',
+    protocolVersion: '0.3.0',
+    url: 'http://localhost:6000/a2a/',
+    capabilities: { streaming: true, pushNotifications: false },
+    defaultInputModes: ['text'],
+    defaultOutputModes: ['text'],
+    skills: [],
+  },
+  {
+    agentId: process.env.NVM_AGENT_ID!,
+    planId: process.env.NVM_PLAN_ID!,
+    credits: 5,
+    paymentType: 'fixed',
+  }
+)
+
+// Define executor
+const executor = {
+  async execute(context, eventBus) {
+    const taskId = context.task?.id
+
+    eventBus.publish({
+      kind: 'status-update',
+      taskId,
+      status: { state: 'working' },
+      final: false,
+    })
+
+    // Your logic here
+    const result = await processTask(context)
+
+    eventBus.publish({
+      kind: 'status-update',
+      taskId,
+      status: {
+        state: 'completed',
+        message: { role: 'agent', parts: [{ kind: 'text', text: result }] },
+      },
+      final: true,
+      metadata: { creditsUsed: 5 },
+    })
+
+    eventBus.finished()
+  },
+  async cancelTask(taskId, eventBus) {
+    // Handle cancellation
+  },
+}
+
+// Start server
+const { server, close } = await payments.a2a.start({
+  agentCard,
+  executor,
+  port: 6000,
+  basePath: '/a2a/',
+  exposeAgentCard: true,        // Expose /.well-known/agent-card.json (+ legacy /.well-known/agent.json alias)
+  exposeDefaultRoutes: true,    // Expose health and info routes
+})
+
+console.log('A2A Server running on port 6000')
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  await close()
+  console.log('Server stopped')
+  process.exit(0)
+})
+```
+
+> 🔐 **Run behind a reverse proxy with HTTPS in production.** A2A peers exchange paid tokens — in band via `x402.payment.payload`, or over the deprecated `payment-signature` header — so never expose the raw server on a public hostname without TLS. Bind the dev server to `127.0.0.1` (e.g. by running it inside a container with no published port, or behind a localhost-bound proxy).
+
+## Credit Reporting
+
+The executor reports credits used in the final status update:
+
+### Fixed Credits
+
+```typescript
+eventBus.publish({
+  kind: 'status-update',
+  taskId,
+  status: { state: 'completed', message: {...} },
+  final: true,
+  metadata: { creditsUsed: 5 },  // Always 5 credits
+})
+```
+
+### Dynamic Credits
+
+Calculate credits based on actual usage:
+
+```typescript
+async execute(context, eventBus) {
+  const taskId = context.task?.id
+
+  // Execute task
+  const result = await processTask(context)
+
+  // Calculate credits based on result
+  const creditsUsed = calculateCredits(result)
+
+  eventBus.publish({
+    kind: 'status-update',
+    taskId,
+    status: { state: 'completed', message: {...} },
+    final: true,
+    metadata: { creditsUsed },  // Variable credits
+  })
+
+  eventBus.finished()
+}
+
+function calculateCredits(result: string): number {
+  // Example: charge based on response length
+  return Math.ceil(result.length / 1000)  // 1 credit per KB
+}
+```
+
+## Streaming Example
+
+For long-running tasks, stream partial results:
+
+```typescript
+const executor = {
+  async execute(context, eventBus) {
+    const taskId = context.task?.id
+
+    eventBus.publish({
+      kind: 'status-update',
+      taskId,
+      status: { state: 'working' },
+      final: false,
+    })
+
+    // Stream partial results
+    const chunks = await processInChunks(context)
+    for (const chunk of chunks) {
+      eventBus.publish({
+        kind: 'message',
+        messageId: generateId(),
+        role: 'agent',
+        parts: [{ kind: 'text', text: chunk }],
+      })
+    }
+
+    // Final result
+    eventBus.publish({
+      kind: 'status-update',
+      taskId,
+      status: {
+        state: 'completed',
+        message: { role: 'agent', parts: [{ kind: 'text', text: 'Done!' }] },
+      },
+      final: true,
+      metadata: { creditsUsed: 5 },
+    })
+
+    eventBus.finished()
+  },
+}
+```
+
+## Complete Example: Weather A2A Agent
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Build agent card
+const agentCard = Payments.a2a.buildPaymentAgentCard(
+  {
+    name: 'Weather Forecast Agent',
+    description: 'Get weather forecasts for any location',
+    version: '1.0.0',
+    protocolVersion: '0.3.0',
+    url: 'http://localhost:6000/a2a/',
+    capabilities: {
+      streaming: true,
+      pushNotifications: false,
+    },
+    defaultInputModes: ['text'],
+    defaultOutputModes: ['text'],
+    skills: [
+      {
+        name: 'weather_forecast',
+        description: 'Get weather forecast',
+      },
+    ],
+  },
+  {
+    agentId: process.env.NVM_AGENT_ID!,
+    planId: process.env.NVM_PLAN_ID!,
+    credits: 3,
+    paymentType: 'fixed',
+    costDescription: '3 credits per forecast request',
+  }
+)
+
+// Implement executor
+const executor = {
+  async execute(context, eventBus) {
+    const taskId = context.task?.id
+
+    // Extract user message
+    const userMessage = context.history?.[0]
+    const prompt = userMessage?.parts?.find(p => p.kind === 'text')?.text
+
+    if (!prompt) {
+      eventBus.publish({
+        kind: 'status-update',
+        taskId,
+        status: {
+          state: 'failed',
+          message: {
+            role: 'agent',
+            parts: [{ kind: 'text', text: 'No prompt provided' }],
+          },
+        },
+        final: true,
+      })
+      eventBus.finished()
+      return
+    }
+
+    // Emit working status
+    eventBus.publish({
+      kind: 'status-update',
+      taskId,
+      status: { state: 'working' },
+      final: false,
+    })
+
+    try {
+      // Process weather request
+      const city = extractCity(prompt)
+      const forecast = await getWeatherForecast(city)
+
+      // Emit completion
+      eventBus.publish({
+        kind: 'status-update',
+        taskId,
+        status: {
+          state: 'completed',
+          message: {
+            role: 'agent',
+            parts: [{ kind: 'text', text: formatForecast(forecast) }],
+          },
+        },
+        final: true,
+        metadata: { creditsUsed: 3 },
+      })
+
+    } catch (error) {
+      eventBus.publish({
+        kind: 'status-update',
+        taskId,
+        status: {
+          state: 'failed',
+          message: {
+            role: 'agent',
+            parts: [{ kind: 'text', text: `Error: ${error.message}` }],
+          },
+        },
+        final: true,
+      })
+    }
+
+    eventBus.finished()
+  },
+
+  async cancelTask(taskId, eventBus) {
+    eventBus.publish({
+      kind: 'status-update',
+      taskId,
+      status: { state: 'canceled' },
+      final: true,
+    })
+    eventBus.finished()
+  },
+}
+
+// Start server
+const { server, close } = await payments.a2a.start({
+  agentCard,
+  executor,
+  port: 6000,
+  basePath: '/a2a/',
+})
+
+console.log('Weather A2A Agent running on http://localhost:6000/a2a/')
+console.log('Agent card: http://localhost:6000/a2a/.well-known/agent-card.json')
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('Shutting down...')
+  await close()
+  process.exit(0)
+})
+
+// Helper functions
+function extractCity(prompt: string): string {
+  // Simple extraction logic
+  const match = prompt.match(/weather (?:in|for) (.+)/i)
+  return match?.[1] || 'San Francisco'
+}
+
+async function getWeatherForecast(city: string) {
+  // Mock weather API call
+  return {
+    city,
+    temperature: 72,
+    condition: 'Sunny',
+    forecast: ['Mon: 70°F', 'Tue: 68°F', 'Wed: 73°F'],
+  }
+}
+
+function formatForecast(forecast: any): string {
+  return `Weather in ${forecast.city}:
+Current: ${forecast.temperature}°F, ${forecast.condition}
+Forecast: ${forecast.forecast.join(', ')}`
+}
+```
+
+## Server Configuration Options
+
+```typescript
+const { server, close } = await payments.a2a.start({
+  agentCard,                      // Payment agent card (required)
+  executor,                       // Task executor (required)
+  port: 6000,                     // Server port (required)
+  basePath: '/a2a/',              // Base path (optional, default: '/')
+  exposeAgentCard: true,          // Expose /.well-known/agent-card.json + legacy alias (optional)
+  exposeDefaultRoutes: true,      // Expose /health, /info (optional)
+  paymentsService: payments,      // Custom payments instance (optional)
+  handlerOptions: {
+    asyncExecution: false,        // Async task execution (optional)
+    defaultBatch: false,          // Batch credit settlement (optional)
+    defaultMarginPercent: 5,      // Add 5% margin to credits (optional)
+  },
+})
+```
+
+## Best Practices
+
+1. **Always Report Credits**: Include `creditsUsed` in final status updates
+2. **Handle Errors**: Emit 'failed' status on errors
+3. **Signal Completion**: Always call `eventBus.finished()`
+4. **Streaming for Long Tasks**: Use message events for real-time updates
+5. **Graceful Shutdown**: Implement proper server cleanup
+6. **Descriptive Agent Cards**: Provide clear descriptions and skills
+7. **Version Control**: Include version in agent card metadata
+
+## Related Documentation
+
+- [Agents](./agents) - Register your A2A agent in Nevermined
+- [Payment Plans](./payment-plans) - Configure pricing for your agent
+- [Validation of Requests](./validation-of-requests) - Understanding credit settlement
+
+---
+
+**Source References**:
+- `RUN.md` (A2A Server section, lines 88-156)
+- `src/a2a/server.ts` (PaymentsA2AServer)
+- `src/a2a/agent-card.ts` (buildPaymentAgentCard)
+- `tests/integration/a2a/complete-message-send-flow.test.ts` (executor patterns)
+- `tests/e2e/helpers/a2a-setup-helpers.ts` (setup examples)
diff --git a/docs/api-reference/typescript/agents.md b/docs/api-reference/typescript/agents.md
new file mode 100644
index 00000000..f0d8ba18
--- /dev/null
+++ b/docs/api-reference/typescript/agents.md
@@ -0,0 +1,388 @@
+---
+title: "Agents"
+description: "Register and manage AI agents with payment plans, metadata, and API endpoints"
+icon: "robot"
+---
+
+# Agents
+
+The Agents API allows AI builders to register their AI agents with the Nevermined protocol, making them discoverable and accessible through payment plans.
+
+## Overview of Agents API
+
+The Agents API (`payments.agents`) enables you to:
+- Register AI agents with metadata and API endpoints
+- Associate agents with one or more payment plans
+- Register agents and plans together in a single operation
+- Update agent metadata and configuration
+- Retrieve agent information
+- Manage plan associations (add/remove plans from agents)
+
+## Agent Metadata Structure
+
+Agents require metadata for discovery and identification:
+
+```typescript
+import { AgentMetadata } from '@nevermined-io/payments'
+
+const agentMetadata: AgentMetadata = {
+  name: 'Weather AI Agent',
+  description: 'Provides real-time weather forecasts and climate data',
+  tags: ['weather', 'forecast', 'climate'],
+  dateCreated: new Date(),
+  author: 'Your Company Name',
+  // Additional metadata fields...
+}
+```
+
+## Agent API Configuration
+
+`AgentAPIAttributes` describes how requests to your agent are authenticated and (optionally) which routes are gated by your Payment Plan. **All fields are optional.**
+
+### Minimal (recommended)
+
+Most builders only need to configure how the agent is authenticated. If you integrate with the Payments library and gate paid routes via library annotations or middleware, you do **not** need to declare endpoints or an OpenAPI URL at registration time.
+
+```typescript
+import { AgentAPIAttributes } from '@nevermined-io/payments'
+
+const agentApi: AgentAPIAttributes = {
+  authType: 'bearer',
+  token: process.env.AGENT_BEARER_TOKEN,
+}
+```
+
+### With Additional Security (opt-in)
+
+If you want the Nevermined platform to enforce a route-level allowlist (defense-in-depth on top of your library-level gating), provide `endpoints`. You can also provide `agentDefinitionUrl` to publish a discoverable OpenAPI / MCP / A2A descriptor.
+
+```typescript
+const agentApi: AgentAPIAttributes = {
+  authType: 'bearer',
+  token: process.env.AGENT_BEARER_TOKEN,
+
+  // Additional Security: only requests matching this allowlist are accepted by
+  // the Nevermined platform's x402 verification service. Omitted = allow-all (default).
+  endpoints: [
+    { POST: 'https://api.example.com/v1/agents/:agentId/tasks' },
+    { GET: 'https://api.example.com/v1/agents/:agentId/tasks/:taskId' },
+  ],
+  openEndpoints: ['https://api.example.com/v1/health'],
+
+  // Optional: discoverable agent definition (OpenAPI / MCP Manifest / A2A card).
+  agentDefinitionUrl: 'https://api.example.com/openapi.json',
+}
+```
+
+> **Migration note:** agents registered before endpoint and agent definition fields became optional may still have these fields populated and will continue to enforce the allowlist as before. Nothing changes for them. Use the Edit Agent screen on app.nevermined.app to add or remove the configuration.
+
+### Endpoint Patterns (Additional Security)
+
+When you opt in to the allowlist, you can use path parameters in your endpoint definitions:
+
+```typescript
+const agentApi: AgentAPIAttributes = {
+  endpoints: [
+    { POST: 'https://api.example.com/agents/:agentId/query' },
+    { GET: 'https://api.example.com/agents/:agentId/status' },
+    { POST: 'https://api.example.com/agents/:agentId/tasks/:taskId/cancel' },
+  ],
+}
+```
+
+## Register Agents
+
+### Register Agent with Existing Plans
+
+If you've already registered payment plans, you can register an agent and associate it with those plans:
+
+```typescript
+import { Payments, AgentMetadata, AgentAPIAttributes } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox',
+})
+
+// Define agent metadata
+const agentMetadata: AgentMetadata = {
+  name: 'Weather Forecast Agent',
+  description: 'Get accurate weather forecasts for any location',
+  tags: ['weather', 'forecast', 'api'],
+}
+
+// Configure API authentication. endpoints + agentDefinitionUrl are
+// optional — see "Additional Security (opt-in)" above.
+const agentApi: AgentAPIAttributes = {
+  authType: 'bearer',
+  token: process.env.AGENT_BEARER_TOKEN,
+}
+
+// Register agent with existing plans
+const { agentId } = await payments.agents.registerAgent(
+  agentMetadata,
+  agentApi,
+  [planId1, planId2]  // Array of plan IDs
+)
+
+console.log(`Agent registered with ID: ${agentId}`)
+```
+
+### Register Agent and Plan Together
+
+For convenience, you can register both an agent and its payment plan in a single operation:
+
+```typescript
+import { Payments, AgentMetadata, AgentAPIAttributes, PlanMetadata } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox',
+})
+
+const builderAddress = payments.getAccountAddress()
+const ERC20_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
+
+// Define plan
+const planMetadata: PlanMetadata = {
+  name: 'Weather Agent Access Plan',
+  description: 'Get 1000 credits to access weather data',
+}
+
+const priceConfig = payments.plans.getCryptoPriceConfig(
+  10_000_000n,
+  builderAddress,
+  ERC20_ADDRESS
+)
+
+const creditsConfig = payments.plans.getFixedCreditsConfig(1000n, 1n)
+
+// Define agent
+const agentMetadata: AgentMetadata = {
+  name: 'Weather Forecast Agent',
+  description: 'Real-time weather forecasts powered by AI',
+  tags: ['weather', 'ai', 'forecast'],
+}
+
+const agentApi: AgentAPIAttributes = {
+  authType: 'bearer',
+  token: process.env.AGENT_BEARER_TOKEN,
+  // Optional: opt in to platform-enforced route allowlist. See
+  // "Additional Security (opt-in)" above.
+  // endpoints: [
+  //   { POST: 'https://weather-api.example.com/v1/agents/:agentId/tasks' },
+  // ],
+}
+
+// Register both together
+const { agentId, planId } = await payments.agents.registerAgentAndPlan(
+  agentMetadata,
+  agentApi,
+  planMetadata,
+  priceConfig,
+  creditsConfig
+)
+
+console.log(`Agent ID: ${agentId}`)
+console.log(`Plan ID: ${planId}`)
+```
+
+## Retrieve Agents
+
+### List Your Agents
+
+List the agents **you** published — the authenticated caller's own agents. This
+is account management, not a marketplace search: it never returns other users'
+agents. Pass an `orgId` to list every agent in an organization you belong to.
+
+```typescript
+// Your own agents (paginated: { total, page, offset, agents })
+const { agents } = await payments.agents.getAgents()
+
+agents.forEach((agent) => {
+  console.log(`${agent.name}: ${agent.agentId}`)
+})
+
+// Every agent in an organization you belong to
+const { agents: orgAgents } = await payments.agents.getAgents(1, 100, 'created', 'desc', 'org-acme')
+```
+
+### Get a Specific Agent
+
+```typescript
+// Get agent details by ID
+const agent = await payments.agents.getAgent(agentId)
+
+console.log(`Name: ${agent.name}`)
+console.log(`Description: ${agent.description}`)
+console.log(`Endpoints: ${JSON.stringify(agent.endpoints)}`)
+```
+
+### Get Plans for an Agent
+
+```typescript
+// Get all payment plans associated with an agent
+const plans = await payments.agents.getAgentPlans(agentId)
+
+plans.forEach(plan => {
+  console.log(`Plan: ${plan.name} (${plan.planId})`)
+})
+```
+
+## Update Agent Metadata
+
+You can update agent metadata and API configuration after registration. This is also where builders typically **opt in to Additional Security** by adding an `endpoints` allowlist or an `agentDefinitionUrl` to an existing agent:
+
+```typescript
+// Update agent information and opt in to the route-level allowlist.
+await payments.agents.updateAgentMetadata(
+  agentId,
+  {
+    description: 'Updated description with new features',
+    tags: ['weather', 'forecast', 'climate', 'ai-powered'],
+  },
+  {
+    // Adding `endpoints` activates the platform-enforced allowlist.
+    // Do not use `endpoints: []` to mean "allow all": a configured-but-empty
+    // allowlist is treated as deny-all unless `openEndpoints` matches,
+    // preserving legacy semantics. Only include `endpoints` when you want
+    // the allowlist to be enforced.
+    endpoints: [
+      { POST: 'https://weather-api.example.com/v2/agents/:agentId/forecast' },
+      { GET: 'https://weather-api.example.com/v2/agents/:agentId/history' },
+      { GET: 'https://weather-api.example.com/v2/agents/:agentId/alerts' },
+    ],
+    agentDefinitionUrl: 'https://weather-api.example.com/openapi.json',
+  }
+)
+
+console.log('Agent updated successfully')
+```
+
+## Manage Agent Plans
+
+### Add Plans to an Agent
+
+Associate additional payment plans with an existing agent:
+
+```typescript
+// Add new plans to an agent
+await payments.agents.addPlanToAgent(newPlanId, agentId)
+
+console.log(`Added plan ${newPlanId} to agent ${agentId}`)
+```
+
+### Remove Plans from an Agent
+
+Remove payment plan associations:
+
+```typescript
+// Remove a plan from an agent
+await payments.agents.removePlanFromAgent(planIdToRemove, agentId)
+
+console.log(`Removed plan ${planIdToRemove} from agent ${agentId}`)
+```
+
+## Authentication Types
+
+The Agents API supports multiple authentication types:
+
+```typescript
+// No authentication required
+const agentApi = {
+  endpoints: [{ GET: 'https://api.example.com/public' }],
+  authType: 'none',
+}
+
+// Basic authentication
+const agentApi = {
+  endpoints: [{ POST: 'https://api.example.com/agent' }],
+  authType: 'basic',
+}
+
+// Bearer token (most common for AI agents)
+const agentApi = {
+  endpoints: [{ POST: 'https://api.example.com/agent' }],
+  authType: 'bearer',  // X402 access token in Authorization header
+}
+
+// OAuth
+const agentApi = {
+  endpoints: [{ POST: 'https://api.example.com/agent' }],
+  authType: 'oauth',
+}
+```
+
+## Complete Example: Multi-Endpoint Agent
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+import { AgentMetadata, AgentAPIAttributes } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Comprehensive agent configuration
+const agentMetadata: AgentMetadata = {
+  name: 'Advanced Weather AI',
+  description: 'Multi-modal weather analysis with forecasts, alerts, and historical data',
+  tags: ['weather', 'forecast', 'climate', 'alerts', 'ai'],
+  author: 'Weather Tech Inc.',
+  dateCreated: new Date(),
+}
+
+const agentApi: AgentAPIAttributes = {
+  endpoints: [
+    { POST: 'https://api.weather-tech.com/v1/agents/:agentId/forecast' },
+    { GET: 'https://api.weather-tech.com/v1/agents/:agentId/forecast/:forecastId' },
+    { POST: 'https://api.weather-tech.com/v1/agents/:agentId/alerts' },
+    { GET: 'https://api.weather-tech.com/v1/agents/:agentId/history' },
+    { DELETE: 'https://api.weather-tech.com/v1/agents/:agentId/alerts/:alertId' },
+  ],
+  openEndpoints: [
+    'https://api.weather-tech.com/v1/health',
+    'https://api.weather-tech.com/v1/status',
+  ],
+  authType: 'bearer',
+  agentDefinitionUrl: 'https://api.weather-tech.com/openapi.json',
+}
+
+// Register with multiple plans
+const { agentId } = await payments.agents.registerAgent(
+  agentMetadata,
+  agentApi,
+  [basicPlanId, proPlanId, enterprisePlanId]
+)
+
+console.log(`Advanced agent registered: ${agentId}`)
+
+// Retrieve and verify
+const agent = await payments.agents.getAgent(agentId)
+const { plans, total, page, offset } = await payments.agents.getAgentPlans(agentId)
+
+console.log(`Agent has ${plans.length} plans on page ${page} (offset ${offset}, total ${total})`)
+```
+
+## Best Practices
+
+1. **Descriptive Metadata**: Use clear names and descriptions for better discoverability
+2. **Relevant Tags**: Add tags that help users find your agent
+3. **RESTful Endpoints**: Follow REST conventions for endpoint paths
+4. **OpenAPI Specs**: Provide agent definition URLs for better integration
+5. **Multiple Plans**: Offer different pricing tiers for various use cases
+6. **Bearer Auth**: Use bearer token authentication for secure access
+
+## Related Documentation
+
+- [Payment Plans](./payment-plans) - Create plans to associate with agents
+- [Publishing Static Resources](./publishing-static-resources) - Register static content agents
+- [Validation of Requests](./validation-of-requests) - Validate incoming agent requests
+
+---
+
+**Source References**:
+- `src/api/agents-api.ts` (Agents API methods)
+- `tests/e2e/test_payments_e2e.test.ts` (lines 373-449)
+- `tests/e2e/test_x402_e2e.test.ts` (agent registration examples)
diff --git a/docs/api-reference/typescript/cli-card-setup.md b/docs/api-reference/typescript/cli-card-setup.md
new file mode 100644
index 00000000..8eca98a8
--- /dev/null
+++ b/docs/api-reference/typescript/cli-card-setup.md
@@ -0,0 +1,303 @@
+---
+title: "CLI Card Setup (Top-Level Redirect Flow)"
+description: "Hand a user off to the Nevermined webapp to enrol a card and create a spending delegation from a CLI or other top-level browser-tab integration"
+icon: "browser"
+---
+
+# CLI Card Setup (Top-Level Redirect Flow)
+
+Nevermined ships a standalone embed app (served at `embed.<tier>` — e.g. `embed.nevermined.app`) with a chromeless **card setup** page at `/cards/setup` that walks a user through:
+
+1. Enrolling a credit / debit card (via Stripe Elements — sensitive data never touches your servers).
+2. Creating a spending delegation against that card (a per-card budget the user pre-authorises for agent spend).
+
+This guide explains how a **CLI or any other non-iframe integrator** can drive that page in a top-level browser tab and receive `paymentMethodId` + `delegationId` back at a localhost HTTP callback. The pattern mirrors `nevermined login`: print a URL, the user clicks it, the browser redirects back to a one-shot port on the user's machine, your process resolves with the result.
+
+The official `nevermined` CLI ships three commands implementing this flow out of the box — see [`nevermined cards setup`](#using-the-nevermined-cli) below. If you are building your own CLI or backend integration, the rest of this guide is the contract you need to honour.
+
+## When to Use This Flow
+
+- You are building a CLI, terminal tool, or other application that runs on the user's machine and wants to attach a card to the user's Nevermined account without forcing them into your own UI for the tokenization step.
+- You want a **white-labeled** card setup page that respects the parent organisation's branding (logo, panel colours, button colours), but you do not want to host an iframe.
+- You need both the `paymentMethodId` and the `delegationId` in one round-trip — the combined `setup` flow emits both in a single callback.
+
+For the classic iframe integration (a website embedding `/cards/enroll` etc. inside an `<iframe>` and listening for `postMessage`), see the `@nevermined-io/ui-widgets` package instead.
+
+## Two Authentication Paths
+
+| Path | Who uses it | Authentication |
+|------|-------------|---------------|
+| **Widget-key** | A third-party (website backend, CLI) acting on behalf of an organisation's own end-users. The end-users do not necessarily have their own Nevermined accounts. | Server signs an init-token with the organisation's widget-key secret and exchanges it at `POST /widgets/session` for a session token. |
+| **Self-mint** | A user with their own NVM API key (typically after running `nevermined login`) who wants to attach a card to their *own* Nevermined identity. | `POST /widgets/session/self` with `Authorization: Bearer <nvmApiKey>`. |
+
+Both paths produce the same response shape (`WidgetSessionResponse`); the embed routes don't branch on which one was used.
+
+Card setup is **organization-scoped**. Self-mint callers must be members of at least one Nevermined organisation. Widget-key sessions are inherently org-scoped through the widget key itself.
+
+## Basic Flow
+
+```text
+┌──────┐                            ┌────────────┐                             ┌─────────────┐                     ┌────────────────┐
+│ CLI  │                            │ Backend    │                             │ User Browser│                     │ Local Callback │
+│      │                            │ (Nevermined│                             │             │                     │  HTTP Server   │
+└──┬───┘                            └─────┬──────┘                             └──────┬──────┘                     └────────┬───────┘
+   │                                      │                                           │                                     │
+   │ start one-shot server on             │                                           │                                     │
+   │ 127.0.0.1:<random> /callback ───────────────────────────────────────────────────────────────────────────────────────────▶ listening
+   │                                      │                                           │                                     │
+   │ POST /widgets/session/self           │                                           │                                     │
+   │   Bearer <nvmApiKey>                 │                                           │                                     │
+   │   body { orgId, returnUrl }          │                                           │                                     │
+   ├────────────────────────────────────▶│ verify org membership                     │                                     │
+   │                                      │ mint session JWT (kind:'self-mint')       │                                     │
+   │◀────────────────────────────────────┤ { sessionToken, isReturnUrlAllowed }      │                                     │
+   │                                      │                                           │                                     │
+   │ open browser at                      │                                           │                                     │
+   │ {embed}/cards/setup                  │                                           │                                     │
+   │  ?sessionToken=...                   │                                           │                                     │
+   │  &returnUrl=http://127.0.0.1:<port>  │                                           │                                     │
+   │  &state=<rand>  &network=<net>       │                                           │                                     │
+   │  &provider=stripe                    │                                           │                                     │
+   ├──────────────────────────────────────────────────────────────────────────────────▶ navigate                            │
+   │                                      │                                           │                                     │
+   │                                      │ GET /widgets/session/validate            │                                     │
+   │                                      │  Bearer <sessionToken>                   │                                     │
+   │                                      │  X-Nvm-Widget-Return-Url: <returnUrl>    │                                     │
+   │                                      │◀──────────────────────────────────────────│                                     │
+   │                                      │ { valid, isReturnUrlAllowed, ... }       │                                     │
+   │                                      │──────────────────────────────────────────▶│                                     │
+   │                                      │                                           │                                     │
+   │                                      │ Step 1: Enroll card                      │                                     │
+   │                                      │   Stripe Elements + SetupIntent          │                                     │
+   │                                      │   POST /delegation/setup-intent          │                                     │
+   │                                      │   POST /delegation/finalize-enrollment   │                                     │
+   │                                      │   → paymentMethodId                      │                                     │
+   │                                      │                                           │                                     │
+   │                                      │ Step 2: Create delegation                │                                     │
+   │                                      │   POST /delegation/create                │                                     │
+   │                                      │   → delegationId                         │                                     │
+   │                                      │                                           │                                     │
+   │                                      │ window.location.replace(returnUrl + ?    │                                     │
+   │                                      │   paymentMethodId&delegationId&state)    │                                     │
+   │                                      │──────────────────────────────────────────▶ GET callback                         │
+   │                                      │                                           │                                     │
+   │◀──────────────────────────────────────────────────────────────────────────────────────────────────resolved { ids, state }
+   │                                      │                                           │                                     │
+   │ verify state matches → resolve        │                                           │                                     │
+   │ shutdown server                       │                                           │                                     │
+```
+
+The browser ends up on a friendly "All done — close this tab" page so the user knows the flow finished; your CLI prints the IDs and exits.
+
+## Using the `nevermined` CLI
+
+Three commands are available out of the box:
+
+```bash
+# Combined: enroll a card AND create a delegation in one flow.
+# Returns both paymentMethodId and delegationId.
+nevermined cards setup
+
+# Single-purpose: only enroll a card. Returns paymentMethodId.
+nevermined cards enroll
+
+# Single-purpose: only create a delegation against an already-enrolled card.
+# Returns delegationId.
+nevermined cards delegate --card pm_1234
+```
+
+All three accept:
+- `--org <id>` — Required if you belong to multiple organisations and the terminal is non-interactive (CI). Inferred silently when you belong to exactly one org. In an interactive terminal with two or more memberships, the CLI prompts you to pick.
+- `--no-browser` — Print the URL instead of opening the browser automatically (useful over SSH or in CI).
+- `--provider stripe|braintree|visa` — Tokenization provider for the enrolment step. Defaults to `stripe`.
+
+Pre-requisite: run `nevermined login` first to authenticate against the target environment.
+
+```bash
+$ nevermined cards setup
+ℹ Using organization: Acme AI (org-abc-123)
+Opening browser...
+Waiting for completion...
+✓ Card setup complete!
+  paymentMethodId: pm_1ABCD…
+  delegationId:    9719d8b5-…
+  organization:    org-abc-123
+```
+
+## Implementing the Flow Yourself
+
+If you are building your own CLI (in a non-Node language, or with stricter packaging requirements), implement the four steps below. The pattern works in any language with an HTTP client, a way to open a browser, and the ability to bind a local TCP port.
+
+### 1. Start a one-shot localhost HTTP server
+
+Bind to `127.0.0.1:0` (the OS picks a free port). Listen on `/callback`. Note the port — you need it for `returnUrl`.
+
+Bind to `127.0.0.1` only, **never `0.0.0.0`** — your callback should not be reachable from the network.
+
+### 2. Mint a session token
+
+For the **self-mint** path (a user with their own `nvmApiKey`):
+
+```http
+POST {api}/api/v1/widgets/session/self
+Authorization: Bearer <nvmApiKey>
+Content-Type: application/json
+
+{
+  "orgId": "org-abc-123",
+  "returnUrl": "http://127.0.0.1:54321/callback"
+}
+```
+
+Response:
+
+```json
+{
+  "sessionToken": "eyJ...",
+  "userId": "us-...",
+  "userWallet": "0x...",
+  "apiKeyHash": "sandbox:eyJ...",
+  "expiresAt": "2026-05-22T19:00:00.000Z",
+  "isReturnUrlAllowed": true
+}
+```
+
+If the user is not a member of the requested org you get `403 BCK.WIDGET_SESSION.0019`. If they have no org memberships at all, `403 BCK.WIDGET_SESSION.0018`.
+
+For the **widget-key** path, see the existing `POST /widgets/session` documentation in the `@nevermined-io/ui-widgets-server` SDK.
+
+### 3. Open the browser
+
+Construct the URL and open it (`xdg-open` / `open` / `start`):
+
+```
+{embed}/cards/setup?sessionToken=<token>&returnUrl=<urlEncoded callback>&state=<random>&network=<sandbox|live>&provider=stripe
+```
+
+`{embed}` is the standalone embed app origin for your environment (`https://embed.nevermined.app` for live/sandbox, `https://embed.nevermined.dev` for staging) — formed by prepending `embed.` to the webapp host.
+
+Required query parameters:
+- `sessionToken` — from step 2.
+- `returnUrl` — your localhost callback URL.
+- `state` — a cryptographically random nonce (16+ bytes, hex-encoded). The browser echoes it back in the redirect; you reject any callback that doesn't echo this value (CSRF binding).
+- `network` — `sandbox` or `live`, matching the environment you minted the session against. **The embed app reads its active backend solely from this param and defaults to `sandbox` when it is absent** — omitting it on a `live` session makes the embed validate the token against the sandbox backend, where it doesn't exist, and the flow fails. Always set it explicitly.
+- `provider` — `stripe`, `braintree`, or `visa`.
+
+Three other routes exist if you only need one step of the flow:
+
+| Route | Result fields in the callback |
+|-------|--------------------------------|
+| `/cards/setup` | `paymentMethodId`, `delegationId` |
+| `/cards/enroll` | `paymentMethodId` |
+| `/cards/delegate?paymentMethodId=<id>` | `delegationId` |
+
+### 4. Wait for the callback
+
+The browser redirects to `<returnUrl>?paymentMethodId=…&delegationId=…&state=<echo>` on success. Your local server should:
+
+1. Verify the `state` query parameter matches the one you issued. Use a constant-time string comparison (the `nevermined` CLI uses `crypto.timingSafeEqual`).
+2. Extract `paymentMethodId` and `delegationId` (or just one, depending on which embed route you opened).
+3. Respond `200 OK` with a friendly "you can close this tab" HTML page.
+4. Close the server.
+
+Recommended timeout: **5 minutes**. Match the `nevermined login` flow so users have time to switch contexts in their browser.
+
+### Pseudocode
+
+```ts
+// TypeScript / Node — the same shape works in any language.
+import { createServer } from 'http'
+import { randomBytes, timingSafeEqual } from 'crypto'
+
+const orgId = process.env.NVM_ORG_ID!
+const nvmApiKey = process.env.NVM_API_KEY!
+const state = randomBytes(16).toString('hex')
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url!, 'http://localhost')
+  if (url.pathname !== '/callback') {
+    res.writeHead(404).end()
+    return
+  }
+  const received = url.searchParams.get('state') ?? ''
+  // Validate hex shape FIRST so we never feed UTF-8 buffers of unequal
+  // byte length into timingSafeEqual (it throws on length mismatch).
+  // Both sides are 32-char hex (16 random bytes) by construction.
+  const HEX_32 = /^[0-9a-f]{32}$/i
+  if (
+    !HEX_32.test(received) ||
+    !timingSafeEqual(Buffer.from(received, 'hex'), Buffer.from(state, 'hex'))
+  ) {
+    res.writeHead(400, { 'Content-Type': 'text/html' }).end(
+      '<h2>State mismatch</h2><p>Close this tab and re-run the command.</p>',
+    )
+    return
+  }
+  const paymentMethodId = url.searchParams.get('paymentMethodId')
+  const delegationId = url.searchParams.get('delegationId')
+  res.writeHead(200, { 'Content-Type': 'text/html' }).end(
+    '<h2>Card setup complete</h2><p>You can close this tab.</p>',
+  )
+  console.log({ paymentMethodId, delegationId })
+  server.close()
+})
+
+server.listen(0, '127.0.0.1', async () => {
+  const port = (server.address() as { port: number }).port
+  // Use 127.0.0.1 (not the `localhost` alias) to match the server bind
+  // above. Node 17+ prefers ::1 for `localhost` on IPv6-capable hosts
+  // and the browser would stall on the IPv6 attempt before falling back.
+  const returnUrl = `http://127.0.0.1:${port}/callback`
+
+  // Mint a session token bound to one of the user's orgs.
+  const mint = await fetch('https://api.sandbox.nevermined.app/api/v1/widgets/session/self', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${nvmApiKey}` },
+    body: JSON.stringify({ orgId, returnUrl }),
+  }).then((r) => r.json())
+
+  const setupUrl = new URL('/cards/setup', 'https://embed.nevermined.app')
+  setupUrl.searchParams.set('sessionToken', mint.sessionToken)
+  setupUrl.searchParams.set('returnUrl', returnUrl)
+  setupUrl.searchParams.set('state', state)
+  // Match the network you minted the session against (sandbox here). The
+  // embed app defaults to 'sandbox' if this is omitted, so a 'live'
+  // session would otherwise be validated against the sandbox backend and
+  // fail. Always set it explicitly.
+  setupUrl.searchParams.set('network', 'sandbox')
+  setupUrl.searchParams.set('provider', 'stripe')
+
+  console.log('Open this URL in your browser:\n')
+  console.log(setupUrl.toString())
+})
+```
+
+## Allowed `returnUrl` Hosts
+
+The server validates `returnUrl` against the session's allow-list. The same allow-list runs at **session-creation time** (response field `isReturnUrlAllowed`) and again at **page-load time** (via the `X-Nvm-Widget-Return-Url` header the embed page forwards on `/validate`). The page refuses to mount if the URL is not allowed, so a stale or wrong `returnUrl` can never leak the result IDs to an unauthorised destination.
+
+Rules:
+- `localhost`, `127.0.0.1`, `[::1]` (any port, any path) — accepted for **both** session kinds.
+- Other `https://` origins — accepted only for **widget-key** sessions whose key has the origin in its `allowedOrigins` list. **Self-mint sessions reject any non-localhost host** (there is no widget-key allow-list to widen).
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| `BCK.WIDGET_SESSION.0018` | Caller has no active organisation memberships. Self-mint is members-only — create or join an organisation in the dashboard first. |
+| `BCK.WIDGET_SESSION.0019` | The `orgId` in the request is not one of the caller's memberships. |
+| `BCK.WIDGET_SESSION.0001` | Invalid widget credentials (widget-key path only). |
+| `BCK.APIKEY.0004` | Invalid or expired NVM API key (self-mint path only). |
+
+## Security Notes
+
+- **Bind only to `127.0.0.1`**, not `0.0.0.0`. Your callback server is for the local user, not the network.
+- **Use a per-flow random `state` value** (16+ bytes, hex-encoded). Compare callbacks in constant time. Reject any callback whose `state` does not match.
+- **Treat the session token like a bearer credential.** It carries the user's `apiKeyHash` and expires in 2 hours. Don't log it, don't persist it past the flow.
+- **Page lifecycle is single-use.** The embed page strips `sessionToken` from the URL immediately after the page consumes it, so it never lands in the browser back-forward history or in any later `document.referrer`. If the user hits "back" after the redirect, they will not land on a re-playable URL.
+
+## See Also
+
+- [`nevermined login`](./installation.md) — the equivalent flow for authentication.
+- [Payment Plans](./payment-plans.md) — once a card is delegated, you can use it to subscribe to plans.
+- [Initialising the Library](./initializing-the-library.md) — bootstrap the SDK.
diff --git a/docs/api-reference/typescript/initializing-the-library.md b/docs/api-reference/typescript/initializing-the-library.md
new file mode 100644
index 00000000..d00ef457
--- /dev/null
+++ b/docs/api-reference/typescript/initializing-the-library.md
@@ -0,0 +1,220 @@
+---
+title: "Getting Started"
+description: "Initialize the Payments SDK in Node.js and browser environments with your API key"
+icon: "rocket"
+---
+
+# Initializing the Library
+
+This guide shows how to initialize the Nevermined Payments Library in your application. The library supports both server-side (Node.js) and browser environments with different initialization methods.
+
+## Get Your NVM API Key
+
+Before initializing the library, you need a Nevermined API key:
+
+1. Visit [nevermined.app](https://nevermined.app)
+2. Sign in or create a free account
+3. Navigate to your profile settings
+4. Generate an API key
+
+**Important**: There are two types of API keys:
+- **Builder Key**: For AI builders who register agents and payment plans
+- **Subscriber Key**: For users who purchase access and query agents
+
+Most applications will use a builder key for server-side operations.
+
+## Server-Side Initialization
+
+For Node.js applications, use the `getInstance` method:
+
+```typescript
+import { Payments } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+})
+```
+
+The environment is derived automatically from your API key — see [Environment derivation](#environment-derivation) below.
+
+### Configuration Options
+
+The `getInstance` method accepts a `PaymentOptions` object:
+
+```typescript
+interface PaymentOptions {
+  nvmApiKey: string           // Your Nevermined API key (required)
+  environment?: EnvironmentName  // @deprecated — derived from the API key (optional)
+  returnUrl?: string          // OAuth callback URL (optional, for browser)
+  appId?: string              // Your application ID (optional)
+  version?: string            // Backend API version pin, MAJOR.MINOR (optional)
+}
+```
+
+### Environment derivation
+
+NVM API keys are prefixed with the environment they belong to
+(`<prefix>:<jwt>`), so the SDK resolves the target environment from the key —
+you no longer need to pass `environment`.
+
+The `environment` option is **deprecated** but still accepted:
+
+- When the key prefix maps to a known environment, the **key always wins** and
+  the `environment` option is ignored (a one-time deprecation warning is logged).
+- When the key has no recognized prefix (for example a local/custom build), the
+  SDK falls back to the `environment` option, and finally to `custom`. This
+  keeps local and custom-backend workflows working unchanged.
+
+### Complete Server-Side Example
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+// Initialize with environment variables
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: process.env.NVM_ENVIRONMENT as EnvironmentName,
+})
+
+// Verify connection
+const accountAddress = payments.getAccountAddress()
+console.log(`Connected as: ${accountAddress}`)
+```
+
+## Browser Initialization
+
+For browser-based applications, use the `getBrowserInstance` method:
+
+```typescript
+import { Payments } from '@nevermined-io/payments'
+
+const payments = Payments.getBrowserInstance({
+  returnUrl: 'https://myapp.example/callback',
+  environment: 'sandbox',
+  appId: 'my-app',
+  // Optional: pin the backend API version (MAJOR.MINOR). Defaults to the
+  // version this SDK release targets — omit unless you must pin an older one.
+  version: '1.1',
+})
+```
+
+### Browser Authentication Flow
+
+The browser instance supports OAuth-style authentication:
+
+```typescript
+// Check if user is logged in
+if (!payments.isLoggedIn) {
+  // Redirect to Nevermined login
+  payments.connect()
+}
+
+// After login, use the payments instance
+const balance = await payments.plans.getPlanBalance(planId)
+
+// Logout when needed
+payments.logout()
+```
+
+## Environments
+
+The Nevermined protocol supports multiple environments:
+
+### Production Environments
+
+| Environment | Description | Usage |
+|-------------|-------------|-------|
+| `sandbox` | Production testing environment | Development and testing with real blockchain |
+| `live` | Production environment | Live agents and real payments |
+
+### Choosing an Environment
+
+```typescript
+// Development and testing
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox',
+})
+
+// Production deployment
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'live',
+})
+```
+
+**Important**: Agents and plans registered in one environment cannot be accessed from another. Always use the same environment throughout your application.
+
+## Environment Configuration Details
+
+Each environment has specific API endpoints:
+
+```typescript
+// Example environment structure
+interface EnvironmentInfo {
+  frontend: string   // Nevermined App URL
+  backend: string    // API URL
+  proxy: string      // Proxy service URL
+  heliconeUrl: string // Observability service URL
+}
+```
+
+The library automatically configures these endpoints based on your chosen environment.
+
+## Verify Connection
+
+After initialization, verify the connection is working:
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Get account address from API key
+const accountAddress = payments.getAccountAddress()
+console.log(`Initialized for account: ${accountAddress}`)
+
+// For browser instances
+if (payments.isLoggedIn) {
+  console.log('User authenticated successfully')
+}
+```
+
+## Best Practices
+
+1. **Environment Variables**: Always store API keys in environment variables, never hardcode them
+2. **Singleton Pattern**: Create one Payments instance per application
+3. **Environment Consistency**: Use the same environment for all operations in a session
+4. **Error Handling**: Wrap initialization in try-catch blocks for production apps
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+let payments: Payments
+
+try {
+  payments = Payments.getInstance({
+    nvmApiKey: process.env.NVM_API_KEY!,
+    environment: process.env.NVM_ENVIRONMENT as EnvironmentName,
+  })
+  console.log('✓ Nevermined Payments initialized')
+} catch (error) {
+  console.error('Failed to initialize Payments:', error)
+  process.exit(1)
+}
+```
+
+## Related Documentation
+
+- [Payment Plans](./payment-plans)
+- [Agents](./agents)
+
+---
+
+**Source References**:
+- `src/payments.ts` (getInstance, getBrowserInstance methods)
+- `src/environments.ts` (environment configurations)
+- `tests/e2e/fixtures.ts` (createPaymentsBuilder, createPaymentsSubscriber)
diff --git a/docs/api-reference/typescript/installation.md b/docs/api-reference/typescript/installation.md
new file mode 100644
index 00000000..5b33738f
--- /dev/null
+++ b/docs/api-reference/typescript/installation.md
@@ -0,0 +1,87 @@
+---
+title: "Installation"
+description: "Install and configure the @nevermined-io/payments TypeScript SDK for monetizing AI agents"
+icon: "download"
+---
+
+# Installation
+
+The Nevermined Payments Library is a TypeScript SDK that enables AI builders and subscribers to monetize and access AI agents through the Nevermined protocol. The library supports flexible payment plans (credits and time-based), multiple payment methods (crypto and fiat), and seamless integration with AI agent frameworks.
+
+## Overview
+
+The Payments Library provides:
+- Registration and discovery of AI agents with payment plans
+- Flexible pricing options (fixed per request or dynamic usage-based)
+- Credit-based access control with on-chain settlement
+- Support for browser and Node.js environments
+- Integration with MCP (Model Context Protocol) and A2A (Agent-to-Agent) protocols
+
+## Prerequisites
+
+Before installing the Nevermined Payments Library, ensure you have:
+
+- **Node.js**: Version 18.x or higher
+- **TypeScript**: Version 5.x or higher (recommended)
+- **Nevermined API Key**: Get your free API key from [nevermined.app](https://nevermined.app)
+- **Package Manager**: npm (included with Node.js) or pnpm
+
+## Installation
+
+Install the library using npm or pnpm. Pin the major version (or use a lockfile-tracked exact version) so SDK upgrades are explicit and reviewable:
+
+```bash
+# Using npm
+npm install @nevermined-io/payments@^1.1
+
+# Using pnpm
+pnpm add @nevermined-io/payments@^1.1
+```
+
+> 🔐 **Security:** always commit your `package-lock.json` / `pnpm-lock.yaml` and review SDK version bumps before deploying. Running unpinned installs in production lets transitive dependencies change between deploys.
+
+### Peer Dependencies
+
+The library has optional peer dependencies for specific integrations:
+
+```bash
+# For MCP (Model Context Protocol) integration
+npm install @modelcontextprotocol/sdk
+
+# For Express-based HTTP agents
+npm install express @types/express
+```
+
+These dependencies are only required if you're using the respective integration features.
+
+## Verify Installation
+
+After installation, verify the library is correctly installed by importing it:
+
+```typescript
+import { Payments } from '@nevermined-io/payments'
+
+console.log('Nevermined Payments Library installed successfully!')
+```
+
+You can also check the installed version:
+
+```bash
+npm list @nevermined-io/payments
+```
+
+## Next Steps
+
+After successful installation:
+
+1. Get your Nevermined API key from [nevermined.app](https://nevermined.app)
+2. Choose your environment (sandbox for testing, live for production)
+3. Initialize the Payments instance in your application
+
+Continue to [Initializing the Library](./initializing-the-library) to get started.
+
+---
+
+**Source References**:
+- `package.json`
+- `README.md`
diff --git a/docs/api-reference/typescript/mcp-integration.md b/docs/api-reference/typescript/mcp-integration.md
new file mode 100644
index 00000000..73192546
--- /dev/null
+++ b/docs/api-reference/typescript/mcp-integration.md
@@ -0,0 +1,561 @@
+---
+title: 'MCP Integration'
+description: 'Build payment-protected MCP servers with OAuth 2.1 authentication and automatic credit management'
+icon: 'plug'
+---
+
+# MCP Integration
+
+The Model Context Protocol (MCP) integration provides a complete payment-protected MCP server with OAuth 2.1 support and automatic credit management. This is the simplest way to run a payment-protected AI agent.
+
+## Overview of MCP Integration
+
+The MCP integration automatically handles:
+
+- **OAuth 2.1 Discovery**: Auto-configured `.well-known` endpoints
+- **Paywall Protection**: Automatic token verification and credit burning
+- **Streaming Support**: SSE (Server-Sent Events) for streaming responses
+- **Credit Management**: Fixed or dynamic credit costs per tool/resource/prompt
+- **Client Registration**: Dynamic client registration for OAuth flows
+
+## OAuth 2.1 Discovery
+
+When you start an MCP server, the library automatically exposes OAuth 2.1 discovery endpoints required by the X402 spec:
+
+| Endpoint                                  | Description                   |
+| ----------------------------------------- | ----------------------------- |
+| `/.well-known/oauth-protected-resource`   | Protected resource metadata   |
+| `/.well-known/oauth-authorization-server` | Authorization server metadata |
+| `/.well-known/openid-configuration`       | OpenID Connect discovery      |
+| `POST /register`                          | Dynamic client registration   |
+
+These endpoints are generated automatically—no manual configuration required.
+
+## Configure MCP
+
+Initialize the MCP integration with your plan details:
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Configure MCP integration
+payments.mcp.configure({
+  planId: process.env.NVM_PLAN_ID!,
+  agentId: process.env.NVM_AGENT_ID, // optional — informational only
+  serverName: 'my-mcp-server',
+})
+```
+
+> **`planId` is required; `agentId` is optional.** The x402 facilitator is
+> plan-centric — verify/settle resolve everything from the plan and the
+> subscriber's token. `agentId` is informational only (it also populates the
+> OAuth `client_id` when present). A per-tool `planId` option overrides the
+> server-level plan.
+
+## Register Tools with Credits
+
+Register MCP tools and specify their credit cost:
+
+```typescript
+import { z } from 'zod'
+
+// Register a tool with fixed credit cost
+payments.mcp.registerTool(
+  'get_weather', // Tool name
+  {
+    title: 'Get Weather',
+    description: 'Get current weather for a city',
+    inputSchema: z.object({
+      city: z.string().describe('City name'),
+    }),
+  },
+  async (args) => {
+    // Handler function
+    // Your tool logic here
+    const weather = await getWeatherData(args.city)
+
+    return {
+      content: [{ type: 'text', text: `Weather in ${args.city}: ${weather}` }],
+    }
+  },
+  { credits: 1n }, // Fixed: 1 credit per call
+)
+```
+
+### Dynamic Credit Calculation
+
+For variable costs based on input/output:
+
+```typescript
+payments.mcp.registerTool(
+  'analyze_text',
+  {
+    title: 'Analyze Text',
+    description: 'Perform text analysis',
+    inputSchema: z.object({
+      text: z.string(),
+    }),
+  },
+  async (args) => {
+    const analysis = await analyzeText(args.text)
+    return {
+      content: [{ type: 'text', text: JSON.stringify(analysis) }],
+    }
+  },
+  {
+    // Dynamic credits based on text length
+    credits: (ctx) => {
+      const { text } = ctx.args as { text: string }
+      const textLength = text.length
+      return BigInt(Math.ceil(textLength / 1000)) // 1 credit per KB
+    },
+  },
+)
+```
+
+## Register Resources
+
+Register MCP resources with payment protection:
+
+```typescript
+payments.mcp.registerResource(
+  'weather-data', // Resource name
+  'weather://current', // Resource URI
+  {
+    title: 'Current Weather Data',
+    description: 'Real-time weather information',
+  },
+  async (uri, vars) => {
+    // Handler function
+    const data = await fetchWeatherData()
+
+    return {
+      contents: [
+        {
+          uri: 'weather://current',
+          mimeType: 'application/json',
+          text: JSON.stringify(data),
+        },
+      ],
+    }
+  },
+  { credits: 2n }, // 2 credits per access
+)
+```
+
+## Register Prompts
+
+Register MCP prompts with credit costs:
+
+```typescript
+payments.mcp.registerPrompt(
+  'weather-query', // Prompt name
+  {
+    title: 'Weather Query Template',
+    description: 'Generate weather queries',
+  },
+  async (args) => {
+    // Handler function
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `What is the weather in ${args.city}?`,
+          },
+        },
+      ],
+    }
+  },
+  { credits: 1n }, // 1 credit per prompt
+)
+```
+
+## Start Managed Server
+
+Start a complete MCP server with all endpoints configured:
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Configure
+payments.mcp.configure({
+  planId: process.env.NVM_PLAN_ID!,
+  agentId: process.env.NVM_AGENT_ID, // optional — informational only
+  serverName: 'weather-server',
+})
+
+// Register tools
+payments.mcp.registerTool(
+  'get_weather',
+  {
+    title: 'Get Weather',
+    description: 'Get current weather',
+    inputSchema: z.object({
+      city: z.string(),
+    }),
+  },
+  async (args) => ({
+    content: [{ type: 'text', text: `Weather in ${args.city}: Sunny` }],
+  }),
+  { credits: 1n },
+)
+
+// Start server (bind to localhost by default; expose via a reverse proxy with HTTPS for public traffic)
+const { info, stop } = await payments.mcp.start({
+  port: 5001,
+  host: process.env.MCP_HOST ?? '127.0.0.1',
+  planId: process.env.NVM_PLAN_ID!,
+  agentId: process.env.NVM_AGENT_ID, // optional — informational only
+  serverName: 'weather-server',
+  version: '1.0.0',
+})
+
+console.log(`MCP Server running at: ${info.baseUrl}`)
+console.log(`MCP endpoint: ${info.baseUrl}/mcp`)
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  await stop()
+  console.log('Server stopped')
+  process.exit(0)
+})
+```
+
+> 🔐 **Bind to localhost in development.** The MCP server holds an OAuth issuer and accepts paid requests — exposing it directly on `0.0.0.0` is rarely what you want. Bind to `127.0.0.1` and front it with a reverse proxy (Caddy, nginx, Traefik) terminating TLS for any public traffic.
+
+## MCP Logical URIs
+
+When registering your agent at [nevermined.app](https://nevermined.app), use MCP logical URIs instead of HTTP URLs:
+
+### URI Format
+
+```
+mcp://<serverName>/<type>/<name>
+```
+
+### Examples
+
+| Type              | URI                                                | Description     |
+| ----------------- | -------------------------------------------------- | --------------- |
+| Tool              | `mcp://weather-server/tools/get_weather`           | Single tool     |
+| Tool Wildcard     | `mcp://weather-server/tools/*`                     | All tools       |
+| Resource          | `mcp://weather-server/resources/weather://current` | Single resource |
+| Resource Wildcard | `mcp://weather-server/resources/*`                 | All resources   |
+| Prompt            | `mcp://weather-server/prompts/weather-query`       | Single prompt   |
+
+### Wildcard Registration
+
+Use wildcards to register all tools/resources/prompts at once:
+
+```
+mcp://weather-server/tools/*
+mcp://weather-server/resources/*
+mcp://weather-server/prompts/*
+```
+
+## Auto-Configured Endpoints
+
+The `start()` method automatically creates these endpoints:
+
+```
+POST /mcp              - MCP JSON-RPC endpoint
+GET /mcp               - SSE streaming endpoint
+DELETE /mcp            - Session cleanup
+GET /                  - Server info
+GET /health            - Health check
+GET /.well-known/oauth-protected-resource
+GET /.well-known/oauth-authorization-server
+GET /.well-known/openid-configuration
+POST /register         - Dynamic client registration
+```
+
+## Complete Example: Weather Agent
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+import { z } from 'zod'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Configure MCP
+payments.mcp.configure({
+  planId: process.env.NVM_PLAN_ID!,
+  agentId: process.env.NVM_AGENT_ID, // optional — informational only
+  serverName: 'weather-agent',
+})
+
+// Register multiple tools
+payments.mcp.registerTool(
+  'get_current_weather',
+  {
+    title: 'Get Current Weather',
+    description: 'Get real-time weather for a location',
+    inputSchema: z.object({
+      city: z.string(),
+      country: z.string().optional(),
+    }),
+  },
+  async (args) => {
+    const weather = await fetchWeather(args.city, args.country)
+    return {
+      content: [{ type: 'text', text: JSON.stringify(weather) }],
+    }
+  },
+  { credits: 1n },
+)
+
+payments.mcp.registerTool(
+  'get_forecast',
+  {
+    title: 'Get Weather Forecast',
+    description: 'Get 7-day weather forecast',
+    inputSchema: z.object({
+      city: z.string(),
+      days: z.number().min(1).max(7).default(3),
+    }),
+  },
+  async (args) => {
+    const forecast = await fetchForecast(args.city, args.days)
+    return {
+      content: [{ type: 'text', text: JSON.stringify(forecast) }],
+    }
+  },
+  { credits: 2n }, // Forecasts cost more
+)
+
+// Register resource
+payments.mcp.registerResource(
+  'weather-alerts',
+  'weather://alerts',
+  {
+    title: 'Weather Alerts',
+    description: 'Active weather alerts',
+  },
+  async (uri) => {
+    const alerts = await fetchAlerts()
+    return {
+      contents: [
+        {
+          uri: 'weather://alerts',
+          mimeType: 'application/json',
+          text: JSON.stringify(alerts),
+        },
+      ],
+    }
+  },
+  { credits: 1n },
+)
+
+// Start server (bind to localhost by default; front with HTTPS reverse proxy for public traffic)
+const { info, stop } = await payments.mcp.start({
+  port: 5001,
+  host: process.env.MCP_HOST ?? '127.0.0.1',
+  planId: process.env.NVM_PLAN_ID!,
+  agentId: process.env.NVM_AGENT_ID, // optional — informational only
+  serverName: 'weather-agent',
+  version: '1.0.0',
+})
+
+console.log(`Weather MCP Agent running at ${info.baseUrl}`)
+console.log(`Register in Nevermined App with:`)
+console.log(`  - mcp://weather-agent/tools/*`)
+console.log(`  - mcp://weather-agent/resources/*`)
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  await stop()
+  process.exit(0)
+})
+
+// Mock functions
+async function fetchWeather(city: string, country?: string) {
+  return { city, temp: 72, condition: 'sunny' }
+}
+
+async function fetchForecast(city: string, days: number) {
+  return { city, days, forecast: [] }
+}
+
+async function fetchAlerts() {
+  return { alerts: [] }
+}
+```
+
+## Handler Options
+
+| Option          | Type                   | Description                                                                                                                                                                                                                             |
+| --------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `credits`       | `bigint` or `function` | Credits to consume per call                                                                                                                                                                                                             |
+| `planId`        | `string`               | Per-handler plan ID override. A server-level `planId` (set via `configure`/`start`) is required; set this only to charge a different plan for this handler.                                                                               |
+| `maxAmount`     | `bigint`               | Max credits to verify during authentication (default: `1n`)                                                                                                                                                                             |
+| `onRedeemError` | `string`               | On post-execution settlement failure: `'ignore'` (default) returns the in-band payment error; `'propagate'` throws a JSON-RPC error. Tool content is always suppressed either way (paid content is never delivered without settlement). |
+
+## In-band x402 signaling (`_meta`)
+
+The MCP transport follows the [x402 v2 MCP transport spec](https://github.com/coinbase/x402/blob/main/specs/transports-v2/mcp.md): payments are signaled **in band** through the MCP tool-call machinery, not via HTTP status codes or headers.
+
+### Request — payment payload
+
+The client sends the x402 `PaymentPayload` in the request params `_meta["x402/payment"]` (plain JSON). Note this is the **payment** channel — separate from session auth: the MCP session is an OAuth-protected resource, so the client must also send an `Authorization: Bearer <accessToken>` header on the transport to establish the session (`initialize` returns `401` without it). For backwards compatibility the server also reads the payment from that header alone (no `_meta`) as a **deprecated fallback** for one release.
+
+```typescript
+import { decodeAccessToken } from '@nevermined-io/payments'
+
+// Mint a token against a delegation (create one first). `agentId` (2nd arg) is
+// optional, but `delegationConfig` is required.
+const { delegationId } = await payments.delegation.createDelegation({
+  provider: 'erc4337', // 'stripe' | 'braintree' | 'visa' for fiat plans
+  spendingLimitCents: 10000,
+  durationSecs: 604800,
+  currency: 'usdc', // 'usd' for fiat plans
+})
+const { accessToken } = await payments.x402.getX402AccessToken(planId, undefined, {
+  delegationConfig: { delegationId },
+})
+
+await client.callTool({
+  name: 'get_weather',
+  arguments: { city: 'Madrid' },
+  // Carry the payment in band (the spec-defined transport):
+  _meta: { 'x402/payment': decodeAccessToken(accessToken) },
+})
+```
+
+### Response — settlement receipt
+
+On a successful paid call, the SDK injects the settlement receipt under `_meta["x402/payment-response"]` (the spec key), and Nevermined-specific observability under a namespaced `_meta["nevermined/credits"]` key:
+
+```typescript
+{
+  content: [{ type: 'text', text: 'result' }],
+  _meta: {
+    // Spec-defined settlement receipt (x402 v2 MCP transport)
+    'x402/payment-response': {
+      success: true,
+      transaction: '0xabc...',
+      network: 'eip155:84532',
+      payer: '0x123...',
+      creditsRedeemed: '5',
+      remainingBalance: '95',
+    },
+    // Nevermined-namespaced observability (NOT part of the x402 spec)
+    'nevermined/credits': {
+      success: true,
+      txHash: '0xabc...',
+      creditsRedeemed: '5',
+      planId: 'plan-123',
+      subscriberAddress: '0x123...',
+    },
+  }
+}
+```
+
+Free / no-credit calls omit the `x402/payment-response` key (no settlement occurred); `nevermined/credits` is still attached with `creditsRedeemed: '0'`.
+
+### Payment required
+
+When payment is required (missing/invalid token, or no subscription), the tool returns an **error tool result** carrying the x402 `PaymentRequired` object — there is no HTTP `402` on `/mcp`:
+
+```typescript
+{
+  isError: true,
+  structuredContent: { x402Version: 2, error: 'payment required', resource: { /* ... */ }, accepts: [ /* ... */ ] },
+  content: [{ type: 'text', text: '<JSON-stringified PaymentRequired>' }],
+}
+```
+
+Both `structuredContent` (the object) and `content[0].text` (its JSON string) are populated, per spec. This applies to **tools** only — resources and prompts raise a JSON-RPC error instead (they have no tool-result error channel).
+
+## Error Handling
+
+Payment-required is signaled **in band** as an error tool result (see above) — there is no HTTP `402` on `/mcp`. OAuth and payment-required live at different layers and never collide: OAuth rejects at the HTTP layer (`401`), while payment-required is an MCP tool-call result. The in-band shape inherently disambiguates the two.
+
+`onRedeemError` controls only the _error type_ surfaced when settlement fails **after** the tool executed — it no longer controls whether content is returned. Per the spec, a paid result is never delivered without settlement landing, so the executed tool's content is always suppressed on settlement failure. `'ignore'` (default) surfaces the in-band payment error; `'propagate'` throws a JSON-RPC misconfiguration error.
+
+```typescript
+payments.mcp.registerTool('premium_tool', toolConfig, handler, {
+  credits: 5n,
+  onRedeemError: 'propagate', // throw a JSON-RPC error on settlement failure (default: 'ignore')
+})
+```
+
+## Advanced: Custom Express App
+
+For existing Express applications, use `createRouter`:
+
+```typescript
+import express from 'express'
+import { Payments } from '@nevermined-io/payments'
+
+const app = express()
+const payments = Payments.getInstance({...})
+
+payments.mcp.configure({
+  planId: process.env.NVM_PLAN_ID!,
+  agentId: process.env.NVM_AGENT_ID, // optional — informational only
+  serverName: 'my-server',
+})
+
+// Register tools...
+
+// Create MCP router
+const mcpRouter = payments.mcp.createRouter({
+  planId: process.env.NVM_PLAN_ID!,
+  agentId: process.env.NVM_AGENT_ID, // optional — informational only
+  serverName: 'my-server',
+})
+
+// Mount router
+app.use('/mcp', mcpRouter)
+
+// Your other routes
+app.get('/custom', (req, res) => {
+  res.json({ status: 'ok' })
+})
+
+// Bind to localhost; expose via a reverse proxy with HTTPS for public traffic
+const server = app.listen(5001, '127.0.0.1')
+
+process.on('SIGINT', () => {
+  server.close(() => process.exit(0))
+})
+```
+
+## Best Practices
+
+1. **Descriptive Names**: Use clear tool/resource/prompt names
+2. **Schema Validation**: Always define proper input schemas with Zod
+3. **Credit Pricing**: Set appropriate credits based on resource cost
+4. **Error Messages**: Provide clear error messages in responses
+5. **Graceful Shutdown**: Always implement `SIGINT` handlers
+6. **Wildcard URIs**: Use wildcards for simpler agent registration
+7. **Version Control**: Include version in server configuration
+
+## Related Documentation
+
+- [Agents](./agents) - Register your MCP agent in Nevermined
+- [Payment Plans](./payment-plans) - Configure pricing for your agent
+- [Validation of Requests](./validation-of-requests) - Understanding the validation flow
+
+---
+
+**Source References**:
+
+- `RUN.md` (MCP Server section, lines 16-86)
+- `src/mcp/index.ts` (MCP integration API)
+- `tests/integration/mcp-integration.test.ts` (integration examples)
diff --git a/docs/api-reference/typescript/mpp-integration.md b/docs/api-reference/typescript/mpp-integration.md
new file mode 100644
index 00000000..c1a36fce
--- /dev/null
+++ b/docs/api-reference/typescript/mpp-integration.md
@@ -0,0 +1,472 @@
+---
+title: 'MPP Integration'
+description: 'Protect Express routes with the Machine Payments Protocol (MPP), a second payment framing over the same plans, delegations and credits as x402'
+icon: 'handshake'
+---
+
+# MPP Integration
+
+> **Experimental.** The `mpp` route option and the `payments.mpp.*` surface ship
+> ahead of their epic's declared MVP scope. The names are settled — `payments.mpp`
+> beside `payments.x402` is what you would guess, and renaming it after a tag
+> costs a major — but the shapes may change in a minor release until the epic
+> adopts them.
+
+The Machine Payments Protocol (MPP) is a second payment framing over the same
+Nevermined plans, delegations and credits that x402 uses. Turning it on for a
+route does not change the plan, the credits or the route configuration.
+
+## Header table
+
+| Header             | Direction                 | Purpose                            |
+| ------------------ | ------------------------- | ---------------------------------- |
+| `WWW-Authenticate` | Server → Client (402)     | Carries the `Payment …` challenge  |
+| `Authorization`    | Client → Server           | Carries the `Payment …` credential |
+| `Payment-Receipt`  | Server → Client (success) | Carries the settlement receipt     |
+
+## The 402 body: `code` and `retryable`
+
+Every `402` carries a JSON body shaped `{ error, message, code?, retryable? }`.
+`code` and `retryable` are present together, or not at all — this is the
+signal a non-SDK buyer (anything not using this package's typed error
+classes) needs to implement the retry loop correctly:
+
+- **No credential was presented yet.** `code` and `retryable` are both
+  absent. This is the opening challenge; pay it.
+- **A credential was presented and rejected.** `code` is one of the
+  backend's `BCK.MPP.*` codes, and `retryable` says whether minting a fresh
+  credential against the new challenge on this same `402` can succeed:
+  - `retryable: false` — the credential itself was refused (forged, replayed,
+    wrong plan, insufficient balance, all collapsed into `BCK.MPP.0003` so
+    the endpoint cannot be used to probe _which_ check failed). Paying again
+    with a new credential changes nothing; treat this as terminal.
+  - `retryable: true` — the challenge expired (`BCK.MPP.0004`) or the request
+    body did not match the digest sealed into the challenge
+    (`BCK.MPP.0005`, only when the route uses `bindBody`). Mint a fresh
+    credential against the challenge this same response carries and retry
+    once.
+
+`code` is never anything outside the `BCK.MPP.*` namespace — a transport or
+infrastructure failure (a network error, a `5xx` from the seller's own backend)
+is stripped rather than forwarded, so a **codeless** `402` is exactly what a
+verify-side infrastructure failure looks like from the buyer's side.
+
+Absence of a `code` is therefore not a rejection signal, and not a retry signal
+either. What the buyer keys on instead is whether the same `402` carries a
+genuinely **fresh** challenge (a different `id`): a fresh challenge means "here
+is a new price, pay it", a replayed `id` means "your credential was refused".
+See [Which backend codes are retryable](#which-backend-codes-are-retryable).
+
+## Protecting a route
+
+```typescript
+import express from 'express'
+import { Payments } from '@nevermined-io/payments'
+import { paymentMiddleware } from '@nevermined-io/payments/express'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox',
+})
+
+const app = express()
+app.use(express.json())
+
+app.use(
+  paymentMiddleware(payments, {
+    'POST /ask': { planId: PLAN_ID, credits: 2, mpp: true },
+  }),
+)
+
+app.post('/ask', (req, res) => res.json({ answer: '...' }))
+```
+
+An unpaid request is answered with `402` and a `WWW-Authenticate: Payment …`
+challenge; the x402 `payment-required` header is sent alongside it, so x402
+buyers keep working unchanged. A paid request carries the credential in
+`Authorization: Payment …`, and a successful response carries the settlement in
+`Payment-Receipt`.
+
+## Credits are sealed into the challenge
+
+Under MPP the credits are fixed when the challenge is minted. A `credits`
+function is evaluated once, at that moment, and the settlement burns the amount
+the challenge carries. There is no post-hoc re-pricing as there is with x402.
+
+## Binding the challenge to the request body
+
+```typescript
+import { captureRawBody } from '@nevermined-io/payments/express'
+
+app.use(express.json({ verify: captureRawBody }))
+app.use(
+  paymentMiddleware(payments, {
+    'POST /ask': { planId: PLAN_ID, credits: 2, mpp: { bindBody: true } },
+  }),
+)
+```
+
+`bindBody` seals a `sha-256=<base64>` digest of the raw request body into the
+challenge, so a credential minted for one body cannot be spent on another.
+
+`captureRawBody` only runs for the content-type the parser it is mounted on
+matches — `express.json({ verify: captureRawBody })` covers `application/json`
+and nothing else. A route that also accepts other content-types needs the
+hook wired into each parser it uses, or body binding fails for those requests.
+
+When `bindBody` is on and a request has a body (a non-zero `Content-Length`,
+or `Transfer-Encoding`) but its raw bytes were never captured, the middleware
+refuses the request rather than minting an unbound challenge — the binding is
+a security property, and it fails closed: a `500` if the request looked like
+the parser should have captured it (a likely configuration mistake), a `400`
+if the request's content-type is not one this route captures at all. Neither
+case falls through to a re-serialized-JSON digest; the alternative — silently
+serving an unbound challenge whenever the buyer's request shape does not
+match — would let the buyer, not the seller, decide whether binding applies.
+
+A request that carries **no body at all** on a `bindBody` route is bound to
+the digest of zero bytes rather than left unbound. Minting unbound would
+reopen the same hole from the other side: the backend only compares digests
+when the challenge carries one, so a buyer could mint with an empty request
+and then attach any body they liked to the paid retry. A bodyless retry
+reproduces the empty digest and passes; one that grew a body does not.
+
+If the seller's own settlement fails after a paid, delivered request, the
+buyer still receives their `2xx` response but no `Payment-Receipt` header —
+the settlement outcome is not otherwise visible on the wire.
+
+A seller who wires `onAfterSettle` (a `paymentMiddleware` option) sees more
+than the wire does. Settlement is the one MPP call that burns, so a request
+to the backend that times out before answering is not the same as one the
+backend actually rejected: the credits may already be burned even though
+nothing came back. That case is reported to `onAfterSettle` as
+`{ outcome: 'unknown', reason }` — the exported `MppSettlementOutcomeUnknown`
+type — instead of the usual `MppSettleResult`, and `settleCredential` itself
+rejects with the exported `MppSettlementOutcomeUnknownError` (extends
+`MppError`, and carries the stable `code` `'settlement_outcome_unknown'` —
+outside the `BCK.MPP.*` namespace the backend owns) rather than a generic
+network error, so a seller calling `settleCredential` directly can check it
+by `instanceof` **or** by `error.code`. Prefer `code` where two copies of
+this package could end up in one dependency tree, or across a process or
+serialization boundary: `instanceof` is false there for a genuinely-MPP
+error, and the check degrades silently to the "nothing was burned" path.
+
+The same unknown-outcome treatment covers a settle whose `2xx` body cannot be
+read: the backend answered, so the burn committed, and only the response was
+lost. `onAfterSettle`'s third parameter is typed
+`unknown`, so narrow to `MppSettlementOutcomeUnknown` explicitly before
+reading `outcome` — a blind cast to `MppSettleResult` reads `undefined` for
+`creditsRedeemed` on this branch with no compile-time or runtime signal.
+
+### `onPaymentError` on an MPP route
+
+On MPP routes `onPaymentError` **notifies**; the middleware keeps ownership of
+the response unless your handler answers the request itself. This differs from
+the x402 branch, where the hook takes over: an MPP `402` has to carry a fresh
+`WWW-Authenticate` challenge for the buyer to make any progress, and a hook
+wired purely for observability must not strip it.
+
+It fires for rejected credentials, expiries, digest mismatches, body-binding
+refusals, challenge-issuance failures, a settle that definitively fails, and
+a buyer disconnecting while settlement was still in flight — but **not** for
+the initial credential-less request. In MPP the first request of every
+payment cycle is unpaid by design, so notifying there would fire the hook on
+every successful payment and drown the failures it exists to surface.
+
+It **does** fire when an `Authorization` header is present but carries no
+`Payment` scheme at all — that shape means an intermediary rewrote it (a
+gateway injecting its own `Bearer`, a reverse proxy with its own auth), which
+otherwise puts the buyer in a silent infinite loop with no error visible on
+either side. A hook that throws — synchronously or as a rejected `async`
+function — is logged and the challenge is still sent.
+
+A `credits` function is evaluated once per _request_ handled by this
+middleware — once when the challenge is minted, and again when the paid
+request presents its credential — so twice per full payment cycle, not once.
+Anything with a side effect (metering, a counter, a DB write) in that
+function runs twice.
+
+## A credential buys exactly one response
+
+Verifying a credential burns nothing, and settling the same credential twice
+burns once — that idempotency is what makes settlement safe to retry. On its
+own it would also make a **replay** free: a buyer who presents the same
+credential again passes verification (nothing was burned to notice), is
+served again, and the second settlement collapses onto the first burn. The
+backend cannot refuse that — a replayed settle succeeding _is_ its
+idempotency contract working as designed — so single-use is enforced at the
+seller edge.
+
+Two guards do it, both **within one Node process** and both keyed on the
+credential's `challenge.id` — not on the raw header bytes, which the buyer
+can vary (scheme case, whitespace, JSON key order) without changing which
+credential they are:
+
+- **Concurrent** — a second request presenting a credential that is verified
+  but not yet settled is refused with `409 Conflict`. Check-and-claim is one
+  atomic step with no `await` in between, so two requests racing the same
+  credential cannot both pass.
+- **Sequential** — a credential that has already bought a response is
+  refused with a `402` carrying a **fresh challenge** and
+  `code: "BCK.MPP.0003"` (`retryable: false`), for the 300-second lifetime
+  of the challenge it came from. After that the challenge has expired and
+  the backend refuses the credential anyway.
+
+A credential that cannot be decoded into a `challenge.id` at all is refused
+the same way, without a backend round-trip — the backend would reject it too.
+
+A credential is only marked spent when a `2xx` is **actually delivered** for
+it — a status code alone is not delivery, since an aborted request still
+reports `200`. If the buyer disconnects before any of the response reaches
+them, settlement never runs and the credential stays theirs to retry with;
+`onPaymentError` still fires so the loss is visible on the seller's side,
+since MPP has no void or reversal for a burn that already committed before
+the disconnect was noticed. A request your handler answers with a `4xx`/`5xx`
+never settles either, so the buyer keeps their claim there too.
+
+**The reverse also holds, and it matters most for streaming endpoints.** On a
+streamed response (SSE, token streaming — the shape most agent endpoints
+take) the buyer receives the value at `res.write()`, well before your handler
+calls `res.end()`. A buyer who reads the payload and then hangs up **has been
+served**, so that request settles and the credential is marked spent. Delivery
+is measured as bytes actually put on the wire for that response, not as a
+socket still being open at the end of it — otherwise a buyer could stream the
+answer, disconnect, and replay the same credential for the rest of the
+challenge TTL.
+
+Neither guard extends across multiple processes or horizontally-scaled
+instances of this middleware — they do not share the in-memory state, and a
+deployment that scales this middleware horizontally needs its own mitigation
+(e.g. a shared store such as Redis) for both races across instances.
+
+## Settlement outcomes your accounting has to distinguish
+
+`settleCredential` can end three ways: a definite success, a definite
+failure, or **unknown** — the backend answered with a `5xx`/`408`, or timed
+out, or returned a `2xx` whose body could not be read, or the connection was
+reset after the request had already been written (`ECONNRESET`, `EPIPE`,
+`UND_ERR_SOCKET`). In all of those the credits may already be burned;
+reporting them as a definite failure would make a real burn silently vanish
+from your records. Failures that prove nothing was reached — `ECONNREFUSED`,
+`ENOTFOUND`, `EAI_AGAIN`, and the backend's own `4xx` rejections — stay
+definite, because inflating your records with burns that never happened is
+the same corruption in the other direction.
+
+`onAfterSettle`'s third parameter is `unknown` precisely so a definite
+failure and an unknown outcome cannot be confused for the same shape — a
+definite failure reports `creditsToSettle: 0` (nothing burned, as far as this
+side can prove), while an unknown outcome reports the charged amount and
+`{ outcome: 'unknown', reason }`. Narrow to `MppSettlementOutcomeUnknown`
+explicitly before reading `outcome`.
+
+Two consequences worth knowing before you wire up accounting:
+
+- **A definite settlement failure still delivers the response.** The buyer
+  gets what they asked for even though the burn did not happen — the
+  alternative would be destroying a response your handler already produced.
+  `onPaymentError` fires so you can reconcile, but the resource is gone.
+- **`paymentContext.creditsToSettle` is only reliable on the buffered path.**
+  When the handler streams (headers already flushed before `res.end()`),
+  settlement is detached and `res.on('finish')` fires before it resolves, so
+  the context still holds the optimistic pre-settle amount. On the buffered
+  path the response is held until settlement resolves, so it is accurate
+  there. **Read the settled amount from `onAfterSettle`, not from
+  `paymentContext`** — that is the only place correct on both paths.
+
+## Paying an MPP endpoint
+
+> **`payments.mpp.*` is `@experimental`.** The buyer surface — `MppFetchOptions`,
+> `MppFetchResult` and the fields on them — may change in a minor release.
+> `MppFetchResult` gained `settled` and `creditsPresented` between two rounds of
+> a single review; pin the package version if that matters to you.
+
+```typescript
+const { delegationId } = await payments.delegation.createDelegation({
+  provider: 'erc4337',
+  spendingLimitCents: 10000,
+  durationSecs: 604800,
+  currency: 'usdc',
+})
+
+const { response, receipt, paid, settled, credentialsPresented } = await payments.mpp.fetch(
+  'https://agent.example/ask',
+  {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ q: 'hello' }),
+  },
+  { delegationConfig: { delegationId }, planId: PLAN_ID },
+)
+
+console.log(await response.json(), receipt?.reference)
+```
+
+The helper reads the plan out of the challenge, mints an MPP access token for
+the delegation you already have, retries the request with the credential, and
+decodes the `Payment-Receipt`. `delegationConfig` must carry a `delegationId`
+— create the delegation first, the same as for x402. Passing `planId` pins
+the plan you expect to pay; the challenge naming a different plan makes the
+call fail before anything is minted. `maxCredits` does the same for price: a
+seller unilaterally names the credits in the challenge (and can raise it on a
+re-challenge), so without a cap the helper pays whatever is asked.
+
+`maxCredits` is a budget for the **whole call**, not for one challenge: the
+credits a challenge asks for are added to what earlier turns of the same call
+already committed, and the call is refused as soon as the running total would
+exceed the cap. `creditsPresented` on the result is that same running total —
+the sum across every credential presented, not the last challenge's price. It
+must be a non-negative integer (decimal string, safe integer or `bigint`);
+anything else is refused with a `PaymentsError` before the first request, not
+mid-flight on whatever 402 arrives.
+
+### What `paid: false` does and does not mean
+
+`paid` is `response.ok && settled` — it does **not** mean nothing was
+attempted. Check `credentialsPresented` (0, 1 or 2) before deciding a blind
+retry is safe:
+
+- **`credentialsPresented === 0`** — no credential was ever minted or sent.
+  The endpoint may not speak MPP, or never returned a challenge. A retry here
+  is exactly as safe as calling `fetch` again.
+- **`credentialsPresented > 0` and `settled === false`** — one or two
+  credentials were minted and presented, and their fate is not known to the
+  caller (the seller may have burned credits and failed to respond, or the
+  receipt could not be decoded). **Do not blindly retry** — that mints and
+  presents yet another credential. Inspect `response` and `creditsPresented`
+  first.
+- **`settled === true`** (equivalently, `receipt` is present) — the payment
+  succeeded regardless of what `paid` says. `paid` additionally requires the
+  HTTP response itself to be a 2xx; a settle-then-error response from a
+  seller is `settled: true, paid: false`. `settled` is exactly "a receipt
+  decoded cleanly": `receipt.status` is a seller-set string with no agreed
+  vocabulary beyond `'success'`, so it is deliberately not interpreted —
+  read it yourself if you are paying a third-party seller and it matters.
+  This SDK's own middleware attaches a receipt only when settlement succeeded.
+
+A request to an endpoint that never challenges (no 402 at all) comes back
+untouched, with `paid: false` and `credentialsPresented: 0` — this holds for
+any body type, including a `ReadableStream`.
+
+**`response.ok === true` with `paid: false` and `credentialsPresented: 1` is a
+routine outcome, not an exotic one.** A seller whose handler streams or flushes
+has already sent its headers by the time settlement runs, so it cannot attach
+`Payment-Receipt` to a response that is on the wire — this SDK's own middleware
+settles detached in exactly that case and says so in its own log line. The
+credits **were** burned. Never read that combination as "the payment did not
+happen" and retry it.
+
+#### What comes back as a 402 instead of throwing
+
+Only a rejection the remote **named** throws. Three dead ends resolve with the
+402 as `response`, because that response is evidence you may need and throwing
+would discard it:
+
+1. A 402 with no **usable** `Payment` challenge, on either turn: no
+   `WWW-Authenticate` header, a different scheme, or a `Payment` challenge
+   missing a required param — the decoder returns nothing for all three, so a
+   seller that announced `Payment` but sent it malformed lands here too, not
+   only one that does not speak MPP. `credentialsPresented: 0`.
+2. A retry-turn 402 that is retryable but carries no challenge to retry
+   against, so there is nothing to mint for.
+3. The one re-challenge cycle spent: two credentials presented and the seller
+   still answering 402.
+
+Cases 2 and 3 come back with a **non-zero** `credentialsPresented`, so a
+resolved promise on its own does not mean the request was free. Check
+`response.ok`.
+
+### Streaming request bodies
+
+A `ReadableStream` request body works exactly like plain `fetch` **as long as
+the endpoint never challenges the request** — the single underlying `fetch()`
+consumes it once, safely. The one caveat: if the endpoint _does_ answer with a
+402 challenge, the retry needs to resend the same body, and a stream can only
+be read once. In that case `payments.mpp.fetch` throws before attempting the
+retry, rather than let it fail with an opaque runtime error. A `string`,
+`Buffer`/`ArrayBuffer`/typed array, `URLSearchParams`, `FormData` or `Blob`
+body has no such caveat — pass one of those instead if the endpoint may
+challenge the request.
+
+### Errors
+
+Two families, thrown for different reasons:
+
+- **`PaymentsError`** (`code: 'validation'`) — a guard this call refused to
+  even attempt: a missing or unusable `delegationConfig` (it must carry a
+  `delegationId` — the deprecated inline create-on-the-fly shape is not
+  accepted here), a malformed `maxCredits`, a challenge naming a different plan
+  than `planId` pinned, a challenge that would take the call over `maxCredits`,
+  or a `ReadableStream` body that a retry would need to replay.
+- **`MppError`** and its typed subclasses — what the wire actually said:
+  `MppNotConfiguredError` when the environment has MPP switched off,
+  `MppCredentialRejectedError` when the backend names that code explicitly, a
+  generic `MppError` for a rejection the backend answers without a code
+  (including the seller replaying an identical challenge, or an unreadable/
+  non-JSON 402 body), and a generic `MppError` for a 402 whose challenge could
+  not be decoded at all.
+- **`MppSpendOutcomeUnknownError`** (a subclass of `MppError`, code
+  `spend_outcome_unknown`) — the credential-bearing retry failed at the
+  transport level: a disconnect, a DNS failure, or your own `AbortSignal`
+  firing between the mint and the retry. The credential was on the wire, so the
+  seller may already have verified and burned it. The original failure is on
+  `.cause`. This exists so such a failure cannot reach you as a raw `TypeError`
+  that the `instanceof MppError` pattern below misses.
+
+#### Errors report what was already spent
+
+An argument guard on the **first** turn throws before anything is minted. A
+guard on the **re-challenge** turn does not — a credential has already been
+presented by then — so every error raised after a credential went out carries
+the same accounting the success path returns. Read it with `mppSpendOf`, which
+works across both error families (they share no base class):
+
+```typescript
+import { mppSpendOf, MppError } from '@nevermined-io/payments'
+
+try {
+  await payments.mpp.fetch(url, init, { delegationConfig: { delegationId }, maxCredits: 100 })
+} catch (err) {
+  const spend = mppSpendOf(err) // undefined => nothing was spent
+  if (spend) {
+    // spend.credentialsPresented, spend.creditsPresented, spend.challengeId
+    // Do NOT blindly retry: those credits may already be burned.
+  }
+  if (err instanceof MppError) {
+    /* the wire refused, or the retry never completed */
+  }
+}
+```
+
+#### Which backend codes are retryable
+
+A 402 that comes back after a credential was presented carries a backend
+code. Only two are retryable — everything else is terminal and surfaces as a
+typed error instead of a second mint:
+
+| Code                                                                                                                    | Meaning                                                                                                                                                                                                                                                | Retryable?                                                                                                                                        |
+| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BCK.MPP.0004`                                                                                                          | The challenge expired                                                                                                                                                                                                                                  | Yes — retried automatically, once, with the fresh challenge the 402 carries                                                                       |
+| `BCK.MPP.0005`                                                                                                          | The request body did not match the digest sealed in the challenge                                                                                                                                                                                      | Yes — the fresh challenge is sealed to the body that just arrived, so a new credential for it (same body) matches; retried automatically, once    |
+| `BCK.MPP.0003`                                                                                                          | The credential was refused (replay, forgery, wrong plan, insufficient balance)                                                                                                                                                                         | No — terminal, throws `MppCredentialRejectedError`                                                                                                |
+| `BCK.MPP.0002`                                                                                                          | MPP is not configured on this environment                                                                                                                                                                                                              | No — terminal, throws `MppNotConfiguredError` (surfaces from the mint, before any challenge is even presented)                                    |
+| **No code at all**, and the 402 carries a genuinely fresh challenge (different `id`)                                    | A seller that publishes no codes — a third party, or **this SDK's own middleware** when verification fails for infrastructure reasons: it forwards a code only when it starts with `BCK.MPP.`, so a synthesized `network_error`/`http_500` is stripped | Yes — treated as a real re-challenge and retried once, against the NEW challenge                                                                  |
+| **No code at all**, and no fresh challenge — same `id` replayed, no parseable challenge, or an unreadable/non-JSON body | A seller refusing the credential it just issued that challenge for, or a proxy/WAF page                                                                                                                                                                | No — terminal, throws a generic `MppError`: minting against the same challenge again cannot help and would only spend twice                       |
+| Any other code on a credential-bearing retry                                                                            | A non-compliant seller, or a backend failure surfacing a non-`BCK.MPP.*` code                                                                                                                                                                          | No — terminal, throws a generic `MppError`. When a code is present it decides alone; the fresh-challenge fallback applies only when there is none |
+
+Both retryable codes share the same one-shot budget: `payments.mpp.fetch`
+follows at most one re-challenge cycle per call, so a seller that keeps
+challenging a freshly paid credential is not satisfied by looping.
+`MppChallengeExpiredError` and `MppBodyDigestMismatchError` are therefore
+never thrown by the **retry gate** — they name exactly the two cases it retries
+automatically. They can still reach a caller from the **mint**, the other call
+in the turn: `MppAPI.post` forwards the backend's `code` into the typed
+hierarchy, so a mint answering `BCK.MPP.0004` surfaces as
+`MppChallengeExpiredError` before any credential is presented — the same way
+`BCK.MPP.0002` does in the row above.
+
+### Note on schemes
+
+This helper mints `nvm:erc4337` access tokens only in this release. A buyer
+holding an `nvm:card-delegation` delegation cannot use `payments.mpp.fetch`
+yet — use `payments.x402.getX402AccessToken` with `scheme: 'nvm:card-delegation'`
+against an x402-only route instead.
diff --git a/docs/api-reference/typescript/payment-plans.md b/docs/api-reference/typescript/payment-plans.md
new file mode 100644
index 00000000..c9dc5535
--- /dev/null
+++ b/docs/api-reference/typescript/payment-plans.md
@@ -0,0 +1,395 @@
+---
+title: "Payment Plans"
+description: "Create and manage flexible payment plans with credits, time-based access, and multiple pricing options"
+icon: "credit-card"
+---
+
+# Payment Plans
+
+Payment plans define how subscribers access your AI agents. The Nevermined Payments Library provides a flexible Plans API for registering different types of plans with various pricing and credit configurations.
+
+## Overview of Payment Plans API
+
+The Plans API (`payments.plans`) allows AI builders to:
+- Define pricing structures (fiat, crypto, ERC20 tokens, or free)
+- Configure credit allocation (fixed, dynamic, time-based)
+- Register plans with the Nevermined protocol
+- Retrieve and manage existing plans
+- Associate plans with agents
+
+## Types of Payment Plans
+
+### Credits Plans
+Grant subscribers a specific number of credits to use across multiple requests. Each agent request burns a defined number of credits.
+
+**Use cases**: API calls, LLM queries, data processing tasks
+
+### Time Plans
+Provide unlimited access for a fixed duration. No per-request credit deduction during the validity period.
+
+**Use cases**: Subscriptions, unlimited access periods, trial memberships
+
+### Trial Plans
+Free plans with time limitations, perfect for demos and user onboarding.
+
+**Use cases**: Free trials, demonstrations, testing
+
+### Pay-As-You-Go Plans
+Dynamic pricing where subscribers pay per request without pre-purchasing credits.
+
+**Use cases**: Variable usage patterns, enterprise integrations
+
+## Price Configuration
+
+The library provides helper functions for different payment methods:
+
+### Crypto Payment (Native Token)
+
+```typescript
+import { Payments } from '@nevermined-io/payments'
+import { ZeroAddress } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox',
+})
+
+const builderAddress = payments.getAccountAddress()
+
+// Native token pricing (ETH, MATIC, etc.)
+const priceConfig = payments.plans.getCryptoPriceConfig(
+  100n,           // Amount in wei
+  builderAddress, // Receiver address
+  ZeroAddress     // Native token
+)
+```
+
+### ERC20 Token Payment
+
+```typescript
+// ERC20 token pricing (USDC, DAI, etc.)
+const USDC_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e' // USDC on Base Sepolia
+
+const priceConfig = payments.plans.getERC20PriceConfig(
+  20n,            // Amount in token's smallest unit
+  USDC_ADDRESS,   // Token contract address
+  builderAddress  // Receiver address
+)
+```
+
+### EURC Token Payment (Euro Stablecoin)
+
+```typescript
+// EURC pricing (Euro stablecoin on Base, 6 decimals)
+const eurcPriceConfig = payments.plans.getEURCPriceConfig(
+  29_000_000n,    // €29.00 in smallest unit (6 decimals)
+  builderAddress  // Receiver address
+)
+
+// Or use a custom EURC address (e.g., testnet)
+import { EURC_TOKEN_ADDRESS_TESTNET } from '@nevermined-io/payments'
+
+const testnetEurcConfig = payments.plans.getEURCPriceConfig(
+  29_000_000n,
+  builderAddress,
+  EURC_TOKEN_ADDRESS_TESTNET
+)
+```
+
+### Fiat Payment (Stripe)
+
+```typescript
+// Fiat pricing in USD (default)
+const priceConfig = payments.plans.getFiatPriceConfig(
+  10_000_000n,    // Amount in 6-decimal units ($10.00) — NOT cents
+  builderAddress
+)
+
+// Fiat pricing in EUR
+import { Currency } from '@nevermined-io/payments'
+
+const eurPriceConfig = payments.plans.getFiatPriceConfig(
+  29_000_000n,    // Amount in 6-decimal units (€29.00) — NOT cents
+  builderAddress,
+  Currency.EUR
+)
+```
+
+> Fiat amounts are in **6-decimal units** (the USDC convention used across the Nevermined protocol), **not** cents — `10_000_000n` = $10.00. The server-side minimum is **$1.00** (`1_000_000n`); smaller amounts are rejected with `BCK.PROTOCOL.0047`.
+
+### Free Plans
+
+```typescript
+// Free plan (no payment required)
+const priceConfig = payments.plans.getFreePriceConfig()
+```
+
+### Pay-As-You-Go Pricing
+
+```typescript
+// Get template address for PAYG plans
+const templateAddress = await payments.contracts.getPayAsYouGoTemplateAddress()
+
+const priceConfig = payments.plans.getPayAsYouGoPriceConfig(
+  100n,              // Cost per request
+  builderAddress,
+  ZeroAddress,       // Token address (optional)
+  templateAddress
+)
+```
+
+## Credits Configuration
+
+### Fixed Credits
+
+Grants a specific number of credits with a fixed burn rate per request.
+
+```typescript
+import { ONE_DAY_DURATION } from '@nevermined-io/payments'
+
+// Grant 100 credits, burn 1 credit per request
+const creditsConfig = payments.plans.getFixedCreditsConfig(
+  100n,  // Total credits granted
+  1n     // Credits per request
+)
+```
+
+### Dynamic Credits
+
+Allows variable credit consumption per request within a range.
+
+```typescript
+// Grant 10 credits, burn 1-2 credits per request (agent decides)
+const creditsConfig = payments.plans.getDynamicCreditsConfig(
+  10n,  // Total credits granted
+  1n,   // Minimum credits per request
+  2n    // Maximum credits per request
+)
+```
+
+### Time-Based Credits (Expirable)
+
+Provides unlimited access for a fixed duration.
+
+```typescript
+import { ONE_DAY_DURATION, ONE_WEEK_DURATION, ONE_MONTH_DURATION } from '@nevermined-io/payments'
+
+// Unlimited access for 24 hours
+const creditsConfig = payments.plans.getExpirableDurationConfig(
+  ONE_DAY_DURATION  // Duration in seconds
+)
+
+// Other durations
+const weeklyConfig = payments.plans.getExpirableDurationConfig(ONE_WEEK_DURATION)
+const monthlyConfig = payments.plans.getExpirableDurationConfig(ONE_MONTH_DURATION)
+```
+
+### Non-Expirable Duration
+
+```typescript
+// Unlimited access with no expiration
+const creditsConfig = payments.plans.getNonExpirableDurationConfig()
+```
+
+## Registering Plans
+
+### Register a Credits Plan
+
+```typescript
+import { Payments } from '@nevermined-io/payments'
+import { PlanMetadata } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox',
+})
+
+const builderAddress = payments.getAccountAddress()
+const ERC20_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
+
+// Define plan metadata
+const planMetadata: PlanMetadata = {
+  name: 'Basic AI Agent Access',
+  description: 'Get 100 credits to query our AI agent',
+}
+
+// Configure pricing and credits
+const priceConfig = payments.plans.getERC20PriceConfig(
+  20n,
+  ERC20_ADDRESS,
+  builderAddress
+)
+
+const creditsConfig = payments.plans.getFixedCreditsConfig(100n, 1n)
+
+// Register the plan
+const { planId } = await payments.plans.registerCreditsPlan(
+  planMetadata,
+  priceConfig,
+  creditsConfig
+)
+
+console.log(`Credits plan registered with ID: ${planId}`)
+```
+
+### Register a Time Plan
+
+```typescript
+import { ONE_DAY_DURATION, PlanMetadata } from '@nevermined-io/payments'
+
+const planMetadata: PlanMetadata = {
+  name: '24-Hour Unlimited Access',
+  description: 'Unlimited queries for 24 hours',
+}
+
+const priceConfig = payments.plans.getERC20PriceConfig(
+  50n,
+  ERC20_ADDRESS,
+  builderAddress
+)
+
+const creditsConfig = payments.plans.getExpirableDurationConfig(ONE_DAY_DURATION)
+
+const { planId } = await payments.plans.registerTimePlan(
+  planMetadata,
+  priceConfig,
+  creditsConfig
+)
+
+console.log(`Time plan registered with ID: ${planId}`)
+```
+
+### Register a Trial Plan
+
+```typescript
+import { ONE_DAY_DURATION, PlanMetadata } from '@nevermined-io/payments'
+
+const planMetadata: PlanMetadata = {
+  name: 'Free 24-Hour Trial',
+  description: 'Try our AI agent free for 24 hours',
+}
+
+// Free pricing
+const priceConfig = payments.plans.getFreePriceConfig()
+
+// Limited duration
+const creditsConfig = payments.plans.getExpirableDurationConfig(ONE_DAY_DURATION)
+
+const { planId } = await payments.plans.registerTimeTrialPlan(
+  planMetadata,
+  priceConfig,
+  creditsConfig
+)
+
+console.log(`Trial plan registered with ID: ${planId}`)
+```
+
+## Retrieving Plans
+
+### Get a Specific Plan
+
+```typescript
+// Retrieve plan details by ID
+const plan = await payments.plans.getPlan(planId)
+
+console.log(`Plan: ${plan.name}`)
+console.log(`Price: ${plan.price}`)
+console.log(`Credits: ${plan.credits}`)
+```
+
+### List Your Plans
+
+List the plans **you** published — the authenticated caller's own plans. This is
+account management, not a marketplace search: it never returns other users'
+plans. Pass an `orgId` to list every plan in an organization you belong to.
+
+```typescript
+// Your own plans (paginated: { total, page, offset, plans })
+const { plans } = await payments.plans.getPlans()
+
+plans.forEach((plan) => {
+  console.log(`${plan.name}: ${plan.planId}`)
+})
+
+// Every plan in an organization you belong to
+const { plans: orgPlans } = await payments.plans.getPlans(1, 100, 'created', 'desc', 'org-acme')
+```
+
+### Get Plans for an Agent
+
+To find plans associated with an agent, use the agents API:
+
+```typescript
+// Get all payment plans associated with an agent
+const { plans } = await payments.agents.getAgentPlans(agentId)
+
+plans.forEach(plan => {
+  console.log(`Plan: ${plan.name} (${plan.planId})`)
+})
+```
+
+## Duration Constants
+
+The library provides convenient duration constants:
+
+```typescript
+import {
+  ONE_DAY_DURATION,     // 86,400 seconds (24 hours)
+  ONE_WEEK_DURATION,    // 604,800 seconds (7 days)
+  ONE_MONTH_DURATION,   // 2,629,746 seconds (~30.44 days)
+  ONE_YEAR_DURATION     // 31,557,600 seconds (~365.25 days)
+} from '@nevermined-io/payments'
+```
+
+## Complete Example: Multi-Tier Plans
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+import { ONE_DAY_DURATION, ONE_MONTH_DURATION } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+const builderAddress = payments.getAccountAddress()
+const ERC20_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
+
+// Free trial plan
+const { planId: trialPlanId } = await payments.plans.registerTimeTrialPlan(
+  { name: 'Free Trial', description: '24 hours free access' },
+  payments.plans.getFreePriceConfig(),
+  payments.plans.getExpirableDurationConfig(ONE_DAY_DURATION)
+)
+
+// Basic tier - 100 credits
+const { planId: basicPlanId } = await payments.plans.registerCreditsPlan(
+  { name: 'Basic Plan', description: '100 credits for basic usage' },
+  payments.plans.getERC20PriceConfig(10n, ERC20_ADDRESS, builderAddress),
+  payments.plans.getFixedCreditsConfig(100n, 1n)
+)
+
+// Pro tier - unlimited monthly access
+const { planId: proPlanId } = await payments.plans.registerTimePlan(
+  { name: 'Pro Plan', description: 'Unlimited access for 30 days' },
+  payments.plans.getERC20PriceConfig(50n, ERC20_ADDRESS, builderAddress),
+  payments.plans.getExpirableDurationConfig(ONE_MONTH_DURATION)
+)
+
+console.log('Multi-tier plans created:')
+console.log(`Trial: ${trialPlanId}`)
+console.log(`Basic: ${basicPlanId}`)
+console.log(`Pro: ${proPlanId}`)
+```
+
+## Related Documentation
+
+- [Agents](./agents) - Associate plans with agents
+- [Payments and Balance](./payments-and-balance) - How subscribers order plans
+
+---
+
+**Source References**:
+- `src/plans.ts` (helper functions, duration constants)
+- `src/api/plans-api.ts` (Plans API methods)
+- `tests/e2e/test_payments_e2e.test.ts` (lines 277-369)
diff --git a/docs/api-reference/typescript/payments-and-balance.md b/docs/api-reference/typescript/payments-and-balance.md
new file mode 100644
index 00000000..12505ad2
--- /dev/null
+++ b/docs/api-reference/typescript/payments-and-balance.md
@@ -0,0 +1,330 @@
+---
+title: "Payments & Balance"
+description: "Purchase payment plans and manage credit balances for accessing AI agents"
+icon: "wallet"
+---
+
+# Payments and Balance
+
+This guide explains how subscribers purchase payment plans and check their credit balances. These operations are typically performed by users who want to access AI agents.
+
+## Overview
+
+The payment flow consists of:
+1. **Discovering Plans**: Browse available payment plans for agents
+2. **Ordering Plans**: Purchase a plan to receive credits
+3. **Checking Balance**: Monitor available credits and subscription status
+
+## Get Plan Balance
+
+Subscribers can check their available credits for a specific plan:
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+// Initialize with subscriber's API key
+const subscriberPayments = Payments.getInstance({
+  nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Get balance for a plan
+const balance = await subscriberPayments.plans.getPlanBalance(planId)
+
+console.log(`Available credits: ${balance.balance}`)
+console.log(`Is owner: ${balance.isOwner}`)
+console.log(`Is subscriber: ${balance.isSubscriber}`)
+```
+
+### Balance Response Structure
+
+The balance response contains:
+
+```typescript
+interface PlanBalance {
+  balance: string        // Available credits as string
+  isOwner: boolean      // True if you're the plan creator
+  isSubscriber: boolean // True if you have an active subscription
+}
+```
+
+### Working with Balance
+
+```typescript
+// Get balance
+const balance = await subscriberPayments.plans.getPlanBalance(planId)
+
+// Convert to BigInt for calculations
+const creditsAvailable = BigInt(balance.balance)
+
+// Check if sufficient credits
+const creditsNeeded = 10n
+if (creditsAvailable >= creditsNeeded) {
+  console.log('Sufficient credits available')
+} else {
+  console.log(`Need ${creditsNeeded - creditsAvailable} more credits`)
+}
+```
+
+## Order a Plan
+
+Subscribers purchase plans to receive credits:
+
+### Crypto Payment
+
+For plans priced in cryptocurrency:
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+const subscriberPayments = Payments.getInstance({
+  nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Order the plan
+const orderResult = await subscriberPayments.plans.orderPlan(planId)
+
+if (orderResult.success) {
+  console.log('Plan ordered successfully!')
+  console.log(`Transaction: ${orderResult.transaction}`)
+} else {
+  console.error('Failed to order plan')
+}
+```
+
+### Fiat Payment (Stripe)
+
+For plans priced in fiat currency, use `orderFiatPlan` to get a Stripe checkout URL:
+
+```typescript
+const fiatResult = await subscriberPayments.plans.orderFiatPlan(planId)
+
+if (fiatResult.checkoutUrl) {
+  console.log(`Complete payment at: ${fiatResult.checkoutUrl}`)
+  // Redirect the user to the Stripe checkout page
+}
+```
+
+#### CLI
+
+```bash
+# Order a fiat plan (returns a Stripe checkout URL)
+nevermined plans order-fiat-plan <plan-id>
+```
+
+> **Note**: When using X402 card-delegation tokens (`nvm:card-delegation` scheme), the payment is handled automatically through the delegated card — no separate checkout URL is needed. See [Querying an Agent](./querying-an-agent) for details on card-delegation tokens.
+
+### Complete Purchase Flow
+
+```typescript
+async function purchaseAndVerify(planId: string) {
+  const subscriberPayments = Payments.getInstance({
+    nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+    environment: 'sandbox',
+  })
+
+  // Check current balance
+  const beforeBalance = await subscriberPayments.plans.getPlanBalance(planId)
+  console.log(`Balance before: ${beforeBalance.balance} credits`)
+
+  // Order the plan
+  const orderResult = await subscriberPayments.plans.orderPlan(planId)
+
+  if (!orderResult.success) {
+    throw new Error('Failed to order plan')
+  }
+
+  console.log('Plan ordered successfully')
+
+  // Wait for credits to be allocated (blockchain settlement)
+  await new Promise(resolve => setTimeout(resolve, 5000))
+
+  // Check new balance
+  const afterBalance = await subscriberPayments.plans.getPlanBalance(planId)
+  console.log(`Balance after: ${afterBalance.balance} credits`)
+}
+```
+
+## Waiting for Balance Updates
+
+After ordering a plan, credits are allocated on-chain, which may take a few seconds:
+
+```typescript
+async function waitForCredits(
+  payments: Payments,
+  planId: string,
+  timeoutMs: number = 60000
+): Promise<bigint> {
+  const startTime = Date.now()
+  const checkInterval = 2000 // Check every 2 seconds
+
+  while (Date.now() - startTime < timeoutMs) {
+    const balance = await payments.plans.getPlanBalance(planId)
+    const credits = BigInt(balance.balance)
+
+    if (credits > 0n) {
+      return credits
+    }
+
+    await new Promise(resolve => setTimeout(resolve, checkInterval))
+  }
+
+  throw new Error('Timeout waiting for credits')
+}
+
+// Usage
+const credits = await waitForCredits(subscriberPayments, planId)
+console.log(`Received ${credits} credits`)
+```
+
+## Check Multiple Plan Balances
+
+If a subscriber has multiple plans:
+
+```typescript
+async function checkAllBalances(planIds: string[]) {
+  const subscriberPayments = Payments.getInstance({
+    nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+    environment: 'sandbox',
+  })
+
+  for (const planId of planIds) {
+    const balance = await subscriberPayments.plans.getPlanBalance(planId)
+    console.log(`Plan ${planId}: ${balance.balance} credits`)
+  }
+}
+
+await checkAllBalances([planId1, planId2, planId3])
+```
+
+## Stripe Checkout Integration
+
+Stripe checkout for fiat-priced plans is managed through the Nevermined App dashboard.
+Visit [nevermined.app](https://nevermined.app) to configure Stripe payments for your plans.
+
+## Plan Information
+
+Before ordering, subscribers might want to view plan details:
+
+```typescript
+// Get plan details
+const plan = await subscriberPayments.plans.getPlan(planId)
+
+console.log(`Plan: ${plan.name}`)
+console.log(`Description: ${plan.description}`)
+console.log(`Price: ${plan.price}`)
+console.log(`Credits: ${plan.credits}`)
+
+// Check if already subscribed
+const balance = await subscriberPayments.plans.getPlanBalance(planId)
+
+if (balance.isSubscriber && BigInt(balance.balance) > 0n) {
+  console.log('Already subscribed with available credits')
+} else {
+  console.log('Need to order plan')
+}
+```
+
+## Complete Example: Purchase Flow with UI
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+class PlanPurchaseManager {
+  private payments: Payments
+
+  constructor(apiKey: string, environment: EnvironmentName) {
+    this.payments = Payments.getInstance({
+      nvmApiKey: apiKey,
+      environment,
+    })
+  }
+
+  async checkBalance(planId: string): Promise<bigint> {
+    const balance = await this.payments.plans.getPlanBalance(planId)
+    return BigInt(balance.balance)
+  }
+
+  async purchasePlan(planId: string): Promise<boolean> {
+    try {
+      // Get plan details
+      const plan = await this.payments.plans.getPlan(planId)
+      console.log(`Purchasing: ${plan.name}`)
+
+      // Check if already subscribed
+      const currentBalance = await this.checkBalance(planId)
+      if (currentBalance > 0n) {
+        console.log(`Already have ${currentBalance} credits`)
+        return true
+      }
+
+      // Order the plan
+      const orderResult = await this.payments.plans.orderPlan(planId)
+
+      if (!orderResult.success) {
+        throw new Error('Order failed')
+      }
+
+      console.log(`Order successful: ${orderResult.transaction}`)
+
+      // Wait for credits
+      const credits = await this.waitForCredits(planId)
+      console.log(`Received ${credits} credits`)
+
+      return true
+    } catch (error) {
+      console.error('Purchase failed:', error)
+      return false
+    }
+  }
+
+  private async waitForCredits(
+    planId: string,
+    timeoutMs: number = 60000
+  ): Promise<bigint> {
+    const startTime = Date.now()
+    const checkInterval = 2000
+
+    while (Date.now() - startTime < timeoutMs) {
+      const credits = await this.checkBalance(planId)
+      if (credits > 0n) return credits
+      await new Promise(resolve => setTimeout(resolve, checkInterval))
+    }
+
+    throw new Error('Timeout waiting for credits')
+  }
+}
+
+// Usage
+const manager = new PlanPurchaseManager(
+  process.env.SUBSCRIBER_API_KEY!,
+  'sandbox'
+)
+
+const success = await manager.purchasePlan(planId)
+if (success) {
+  const balance = await manager.checkBalance(planId)
+  console.log(`Ready to use agent with ${balance} credits`)
+}
+```
+
+## Best Practices
+
+1. **Check Balance First**: Always check existing balance before ordering
+2. **Wait for Settlement**: Allow time for on-chain credit allocation after purchase
+3. **Handle Errors**: Wrap order operations in try-catch blocks
+4. **User Feedback**: Provide clear feedback during the purchase process
+5. **Balance Monitoring**: Check balance before each agent request
+6. **Stripe Redirects**: Use absolute URLs for Stripe success/cancel URLs
+
+## Related Documentation
+
+- [Payment Plans](./payment-plans) - Understanding plan types and pricing
+- [Querying an Agent](./querying-an-agent) - Using credits to access agents
+
+---
+
+**Source References**:
+- `src/api/plans-api.ts` (orderPlan, getPlanBalance methods)
+- `tests/e2e/test_payments_e2e.test.ts` (ordering and balance verification)
diff --git a/docs/api-reference/typescript/publishing-static-resources.md b/docs/api-reference/typescript/publishing-static-resources.md
new file mode 100644
index 00000000..ca637923
--- /dev/null
+++ b/docs/api-reference/typescript/publishing-static-resources.md
@@ -0,0 +1,311 @@
+---
+title: "Static Resources"
+description: "Monetize access to static content like files, datasets, and documents with payment protection"
+icon: "folder-open"
+---
+
+# Publishing Static Resources
+
+In addition to AI agents, you can register static resources (files, datasets, documents) as payment-protected content. This allows you to monetize access to files, datasets, models, or any static content through the Nevermined protocol.
+
+## Overview of Static Resources
+
+Static resource agents are specialized agent registrations that provide access to files and documents instead of interactive AI services. They work identically to regular agents but are optimized for static content delivery.
+
+**Use Cases**:
+- Premium datasets (CSV, JSON, Parquet files)
+- Trained ML models (PyTorch, TensorFlow checkpoints)
+- Documents and reports (PDF, DOCX)
+- Media files (images, audio, video)
+- Configuration files and templates
+- API specifications and documentation
+
+## Register Static Resource Agents
+
+Static resources are registered using the same Agents API, but with HTTP GET endpoints pointing to your content URLs:
+
+```typescript
+import { Payments, AgentMetadata, AgentAPIAttributes } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox',
+})
+
+// Define static resource metadata
+const resourceMetadata: AgentMetadata = {
+  name: 'Premium Weather Datasets',
+  description: 'Historical weather data for the past 10 years',
+  tags: ['dataset', 'weather', 'csv', 'historical'],
+}
+
+// Configure file endpoints
+const resourceApi: AgentAPIAttributes = {
+  endpoints: [
+    { GET: 'https://storage.example.com/weather/monthly-data-2024.csv' },
+    { GET: 'https://storage.example.com/weather/monthly-data-2023.csv' },
+  ],
+  authType: 'bearer',  // Require X402 access token
+}
+
+// Register as agent
+const { agentId } = await payments.agents.registerAgent(
+  resourceMetadata,
+  resourceApi,
+  [planId]
+)
+
+console.log(`Static resource agent registered: ${agentId}`)
+```
+
+## Using Wildcards for Multiple Files
+
+You can use wildcards to grant access to multiple files with a single endpoint pattern:
+
+### Single Wildcard
+
+```typescript
+const resourceApi: AgentAPIAttributes = {
+  endpoints: [
+    { GET: 'https://storage.example.com/datasets/:dataset/*' },
+  ],
+  authType: 'bearer',
+}
+```
+
+This pattern allows access to:
+- `https://storage.example.com/datasets/weather/2024-data.csv`
+- `https://storage.example.com/datasets/weather/hourly-readings.json`
+- `https://storage.example.com/datasets/climate/temperature-records.csv`
+
+### Multiple Wildcards
+
+```typescript
+const resourceApi: AgentAPIAttributes = {
+  endpoints: [
+    { GET: 'https://storage.example.com/datasets/:category/:year/*' },
+  ],
+  authType: 'bearer',
+}
+```
+
+This pattern allows access to:
+- `https://storage.example.com/datasets/weather/2024/january.csv`
+- `https://storage.example.com/datasets/climate/2023/summer.json`
+
+### File Type Wildcards
+
+```typescript
+const resourceApi: AgentAPIAttributes = {
+  endpoints: [
+    { GET: 'https://storage.example.com/models/:model/*.pt' },      // PyTorch models
+    { GET: 'https://storage.example.com/models/:model/*.safetensors' }, // Safetensors
+    { GET: 'https://storage.example.com/datasets/:name/*.csv' },    // CSV files
+  ],
+  authType: 'bearer',
+}
+```
+
+## Examples
+
+### Example 1: Dataset Collection
+
+```typescript
+import { Payments, AgentMetadata, AgentAPIAttributes } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox',
+})
+
+const datasetMetadata: AgentMetadata = {
+  name: 'ML Training Datasets',
+  description: 'Curated datasets for machine learning training',
+  tags: ['dataset', 'ml', 'training', 'csv', 'json'],
+}
+
+const datasetApi: AgentAPIAttributes = {
+  endpoints: [
+    { GET: 'https://cdn.example.com/datasets/:category/:filename' },
+  ],
+  openEndpoints: [
+    'https://cdn.example.com/datasets/samples/preview.json',  // Free preview
+  ],
+  authType: 'bearer',
+}
+
+const { agentId } = await payments.agents.registerAgent(
+  datasetMetadata,
+  datasetApi,
+  [planId]
+)
+
+console.log(`Dataset collection registered: ${agentId}`)
+```
+
+### Example 2: Model Repository
+
+```typescript
+const modelMetadata: AgentMetadata = {
+  name: 'Fine-tuned Language Models',
+  description: 'Pre-trained and fine-tuned models for NLP tasks',
+  tags: ['model', 'nlp', 'pytorch', 'transformers'],
+}
+
+const modelApi: AgentAPIAttributes = {
+  endpoints: [
+    { GET: 'https://models.example.com/nlp/:model-name/*.pt' },
+    { GET: 'https://models.example.com/nlp/:model-name/*.safetensors' },
+    { GET: 'https://models.example.com/nlp/:model-name/config.json' },
+  ],
+  authType: 'bearer',
+}
+
+const { agentId } = await payments.agents.registerAgent(
+  modelMetadata,
+  modelApi,
+  [premiumPlanId]
+)
+```
+
+### Example 3: Document Library
+
+```typescript
+const documentMetadata: AgentMetadata = {
+  name: 'Research Reports & Whitepapers',
+  description: 'Premium industry research and technical whitepapers',
+  tags: ['documents', 'research', 'reports', 'pdf'],
+}
+
+const documentApi: AgentAPIAttributes = {
+  endpoints: [
+    { GET: 'https://docs.example.com/reports/:year/:category/*.pdf' },
+    { GET: 'https://docs.example.com/whitepapers/:topic/*.pdf' },
+  ],
+  openEndpoints: [
+    'https://docs.example.com/samples/index.html',  // Catalog
+  ],
+  authType: 'bearer',
+}
+
+const { agentId } = await payments.agents.registerAgent(
+  documentMetadata,
+  documentApi,
+  [basicPlanId, proPlanId]
+)
+```
+
+### Example 4: Directory-Level Access
+
+```typescript
+const directoryMetadata: AgentMetadata = {
+  name: 'Premium Asset Library',
+  description: 'Complete directory access to all assets',
+  tags: ['assets', 'media', 'images', 'videos'],
+}
+
+const directoryApi: AgentAPIAttributes = {
+  endpoints: [
+    { GET: 'https://assets.example.com/premium/*' },  // Everything under /premium/
+  ],
+  authType: 'bearer',
+}
+
+const { agentId } = await payments.agents.registerAgent(
+  directoryMetadata,
+  directoryApi,
+  [unlimitedPlanId]
+)
+```
+
+## MCP Logical URIs for Static Resources
+
+When registering static resource agents in the Nevermined App, you can also use MCP logical URIs with wildcards:
+
+```
+mcp://storage-server/resources/weather://2024/*
+mcp://model-server/resources/models://:model-name/*
+mcp://docs-server/resources/reports://:category/*
+```
+
+## Access Control
+
+Static resources use the same X402 access token authentication as AI agents:
+
+1. Subscribers order a plan and receive credits
+2. Subscribers generate an X402 access token
+3. Requests to static resources include the token in the `payment-signature` header
+4. Your server verifies the token and grants access
+5. Credits are burned based on your plan configuration
+
+See [Validation of Requests](./validation-of-requests) for implementation details.
+
+## Best Practices
+
+1. **Organized Structure**: Use clear URL patterns with logical path segments
+2. **Wildcard Strategy**: Balance flexibility (broad wildcards) with security (specific patterns)
+3. **File Types**: Specify file extensions in patterns when possible (e.g., `*.csv`, `*.pdf`)
+4. **Preview Access**: Consider providing free samples via `openEndpoints`
+5. **Metadata Tags**: Include file types and categories in tags for discoverability
+6. **Plan Configuration**: Set appropriate credits per download based on file size/value
+
+## Complete Example: Multi-Format Resource Library
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+import { AgentMetadata, AgentAPIAttributes } from '@nevermined-io/payments'
+
+const payments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+const resourceMetadata: AgentMetadata = {
+  name: 'Data Science Resource Library',
+  description: 'Comprehensive collection of datasets, models, and notebooks',
+  tags: ['dataset', 'model', 'notebook', 'ml', 'ai'],
+}
+
+const resourceApi: AgentAPIAttributes = {
+  endpoints: [
+    // Datasets
+    { GET: 'https://cdn.example.com/datasets/:category/:name.csv' },
+    { GET: 'https://cdn.example.com/datasets/:category/:name.json' },
+    { GET: 'https://cdn.example.com/datasets/:category/:name.parquet' },
+
+    // Models
+    { GET: 'https://cdn.example.com/models/:framework/:name/*' },
+
+    // Notebooks
+    { GET: 'https://cdn.example.com/notebooks/:topic/*.ipynb' },
+
+    // Documentation
+    { GET: 'https://cdn.example.com/docs/:section/*.pdf' },
+  ],
+  openEndpoints: [
+    'https://cdn.example.com/catalog.json',
+    'https://cdn.example.com/samples/preview-dataset.csv',
+  ],
+  authType: 'bearer',
+}
+
+const { agentId } = await payments.agents.registerAgent(
+  resourceMetadata,
+  resourceApi,
+  [basicPlanId, proPlanId, enterprisePlanId]
+)
+
+console.log(`Multi-format resource library registered: ${agentId}`)
+```
+
+## Related Documentation
+
+- [Agents](./agents) - Agent registration fundamentals
+- [Payment Plans](./payment-plans) - Configure pricing for resource access
+- [Validation of Requests](./validation-of-requests) - Verify access tokens for downloads
+
+---
+
+**Source References**:
+- `src/api/agents-api.ts` (Agents API for static resources)
+- `RUN.md` (MCP logical URIs with wildcards)
diff --git a/docs/api-reference/typescript/querying-an-agent.md b/docs/api-reference/typescript/querying-an-agent.md
new file mode 100644
index 00000000..dfa5ea5a
--- /dev/null
+++ b/docs/api-reference/typescript/querying-an-agent.md
@@ -0,0 +1,447 @@
+---
+title: "Querying Agents"
+description: "Generate X402 access tokens and make authenticated requests to AI agents"
+icon: "message"
+---
+
+# Querying an Agent
+
+After purchasing a payment plan, subscribers can generate X402 access tokens and use them to query AI agents. This guide explains how to get tokens and make authenticated requests.
+
+> 🔐 **Treat access tokens like API keys.** The `accessToken` returned by `getX402AccessToken()` is a bearer credential that authorises spending against your plan. Send it only over HTTPS, never log its full value, and scrub the `payment-signature` header from any pino/winston/OpenTelemetry exporter. Use a redaction helper such as ``redactToken(t) => `${t.slice(0,6)}…${t.slice(-4)}` `` if you need diagnostic output.
+
+## Overview
+
+The query flow consists of:
+1. **Generate X402 Access Token**: Get a payment-authorized token for agent access
+2. **Make Authenticated Requests**: Include the token in HTTP headers
+3. **Receive Responses**: Agent validates the token and processes the request
+
+## Get X402 Access Token
+
+The X402 access token is a cryptographically signed credential that proves you have purchased access to an agent:
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+// Initialize with subscriber's API key
+const subscriberPayments = Payments.getInstance({
+  nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Generate access token
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+  planId,   // Required: The plan you purchased
+  agentId   // Optional: Specific agent ID to restrict access
+)
+
+console.log('Access token generated')
+```
+
+### Token Parameters
+
+The `getX402AccessToken` method takes the plan id plus two optional arguments:
+
+```typescript
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+  planId,
+  agentId,       // Optional: restrict the token to a specific agent
+  tokenOptions,  // Optional: X402TokenOptions (scheme, network, delegationConfig)
+)
+```
+
+Both schemes require `tokenOptions.delegationConfig` — pass
+`{ delegationId }` for a delegation created via
+[`createDelegation`](#card-delegation-tokens-fiat).
+
+### Card-Delegation Tokens (Fiat)
+
+For plans that accept fiat payments, use the `nvm:card-delegation` scheme.
+Create the delegation once with `createDelegation` (passing the enrolled card's
+`providerPaymentMethodId` and the required `currency`), then request tokens by
+its `delegationId`:
+
+```typescript
+import { Payments, EnvironmentName, X402TokenOptions } from '@nevermined-io/payments'
+
+const subscriberPayments = Payments.getInstance({
+  nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// 1. List enrolled payment methods and create a delegation once.
+const methods = await subscriberPayments.delegation.listPaymentMethods()
+console.log(`Found ${methods.length} enrolled card(s)`)
+
+const { delegationId } = await subscriberPayments.delegation.createDelegation({
+  provider: methods[0].provider ?? 'stripe',
+  providerPaymentMethodId: methods[0].id, // or a specific 'pm_...' ID
+  spendingLimitCents: 1000, // max $10.00
+  durationSecs: 3600, // 1 hour delegation
+  currency: 'usd',
+})
+
+// 2. Request a token by delegationId (reuse it for subsequent requests).
+const tokenOptions: X402TokenOptions = {
+  scheme: 'nvm:card-delegation',
+  delegationConfig: { delegationId },
+}
+
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+  planId,
+  agentId,
+  tokenOptions,
+)
+```
+
+#### Auto-Detecting the Scheme
+
+If you don't know whether a plan uses crypto or fiat, use `resolveScheme()` to auto-detect from plan metadata:
+
+```typescript
+import { Payments, resolveScheme } from '@nevermined-io/payments'
+
+const scheme = await resolveScheme(subscriberPayments, planId)
+
+let tokenOptions: X402TokenOptions | undefined
+if (scheme === 'nvm:card-delegation') {
+  const methods = await subscriberPayments.delegation.listPaymentMethods()
+  const { delegationId } = await subscriberPayments.delegation.createDelegation({
+    provider: methods[0].provider ?? 'stripe',
+    providerPaymentMethodId: methods[0].id,
+    spendingLimitCents: 1000,
+    durationSecs: 3600,
+    currency: 'usd',
+  })
+  tokenOptions = {
+    scheme: 'nvm:card-delegation',
+    delegationConfig: { delegationId },
+  }
+}
+
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+  planId, agentId, tokenOptions,
+)
+```
+
+#### CLI
+
+> ⚠️ Inline create-on-the-fly is deprecated (nevermined-io/nvm-monorepo#1674) — the `--payment-type fiat` / `--payment-method-id` / `--spending-limit-cents` / `--delegation-duration-secs` flags create a delegation on the fly. Prefer creating a delegation first, then requesting the token by its `delegationId`.
+
+```bash
+# Crypto (default)
+nevermined x402token get-x402-access-token <planId>
+
+# Fiat with auto-selected card
+nevermined x402token get-x402-access-token <planId> --payment-type fiat
+
+# Fiat with specific card and limits
+nevermined x402token get-x402-access-token <planId> --payment-type fiat \
+    --payment-method-id pm_1AbCdEfGhIjKlM \
+    --spending-limit-cents 5000 \
+    --delegation-duration-secs 7200
+
+# Auto-detect scheme from plan metadata
+nevermined x402token get-x402-access-token <planId> --auto-resolve-scheme
+
+# List enrolled payment methods
+nevermined delegation list-payment-methods
+```
+
+### Basic Example
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+const subscriberPayments = Payments.getInstance({
+  nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Simple token generation
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+  planId,
+  agentId
+)
+
+// ⚠️ Never log the full token — it is a bearer credential.
+console.log('Access token generated')
+```
+
+## Token Structure (X402 v2)
+
+The access token is a JSON Web Token (JWT) containing an X402 v2 payment credential:
+
+```json
+{
+  "x402Version": 2,
+  "accepted": {
+    "scheme": "nvm:erc4337",
+    "network": "eip155:84532",
+    "planId": "plan-123",
+    "extra": {
+      "version": "1",
+      "agentId": "did:nv:agent-456"
+    }
+  },
+  "payload": {
+    "signature": "0x...",
+    "authorization": {
+      "from": "0xSubscriberAddress",
+      "sessionKeysProvider": "zerodev",
+      "sessionKeys": []
+    }
+  },
+  "extensions": {}
+}
+```
+
+## Make Requests with X402 Token
+
+### Using payment-signature Header (X402 v2 Spec)
+
+The X402 v2 specification defines the `payment-signature` header for payment credentials:
+
+```typescript
+// Make authenticated request to agent
+const response = await fetch('https://agent.example.com/api/v1/tasks', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'payment-signature': accessToken,  // X402 v2 standard header
+  },
+  body: JSON.stringify({
+    prompt: 'What is the weather in San Francisco?',
+  }),
+})
+
+const result = await response.json()
+console.log(result)
+```
+
+**Note**: The A2A (Agent-to-Agent) protocol also uses the `payment-signature` header for authentication. For A2A integration details, see the [A2A Integration](./a2a-integration) guide.
+
+## Complete Query Example
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+async function queryAgent(
+  planId: string,
+  agentId: string,
+  agentUrl: string,
+  prompt: string
+) {
+  // Initialize subscriber payments
+  const subscriberPayments = Payments.getInstance({
+    nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+    environment: 'sandbox' as EnvironmentName,
+  })
+
+  try {
+    // 1. Generate access token
+    const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+      planId,
+      agentId
+    )
+    console.log('✓ Access token generated')
+
+    // 2. Make authenticated request
+    const response = await fetch(`${agentUrl}/tasks`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'payment-signature': accessToken,
+      },
+      body: JSON.stringify({ prompt }),
+    })
+
+    // 3. Handle response
+    if (!response.ok) {
+      if (response.status === 402) {
+        console.error('Payment required - insufficient credits')
+      } else {
+        console.error(`Request failed: ${response.statusText}`)
+      }
+      return null
+    }
+
+    const result = await response.json()
+    console.log('✓ Agent response received')
+    return result
+
+  } catch (error) {
+    console.error('Failed to query agent:', error)
+    return null
+  }
+}
+
+// Usage
+const result = await queryAgent(
+  'plan-123',
+  'did:nv:agent-456',
+  'https://weather-agent.example.com/api/v1',
+  'What is the weather forecast for tomorrow?'
+)
+```
+
+## Handling 402 Payment Required
+
+If the token is invalid or credits are insufficient, agents return HTTP 402 with payment details:
+
+```typescript
+const response = await fetch(agentUrl, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'payment-signature': accessToken,
+  },
+  body: JSON.stringify({ prompt }),
+})
+
+if (response.status === 402) {
+  // Read PAYMENT-REQUIRED header
+  const paymentRequiredHeader = response.headers.get('PAYMENT-REQUIRED')
+
+  if (paymentRequiredHeader) {
+    // Decode base64 payment required info
+    const paymentRequired = JSON.parse(
+      Buffer.from(paymentRequiredHeader, 'base64').toString()
+    )
+
+    console.log('Payment required:', paymentRequired)
+    console.log(`Plan ID: ${paymentRequired.accepts[0].planId}`)
+
+    // User needs to purchase plan or top up credits
+  }
+}
+```
+
+## MCP JSON-RPC Requests
+
+For MCP-based agents, use JSON-RPC format:
+
+```typescript
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+  planId,
+  agentId
+)
+
+const response = await fetch('https://mcp-agent.example.com/mcp', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'payment-signature': accessToken,
+  },
+  body: JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/call',
+    params: {
+      name: 'get_weather',
+      arguments: {
+        city: 'San Francisco'
+      }
+    }
+  }),
+})
+
+const result = await response.json()
+console.log(result.result)
+```
+
+## Token Reuse
+
+X402 access tokens can be reused for multiple requests until they expire or credits are exhausted:
+
+```typescript
+// Generate token once
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+  planId,
+  agentId
+)
+
+// Use for multiple requests
+for (const city of ['San Francisco', 'New York', 'London']) {
+  const response = await fetch(agentUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'payment-signature': accessToken,  // Reuse same token
+    },
+    body: JSON.stringify({ prompt: `Weather in ${city}` }),
+  })
+
+  const result = await response.json()
+  console.log(`${city}:`, result)
+}
+```
+
+## Check Balance Before Querying
+
+To avoid 402 errors, check your balance before making requests:
+
+```typescript
+async function queryWithBalanceCheck(
+  planId: string,
+  agentId: string,
+  agentUrl: string,
+  prompt: string
+) {
+  const subscriberPayments = Payments.getInstance({
+    nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+    environment: 'sandbox',
+  })
+
+  // Check balance first
+  const balance = await subscriberPayments.plans.getPlanBalance(planId)
+  const availableCredits = BigInt(balance.balance)
+
+  if (availableCredits === 0n) {
+    console.error('No credits available - please purchase a plan')
+    return null
+  }
+
+  console.log(`Available credits: ${availableCredits}`)
+
+  // Generate token and query
+  const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+    planId,
+    agentId
+  )
+
+  const response = await fetch(agentUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'payment-signature': accessToken,
+    },
+    body: JSON.stringify({ prompt }),
+  })
+
+  return await response.json()
+}
+```
+
+## Best Practices
+
+1. **Token Caching**: Generate tokens once and reuse them for multiple requests
+2. **Balance Checking**: Check balance before generating tokens
+3. **Error Handling**: Always handle 402 Payment Required responses
+4. **HTTPS Only**: Never send tokens over unencrypted HTTP
+5. **Token Expiration**: Regenerate tokens if you receive 402 errors
+6. **Header Standard**: Prefer `payment-signature` header (X402 v2 spec)
+
+## Related Documentation
+
+- [Payments and Balance](./payments-and-balance) - How to purchase plans and check credits
+- [Validation of Requests](./validation-of-requests) - How agents validate tokens (for builders)
+- [X402 Protocol](./x402) - Complete X402 specification
+
+---
+
+**Source References**:
+- `src/x402/token.ts` (getX402AccessToken method)
+- `tests/e2e/test_x402_e2e.test.ts` (lines 114-133, token generation)
+- `tests/e2e/test_payments_e2e.test.ts` (MockAgentServer, lines 72-127)
diff --git a/docs/api-reference/typescript/validation-of-requests.md b/docs/api-reference/typescript/validation-of-requests.md
new file mode 100644
index 00000000..b6bf6119
--- /dev/null
+++ b/docs/api-reference/typescript/validation-of-requests.md
@@ -0,0 +1,410 @@
+---
+title: "Request Validation"
+description: "Verify X402 access tokens and settle payments when subscribers access your agents"
+icon: "shield-check"
+---
+
+# Validation of Requests
+
+This guide explains how AI agents validate incoming requests and settle payments using the Nevermined Facilitator. Agent builders use these methods to verify subscriber access and burn credits.
+
+> 🔐 **Never log incoming tokens.** When you extract the `payment-signature` header, treat it as a bearer secret: do not echo it in error messages, debug output, or telemetry. Configure your log/trace exporters to redact `payment-signature`, `authorization`, and `cookie` headers by default.
+
+## Overview
+
+The validation flow consists of:
+1. **Extract Token**: Read X402 access token from request headers
+2. **Build Payment Required**: Create payment requirement specification
+3. **Verify Permissions**: Check if subscriber has valid access
+4. **Execute Task**: Process the agent request
+5. **Settle Permissions**: Burn credits after successful execution
+6. **Return Response**: Send result or 402 error to subscriber
+
+## Receiving Requests
+
+Extract the X402 access token from request headers. The X402 v2 spec defines the `payment-signature` header:
+
+```typescript
+import express from 'express'
+
+const app = express()
+app.use(express.json())
+
+app.post('/api/v1/tasks', async (req, res) => {
+  // Extract token from payment-signature header (X402 v2)
+  const accessToken = req.headers['payment-signature'] as string
+
+  // Alternative: Authorization header
+  // const accessToken = req.headers.authorization?.replace('Bearer ', '')
+
+  if (!accessToken) {
+    return res.status(402).json({ error: 'Payment required' })
+  }
+
+  // Process request...
+})
+```
+
+## Build Payment Required
+
+Use the `buildPaymentRequired` helper to create the payment specification:
+
+```typescript
+import { buildPaymentRequired } from '@nevermined-io/payments'
+
+const paymentRequired = buildPaymentRequired(planId, {
+  endpoint: req.url,           // Resource URL
+  agentId: agentId,            // Your agent ID
+  httpVerb: req.method,        // HTTP method (POST, GET, etc.)
+  network: 'eip155:84532',     // Optional: blockchain network
+  description: 'Task API'      // Optional: description
+})
+```
+
+## Verify Permissions
+
+Before executing the request, verify the subscriber has valid access:
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+import { buildPaymentRequired } from '@nevermined-io/payments'
+
+const agentPayments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,  // Builder/agent API key
+  environment: 'sandbox' as EnvironmentName,
+})
+
+app.post('/api/v1/tasks', async (req, res) => {
+  const accessToken = req.headers['payment-signature'] as string
+
+  if (!accessToken) {
+    return res.status(402).json({ error: 'Payment required' })
+  }
+
+  // Build payment required
+  const paymentRequired = buildPaymentRequired(planId, {
+    endpoint: req.url,
+    agentId: agentId,
+    httpVerb: req.method,
+  })
+
+  try {
+    // Verify permissions
+    const verification = await agentPayments.facilitator.verifyPermissions({
+      paymentRequired,
+      x402AccessToken: accessToken,
+      maxAmount: 1n,  // Max credits to verify
+    })
+
+    if (!verification.isValid) {
+      return res.status(402).json({ error: 'Insufficient credits or invalid token' })
+    }
+
+    // Verification successful, proceed with request...
+
+  } catch (error) {
+    return res.status(500).json({ error: error.message })
+  }
+})
+```
+
+## Settle Permissions
+
+After successfully processing the request, burn the credits:
+
+```typescript
+app.post('/api/v1/tasks', async (req, res) => {
+  const accessToken = req.headers['payment-signature'] as string
+
+  if (!accessToken) {
+    return res.status(402).json({ error: 'Payment required' })
+  }
+
+  const paymentRequired = buildPaymentRequired(planId, {
+    endpoint: req.url,
+    agentId: agentId,
+    httpVerb: req.method,
+  })
+
+  try {
+    // Verify
+    const verification = await agentPayments.facilitator.verifyPermissions({
+      paymentRequired,
+      x402AccessToken: accessToken,
+      maxAmount: 1n,
+    })
+
+    if (!verification.isValid) {
+      return res.status(402).json({ error: 'Insufficient credits' })
+    }
+
+    // Execute task
+    const result = await processTask(req.body)
+
+    // Settle permissions (burn credits)
+    const settlement = await agentPayments.facilitator.settlePermissions({
+      paymentRequired,
+      x402AccessToken: accessToken,
+      maxAmount: 1n,  // Credits to burn
+    })
+
+    // Return success with payment metadata
+    return res.json({
+      result,
+      transaction: settlement.transaction,
+      creditsUsed: settlement.creditsRedeemed,
+      remainingBalance: settlement.remainingBalance,
+    })
+
+  } catch (error) {
+    return res.status(500).json({ error: error.message })
+  }
+})
+```
+
+## Return 402 Payment Required
+
+When payment is required, return HTTP 402 with the `PAYMENT-REQUIRED` header:
+
+```typescript
+import { buildPaymentRequired } from '@nevermined-io/payments'
+
+function return402Response(res: express.Response, planId: string, agentId: string, endpoint: string) {
+  const paymentRequired = buildPaymentRequired(planId, {
+    endpoint,
+    agentId,
+    httpVerb: 'POST',
+  })
+
+  // Encode payment required as base64
+  const paymentRequiredHeader = Buffer.from(
+    JSON.stringify(paymentRequired)
+  ).toString('base64')
+
+  res.writeHead(402, {
+    'Content-Type': 'application/json',
+    'PAYMENT-REQUIRED': paymentRequiredHeader,
+  })
+
+  res.end(JSON.stringify({
+    error: 'Payment required',
+    message: 'Valid X402 access token required in payment-signature header',
+  }))
+}
+
+// Usage
+app.post('/api/v1/tasks', async (req, res) => {
+  const accessToken = req.headers['payment-signature'] as string
+
+  if (!accessToken) {
+    return return402Response(res, planId, agentId, req.url)
+  }
+
+  // Verify and process...
+})
+```
+
+## Complete Validation Example
+
+```typescript
+import express from 'express'
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+import { buildPaymentRequired } from '@nevermined-io/payments'
+
+const app = express()
+app.use(express.json())
+
+const agentPayments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+const PLAN_ID = process.env.NVM_PLAN_ID!
+const AGENT_ID = process.env.NVM_AGENT_ID!
+
+app.post('/api/v1/tasks', async (req, res) => {
+  // 1. Extract token
+  const accessToken = req.headers['payment-signature'] as string
+
+  if (!accessToken) {
+    return return402Response(res, PLAN_ID, AGENT_ID, req.url)
+  }
+
+  // 2. Build payment required
+  const paymentRequired = buildPaymentRequired(PLAN_ID, {
+    endpoint: req.url,
+    agentId: AGENT_ID,
+    httpVerb: req.method,
+  })
+
+  try {
+    // 3. Verify permissions
+    const verification = await agentPayments.facilitator.verifyPermissions({
+      paymentRequired,
+      x402AccessToken: accessToken,
+      maxAmount: 1n,
+    })
+
+    if (!verification.isValid) {
+      console.log('Verification failed: insufficient credits or invalid token')
+      return return402Response(res, PLAN_ID, AGENT_ID, req.url)
+    }
+
+    console.log('✓ Permissions verified')
+
+    // 4. Execute task
+    const result = await processTask(req.body)
+
+    // 5. Settle permissions
+    const settlement = await agentPayments.facilitator.settlePermissions({
+      paymentRequired,
+      x402AccessToken: accessToken,
+      maxAmount: 1n,
+    })
+
+    console.log(`✓ Credits settled: ${settlement.creditsRedeemed}`)
+    console.log(`✓ Transaction: ${settlement.transaction}`)
+
+    // 6. Return response with payment metadata
+    const paymentResponse = {
+      success: settlement.success,
+      network: settlement.network,
+      transaction: settlement.transaction,
+      creditsRedeemed: settlement.creditsRedeemed,
+    }
+
+    res.writeHead(200, {
+      'Content-Type': 'application/json',
+      'PAYMENT-RESPONSE': Buffer.from(JSON.stringify(paymentResponse)).toString('base64'),
+    })
+
+    res.end(JSON.stringify({ result }))
+
+  } catch (error) {
+    console.error('Request processing failed:', error)
+    res.status(500).json({ error: error.message })
+  }
+})
+
+function return402Response(
+  res: express.Response,
+  planId: string,
+  agentId: string,
+  endpoint: string
+) {
+  const paymentRequired = buildPaymentRequired(planId, {
+    endpoint,
+    agentId,
+    httpVerb: 'POST',
+  })
+
+  const paymentRequiredHeader = Buffer.from(
+    JSON.stringify(paymentRequired)
+  ).toString('base64')
+
+  res.writeHead(402, {
+    'Content-Type': 'application/json',
+    'PAYMENT-REQUIRED': paymentRequiredHeader,
+  })
+
+  res.end(JSON.stringify({ error: 'Payment required' }))
+}
+
+async function processTask(body: any): Promise<any> {
+  // Your agent logic here
+  return { response: 'Task completed' }
+}
+
+app.listen(3000, () => {
+  console.log('Agent server running on port 3000')
+})
+```
+
+## Dynamic Credit Burning
+
+For agents with variable credit costs, calculate credits based on the request:
+
+```typescript
+async function calculateCredits(request: any, response: any): Promise<bigint> {
+  // Example: charge based on response length
+  const responseLength = JSON.stringify(response).length
+  return BigInt(Math.ceil(responseLength / 1000))  // 1 credit per KB
+}
+
+app.post('/api/v1/tasks', async (req, res) => {
+  const accessToken = req.headers['payment-signature'] as string
+  const paymentRequired = buildPaymentRequired(PLAN_ID, {
+    endpoint: req.url,
+    agentId: AGENT_ID,
+    httpVerb: req.method,
+  })
+
+  // Verify with max possible credits
+  const verification = await agentPayments.facilitator.verifyPermissions({
+    paymentRequired,
+    x402AccessToken: accessToken,
+    maxAmount: 10n,  // Max credits subscriber might need
+  })
+
+  if (!verification.isValid) {
+    return return402Response(res, PLAN_ID, AGENT_ID, req.url)
+  }
+
+  // Execute
+  const result = await processTask(req.body)
+
+  // Calculate actual credits used
+  const creditsUsed = await calculateCredits(req.body, result)
+
+  // Settle with actual amount
+  const settlement = await agentPayments.facilitator.settlePermissions({
+    paymentRequired,
+    x402AccessToken: accessToken,
+    maxAmount: creditsUsed,
+  })
+
+  return res.json({
+    result,
+    creditsUsed: settlement.creditsRedeemed,
+  })
+})
+```
+
+## Settle Options
+
+The `settlePermissions` method accepts additional options:
+
+```typescript
+const settlement = await agentPayments.facilitator.settlePermissions({
+  paymentRequired,
+  x402AccessToken: accessToken,
+  maxAmount: 5n,               // Credits to burn
+  batch: false,                // Batch settlement (optional)
+  marginPercent: 5,            // Add 5% margin to calculated cost (optional)
+  agentRequestId: 'req-123',   // Request ID from verification (optional)
+})
+```
+
+## Best Practices
+
+1. **Always Verify First**: Call `verifyPermissions` before executing tasks
+2. **Settle After Success**: Only burn credits after successful task completion
+3. **Handle Errors**: Wrap verification/settlement in try-catch blocks
+4. **Return 402 Properly**: Include `PAYMENT-REQUIRED` header with payment details
+5. **Log Transactions**: Record transaction hashes for audit trails
+6. **Dynamic Pricing**: Calculate credits based on actual resource usage
+7. **Token Validation**: Never skip verification even if token looks valid
+
+## Related Documentation
+
+- [Querying an Agent](./querying-an-agent) - How subscribers generate and use tokens
+- [X402 Protocol](./x402) - Complete X402 specification
+- [MCP Integration](./mcp-integration) - Automatic validation in MCP servers
+- [A2A Integration](./a2a-integration) - Automatic validation in A2A servers
+
+---
+
+**Source References**:
+- `src/x402/facilitator-api.ts` (buildPaymentRequired, verifyPermissions, settlePermissions)
+- `tests/e2e/test_payments_e2e.test.ts` (MockAgentServer class, complete validation flow)
+- `tests/e2e/test_x402_e2e.test.ts` (lines 135-150, verification examples)
diff --git a/docs/api-reference/typescript/x402.md b/docs/api-reference/typescript/x402.md
new file mode 100644
index 00000000..a8dfaf40
--- /dev/null
+++ b/docs/api-reference/typescript/x402.md
@@ -0,0 +1,819 @@
+---
+title: "X402 Protocol"
+description: "Understand the X402 payment protocol for HTTP-based AI agent authentication and authorization"
+icon: "file-contract"
+---
+
+# X402 Protocol
+
+The X402 protocol is a payment-aware HTTP extension that enables AI agents to require and verify payments for API access. This guide provides a complete overview of X402 implementation in the Nevermined Payments Library.
+
+> 🔐 **Bearer-token hygiene.** The `payment-signature` header is a bearer credential — anyone holding it can spend the associated plan's credits until it expires. Send it only over HTTPS, never log the full value, and configure your log/trace exporters (pino, winston, OpenTelemetry) to redact `payment-signature`, `authorization`, and `cookie` headers by default.
+
+## Overview of X402
+
+X402 is an HTTP-based protocol for payment-protected resources:
+- **402 Payment Required**: HTTP status code for payment requests
+- **payment-signature**: Header containing payment credentials (X402 v2)
+- **PAYMENT-REQUIRED**: Header with payment requirements in 402 responses
+- **PAYMENT-RESPONSE**: Header with payment settlement details in success responses
+- **Cryptographic Signatures**: ERC-4337 account abstraction for secure payments
+
+## Supported Schemes
+
+Nevermined supports two x402 payment schemes:
+
+| Scheme | Network | Use Case | Settlement |
+|--------|---------|----------|------------|
+| `nvm:erc4337` | `eip155:84532` | Crypto payments | ERC-4337 UserOps + session keys |
+| `nvm:card-delegation` | `stripe` \| `braintree` \| `visa` | Fiat/credit card | Provider charge + credit burn |
+
+The scheme is determined by the plan's pricing configuration. Plans with `isCrypto: false` use `nvm:card-delegation`; all others use `nvm:erc4337`. The SDK auto-detects the scheme via `resolveScheme()`. The `network` value within `nvm:card-delegation` is determined by which provider issued the delegation being consumed (`stripe`, `braintree`, or `visa`).
+
+### Visa support
+
+Visa delegations use the same `nvm:card-delegation` scheme and SDK surface as Stripe and Braintree, but two steps must happen in a **browser** before the SDK can consume them:
+
+1. **Card enrolment** — the cardholder enrols a Visa card through VGS Collect (PCI-compliant iframe) in the Nevermined webapp. The card is bound to a Visa Agentic Token via the VGS Credential Management Platform.
+2. **Delegation creation** — the cardholder approves a delegation via a WebAuthn/passkey (FIDO) device-binding ceremony embedded by Visa VTS. This produces a single-use `assuranceData` blob bound to the spending limit + duration + merchant context.
+
+Both steps require a real DOM and a user gesture, so the SDK cannot perform them programmatically. Once a Visa delegation exists, the SDK consumes it identically to Stripe/Braintree — see [Reusing Existing Delegations](#reusing-existing-delegations).
+
+## X402 Version 2 Specification
+
+The Nevermined Payments Library implements X402 v2, which uses:
+- `payment-signature` header for access tokens (replaces Authorization)
+- `PAYMENT-REQUIRED` header for payment requirements (replaces custom formats)
+- `PAYMENT-RESPONSE` header for settlement receipts
+- Structured payment credentials with cryptographic signatures
+
+## Generate X402 Access Tokens
+
+The supported flow is **create-first**: create a delegation once with
+`payments.delegation.createDelegation(...)`, then request access tokens by
+passing only its `delegationId`. **Both schemes (`nvm:erc4337` and
+`nvm:card-delegation`) require a `delegationConfig`** — the older
+"just pass planId + agentId" shape no longer mints a token and surfaces
+`BCK.X402.0030` ("Required token-generation input is missing or incomplete";
+the `details` field names the missing input) at the backend.
+
+```typescript
+import { Payments, EnvironmentName, X402TokenOptions } from '@nevermined-io/payments'
+
+const subscriberPayments = Payments.getInstance({
+  nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// 1. Create a delegation once. `currency` is required: 'usdc' for the
+//    crypto (erc4337) scheme, 'usd'/'eur'/… for card providers.
+const { delegationId } = await subscriberPayments.delegation.createDelegation({
+  provider: 'erc4337',
+  spendingLimitCents: 1000, // $10 cap
+  durationSecs: 86_400, // 1 day
+  currency: 'usdc',
+})
+
+// 2. Request a token by delegationId. Reuse this delegation for every
+//    subsequent token request until it expires or is exhausted.
+const tokenOptions: X402TokenOptions = {
+  scheme: 'nvm:erc4337',
+  delegationConfig: { delegationId },
+}
+
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+  planId, // Required: Plan ID
+  agentId, // Optional: Agent ID (restricts token to specific agent)
+  tokenOptions, // Required: scheme + delegationConfig
+)
+
+console.log('X402 access token generated')
+```
+
+> ⚠️ **Inline create-on-the-fly is deprecated.** Passing creation fields
+> (`spendingLimitCents`, `durationSecs`, `providerPaymentMethodId`, `cardId`,
+> `currency`, `merchantAccountId`, `maxTransactions`) directly in
+> `delegationConfig` instead of a `delegationId` still works, but
+> `getX402AccessToken` now emits a runtime deprecation warning. Create the
+> delegation first (above) and pass only `{ delegationId }`.
+
+### Generate Tokens via Nevermined App
+
+Users can also generate X402 access tokens through the Nevermined App:
+
+1. Visit [nevermined.app/permissions/agent-permissions](https://nevermined.app/permissions/agent-permissions)
+2. Select the plan you've purchased
+3. Configure token parameters (agent, expiration, limits)
+4. Generate and copy the X402 access token
+5. Use the token in API requests
+
+This provides a user-friendly interface for non-technical users to generate tokens without code.
+
+### Generate Card-Delegation Tokens
+
+For fiat plans using `nvm:card-delegation`, create the delegation first with
+`createDelegation` (passing the card's `providerPaymentMethodId`), then request
+tokens by its `delegationId`. `currency` is required on creation:
+
+```typescript
+import { X402TokenOptions } from '@nevermined-io/payments'
+
+// 1. Create a USD card delegation once.
+const { delegationId: usdDelegationId } =
+  await subscriberPayments.delegation.createDelegation({
+    provider: 'stripe',
+    providerPaymentMethodId: 'pm_1AbCdEfGhIjKlM',
+    spendingLimitCents: 10000, // $100.00
+    durationSecs: 2592000, // 30 days
+    currency: 'usd',
+    maxTransactions: 100,
+  })
+
+// 2. Request a token by delegationId (reuse for every subsequent request).
+const tokenOptions: X402TokenOptions = {
+  scheme: 'nvm:card-delegation',
+  delegationConfig: { delegationId: usdDelegationId },
+}
+
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+  planId,
+  agentId,
+  tokenOptions,
+)
+```
+
+A EUR delegation is the same call with `currency: 'eur'`. The delegation's
+currency is fixed at creation, so you create one delegation per currency and
+reuse each by its `delegationId`.
+
+### Reusing Existing Delegations
+
+Passing `delegationConfig: { delegationId }` is the supported pattern for every
+provider, and the **only** supported pattern for Visa delegations (which cannot
+be created from the SDK). Reuse one delegation across multiple agents that share
+a single spending budget:
+
+```typescript
+const tokenOptions: X402TokenOptions = {
+  scheme: 'nvm:card-delegation',
+  delegationConfig: {
+    delegationId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  }
+}
+
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
+  planId,
+  agentId,
+  tokenOptions,
+)
+```
+
+When `delegationId` is provided, the backend verifies that the delegation is active and that the requesting API key has access, then returns its existing token without creating a new delegation. The provider (`stripe`, `braintree`, or `visa`) is inferred from the delegation record on the server.
+
+To scope a token request to a specific NVM API key, add `apiKeyId` alongside
+`delegationId` — both fields stay active (non-deprecated):
+
+```typescript
+delegationConfig: { delegationId: '…', apiKeyId: 'key-uuid' }
+```
+
+### Deprecated: inline create-on-the-fly
+
+> ⚠️ **Deprecated.** Supplying creation fields directly in `delegationConfig`
+> instead of a `delegationId` (e.g. `providerPaymentMethodId` +
+> `spendingLimitCents`, a bare `cardId`, or an identifier-less "auto-select"
+> shape) still creates a delegation on the fly, but `getX402AccessToken` now
+> emits a runtime deprecation warning. Use the create-first pattern above
+> (`createDelegation` → `{ delegationId }`); inline creation will be removed in
+> a future major release.
+
+### CardDelegationConfig Reference
+
+| Field | Type | Status | Description |
+|-------|------|--------|-------------|
+| `delegationId` | `string` | Active | Existing delegation UUID to reuse — the supported path |
+| `apiKeyId` | `string` | Active | NVM API Key ID to scope the token request to |
+| `cardId` | `string` | Deprecated | Payment method UUID to target (inline create) |
+| `providerPaymentMethodId` | `string` | Deprecated | Stripe payment method ID (e.g., `pm_...`) (inline create) |
+| `spendingLimitCents` | `number` | Deprecated | Max spending in cents (inline create) |
+| `durationSecs` | `number` | Deprecated | Duration in seconds (inline create) |
+| `currency` | `string` | Deprecated | Currency code (inline create) |
+| `planId` | `string` | Deprecated | Plan ID to scope a new delegation to (inline create) |
+| `merchantAccountId` | `string` | Deprecated | Stripe Connect account ID (inline create) |
+| `maxTransactions` | `number` | Deprecated | Max transactions allowed (inline create) |
+
+The deprecated fields apply only to inline create-on-the-fly. Create the
+delegation with [`createDelegation`](#createdelegation) and pass only
+`delegationId` (optionally `apiKeyId`) here.
+
+### Auto Scheme Resolution
+
+Use `resolveScheme()` to auto-detect the correct scheme from plan metadata:
+
+```typescript
+import { resolveScheme } from '@nevermined-io/payments'
+
+// Auto-detect scheme from plan metadata (cached for 5 minutes)
+const scheme = await resolveScheme(payments, planId)
+// Returns "nvm:erc4337" for crypto plans, "nvm:card-delegation" for fiat plans
+
+// Explicit override
+const scheme = await resolveScheme(payments, planId, 'nvm:card-delegation')
+```
+
+### DelegationAPI
+
+Manage payment methods and delegations for card delegation:
+
+```typescript
+import { DelegationAPI, PaymentMethodSummary } from '@nevermined-io/payments'
+
+const delegationApi = DelegationAPI.getInstance(payments.options)
+
+// List enrolled payment methods (every provider)
+const methods: PaymentMethodSummary[] = await delegationApi.listPaymentMethods()
+
+// Restrict the result to a single provider with the optional `provider` filter
+const stripeMethods: PaymentMethodSummary[] = await delegationApi.listPaymentMethods({
+  provider: 'stripe',
+})
+
+for (const method of methods) {
+  console.log(`${method.brand} ****${method.last4} (expires ${method.expMonth}/${method.expYear})`)
+  if (method.allowedApiKeyIds) {
+    console.log(`  Restricted to API keys: ${method.allowedApiKeyIds.join(', ')}`)
+  }
+}
+```
+
+`listPaymentMethods` accepts an optional `ListOptions`:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `provider` | `DelegationProvider` (`'stripe' \| 'braintree' \| 'visa' \| 'erc4337'`) | Server-side filter that restricts the result to payment methods backed by this provider. Omit it (the default) to return methods from every provider. |
+| `accessible` | `boolean` | When `true`, return only methods accessible to the requesting API key. |
+
+#### Update Payment Method
+
+Restrict a card to specific NVM API Keys so only designated agents can use it:
+
+```typescript
+await delegationApi.updatePaymentMethod('pm-uuid-here', {
+  alias: 'Production Card',
+  allowedApiKeyIds: ['sk-agent-1', 'sk-agent-2'],  // Only these API keys can use this card
+})
+
+// Remove restrictions (any API key can use the card)
+await delegationApi.updatePaymentMethod('pm-uuid-here', {
+  allowedApiKeyIds: null,
+})
+```
+
+#### List Delegations
+
+Retrieve all delegations for the authenticated user:
+
+```typescript
+const { delegations, totalResults } = await delegationApi.listDelegations()
+
+console.log(`Total delegations: ${totalResults}`)
+for (const d of delegations) {
+  console.log(`${d.delegationId} - ${d.status} (${d.remainingBudgetCents} cents remaining)`)
+  if (d.apiKeyId) {
+    console.log(`  Restricted to API key: ${d.apiKeyId}`)
+  }
+}
+```
+
+#### createDelegation
+
+Create a delegation once, then reuse it across token requests by its
+`delegationId` (the create-first pattern). This is the supported way to
+provision spending authority for `nvm:erc4337` and `nvm:card-delegation` —
+prefer it over inline create-on-the-fly in `getX402AccessToken`.
+
+```typescript
+// Crypto (erc4337): currency must be 'usdc'.
+const { delegationId } = await delegationApi.createDelegation({
+  provider: 'erc4337',
+  spendingLimitCents: 100000, // $1000 cap
+  durationSecs: 604800, // 1 week
+  currency: 'usdc',
+})
+
+// Card (stripe / braintree): pass the enrolled card's providerPaymentMethodId.
+const { delegationId: cardDelegationId } = await delegationApi.createDelegation({
+  provider: 'stripe',
+  providerPaymentMethodId: 'pm_1AbCdEfGhIjKlM',
+  spendingLimitCents: 10000,
+  durationSecs: 2592000,
+  currency: 'usd',
+})
+```
+
+`CreateDelegationPayload` fields:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `provider` | `'stripe' \| 'braintree' \| 'visa' \| 'erc4337'` | Yes | Delegation provider |
+| `spendingLimitCents` | `number` | Yes | Maximum spending limit in cents |
+| `durationSecs` | `number` | Yes | Delegation lifetime in seconds |
+| `currency` | `DelegationCurrency` (`'usd' \| 'eur' \| 'usdc' \| 'eurc'`) | Yes | Currency code — `'usdc'`/`'eurc'` for erc4337, `'usd'`/`'eur'` for card providers. No silent default; the backend requires it. |
+| `providerPaymentMethodId` | `string` | Card only | Payment method ID (Stripe `pm_...`, Braintree vault token, Visa Agentic token id) |
+| `planId` | `string` | No | Optional and additive — delegations are plan-agnostic by default; supply `planId` to bind the delegation to a single plan. (Visa is always plan-specific and requires it.) |
+| `merchantAccountId` | `string` | No | Stripe Connect account ID or Braintree merchantId |
+| `maxTransactions` | `number` | No | Maximum number of transactions allowed |
+| `apiKeyId` | `string` | No | NVM API Key ID to scope the delegation to |
+
+> Visa delegations require a browser-side device-binding ceremony and cannot be
+> created from the SDK — see [Visa support](#visa-support). Create them in the
+> Nevermined webapp, then consume them here by `delegationId`.
+
+#### DelegationListResponse Fields
+
+`listDelegations()` resolves to a `DelegationListResponse` object:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `delegations` | `DelegationSummary[]` | Array of delegation records |
+| `totalResults` | `number` | Total number of delegations |
+| `page` | `number` | Current page number |
+| `offset` | `number` | Offset into the full result set |
+
+#### DelegationSummary Fields
+
+Each item in the `delegations` array is a `DelegationSummary`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `delegationId` | `string` | Unique delegation identifier |
+| `provider` | `string` | Payment provider (`stripe`, `braintree`, or `visa`) |
+| `providerPaymentMethodId` | `string` | Provider-side payment method ID |
+| `status` | `string` | Delegation status (`Active`, `Revoked`, etc.) |
+| `spendingLimitCents` | `string` | Maximum spendable amount in cents |
+| `amountSpentCents` | `string` | Amount already spent in cents |
+| `remainingBudgetCents` | `string` | Remaining budget in cents |
+| `currency` | `string` | Currency code (e.g., `usd`) |
+| `transactionCount` | `number` | Number of transactions made |
+| `expiresAt` | `string` | Expiry timestamp (ISO 8601) |
+| `createdAt` | `string` | Creation timestamp (ISO 8601) |
+| `apiKeyId` | `string \| null` | API key this delegation is restricted to, or `null` if unrestricted |
+
+#### PaymentMethodSummary Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Payment method ID (e.g., `pm_...`) |
+| `brand` | `string` | Card brand (e.g., `visa`, `mastercard`) |
+| `last4` | `string` | Last 4 digits of the card number |
+| `expMonth` | `number` | Card expiration month |
+| `expYear` | `number` | Card expiration year |
+| `allowedApiKeyIds` | `string[] \| null` | API keys allowed to use this card (`null` = unrestricted) |
+
+## X402 Access Token Structure
+
+The access token is a JWT containing an X402 v2 payment credential:
+
+```json
+{
+  "x402Version": 2,
+  "accepted": {
+    "scheme": "nvm:erc4337",           // Payment scheme
+    "network": "eip155:84532",         // Blockchain network (Base Sepolia)
+    "planId": "plan-123",              // Payment plan ID
+    "extra": {
+      "version": "1",                  // Extra version info
+      "agentId": "did:nv:agent-456"    // Optional agent restriction
+    }
+  },
+  "payload": {
+    "signature": "0x...",              // Cryptographic signature
+    "authorization": {
+      "from": "0xSubscriberAddress",   // Subscriber's wallet address
+      "sessionKeysProvider": "zerodev", // Session key provider
+      "sessionKeys": []                // Session keys for gasless transactions
+    }
+  },
+  "extensions": {}                     // Optional extensions
+}
+```
+
+### Card-Delegation Token Structure
+
+For fiat plans using `nvm:card-delegation`, the token contains a JWT-based delegation authorization:
+
+```json
+{
+  "x402Version": 2,
+  "accepted": {
+    "scheme": "nvm:card-delegation",
+    "network": "stripe",
+    "planId": "plan-123",
+    "extra": {
+      "version": "1",
+      "agentId": "did:nv:agent-456"
+    }
+  },
+  "payload": {
+    "token": "eyJhbGciOiJSUzI1NiIs...",
+    "authorization": {
+      "from": "0xSubscriberAddress",
+      "sessionKeys": [{ "id": "redeem", "data": "0xabc123..." }]
+    }
+  },
+  "extensions": {}
+}
+```
+
+### Token Components
+
+- **x402Version**: Protocol version (2 for current spec)
+- **accepted**: Payment method specification
+  - **scheme**: `nvm:erc4337` for crypto or `nvm:card-delegation` for fiat
+  - **network**: `eip155:84532` (Base Sepolia) for crypto, one of `stripe`, `braintree`, or `visa` for fiat
+  - **planId**: The payment plan being used
+  - **extra**: Additional metadata (version, agentId, etc.)
+- **payload**: Payment authorization
+  - **signature** (erc4337): Cryptographic proof of payment authorization
+  - **token** (card-delegation): Signed JWT encoding the delegation claims
+  - **authorization**: Subscriber identity and session keys
+- **extensions**: Optional protocol extensions
+
+## Verify X402 Permissions
+
+Agents verify tokens before executing requests:
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+import { buildPaymentRequired } from '@nevermined-io/payments'
+
+const agentPayments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,  // Builder/agent API key
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// Build payment required specification
+const paymentRequired = buildPaymentRequired(planId, {
+  endpoint: '/api/v1/tasks',
+  agentId: agentId,
+  httpVerb: 'POST',
+  network: 'eip155:84532',
+  description: 'Task execution API',
+})
+
+// Verify subscriber permissions
+const verification = await agentPayments.facilitator.verifyPermissions({
+  paymentRequired,
+  x402AccessToken: accessToken,
+  maxAmount: 2n,  // Max credits to verify
+})
+
+if (verification.isValid) {
+  console.log('✓ Permissions verified')
+  console.log(`Payer: ${verification.payer}`)
+} else {
+  console.log(`✗ Verification failed: ${verification.invalidReason}`)
+}
+```
+
+### Verification Response
+
+```typescript
+interface VerifyPermissionsResult {
+  isValid: boolean           // True if token is valid
+  invalidReason?: string     // Reason for invalidity (if isValid is false)
+  payer?: string             // Address of the payer's wallet
+  agentRequestId?: string    // Agent request ID for observability tracking (Nevermined extension)
+  urlMatching?: string       // URL pattern that matched the endpoint (Nevermined extension)
+  agentRequest?: StartAgentRequest  // Agent request context for observability (Nevermined extension)
+}
+
+interface StartAgentRequest {
+  agentRequestId: string     // Unique request identifier
+  agentName: string          // Name of the agent
+  agentId: string            // Agent identifier
+  balance: PlanBalance       // Current plan balance (planId, balance, pricePerCredit, etc.)
+  urlMatching: string        // URL pattern that was matched
+  verbMatching: string       // HTTP verb that was matched
+  batch: boolean             // Whether this is a batch request
+}
+```
+
+## Settle X402 Permissions
+
+After successful execution, burn credits:
+
+```typescript
+// Settle permissions (burn credits)
+const settlement = await agentPayments.facilitator.settlePermissions({
+  paymentRequired,
+  x402AccessToken: accessToken,
+  maxAmount: 2n,  // Credits to burn
+  batch: false,   // Batch settlement (optional)
+  marginPercent: 5,  // Add 5% margin (optional)
+  agentRequestId: verification.agentRequest?.agentRequestId,  // From verification
+})
+
+console.log(`✓ Settlement successful`)
+console.log(`Transaction: ${settlement.transaction}`)
+console.log(`Credits burned: ${settlement.creditsRedeemed}`)
+console.log(`Remaining balance: ${settlement.remainingBalance}`)
+```
+
+### Settlement Response
+
+```typescript
+interface SettlePermissionsResult {
+  success: boolean          // True if settlement succeeded
+  transaction: string       // Blockchain transaction hash
+  creditsRedeemed: string   // Credits burned
+  remainingBalance: string  // Subscriber's remaining credits
+  network: string          // Blockchain network
+}
+```
+
+## HTTP Headers (X402 v2)
+
+### payment-signature Header
+
+Subscribers include this header in requests:
+
+```http
+POST /api/v1/tasks HTTP/1.1
+Host: agent.example.com
+Content-Type: application/json
+payment-signature: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+{"prompt": "Hello"}
+```
+
+### PAYMENT-REQUIRED Header (402 Response)
+
+Agents return this header when payment is required:
+
+```http
+HTTP/1.1 402 Payment Required
+Content-Type: application/json
+PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiL2FwaS92MS90YXNrcyJ9...
+
+{"error": "Payment required"}
+```
+
+The header contains base64-encoded payment requirement JSON. The `scheme` and `network` vary by plan type:
+
+**Crypto plan:**
+
+```json
+{
+  "x402Version": 2,
+  "resource": {
+    "url": "/api/v1/tasks",
+    "description": "Task execution API",
+    "mimeType": "application/json"
+  },
+  "accepts": [
+    {
+      "scheme": "nvm:erc4337",
+      "network": "eip155:84532",
+      "planId": "plan-123",
+      "extra": {
+        "version": "1",
+        "agentId": "did:nv:agent-456"
+      }
+    }
+  ],
+  "extensions": {}
+}
+```
+
+**Fiat plan:**
+
+```json
+{
+  "x402Version": 2,
+  "resource": {
+    "url": "/api/v1/tasks",
+    "description": "Task execution API",
+    "mimeType": "application/json"
+  },
+  "accepts": [
+    {
+      "scheme": "nvm:card-delegation",
+      "network": "stripe",
+      "planId": "plan-123",
+      "extra": {
+        "version": "1",
+        "agentId": "did:nv:agent-456"
+      }
+    }
+  ],
+  "extensions": {}
+}
+```
+
+### PAYMENT-RESPONSE Header (Success)
+
+Agents include this header in successful responses:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4Li4uIn0=
+
+{"result": "Task completed"}
+```
+
+The header contains base64-encoded settlement details:
+
+```json
+{
+  "success": true,
+  "network": "eip155:84532",
+  "transaction": "0x...",
+  "creditsRedeemed": "2",
+  "remainingBalance": "98"
+}
+```
+
+## Complete X402 Flow
+
+### Subscriber Side
+
+```typescript
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+
+const subscriberPayments = Payments.getInstance({
+  nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+// 1. Create a delegation once (currency required; 'usdc' for erc4337),
+//    then generate an access token by its delegationId.
+const { delegationId } = await subscriberPayments.delegation.createDelegation({
+  provider: 'erc4337',
+  spendingLimitCents: 1000,
+  durationSecs: 86_400,
+  currency: 'usdc',
+})
+const { accessToken } = await subscriberPayments.x402.getX402AccessToken(planId, agentId, {
+  scheme: 'nvm:erc4337',
+  delegationConfig: { delegationId },
+})
+
+// 2. Make request with payment-signature header
+const response = await fetch('https://agent.example.com/api/v1/tasks', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'payment-signature': accessToken,
+  },
+  body: JSON.stringify({ prompt: 'Hello, agent!' }),
+})
+
+// 3. Handle response
+if (response.status === 402) {
+  // Payment required - need to purchase plan or top up
+  const paymentRequired = response.headers.get('PAYMENT-REQUIRED')
+  console.error('Payment required:', paymentRequired)
+} else {
+  const result = await response.json()
+  const paymentResponse = response.headers.get('PAYMENT-RESPONSE')
+  console.log('Success:', result)
+  console.log('Payment:', paymentResponse)
+}
+```
+
+### Agent Side
+
+```typescript
+import express from 'express'
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
+import { buildPaymentRequired } from '@nevermined-io/payments'
+
+const app = express()
+app.use(express.json())
+
+const agentPayments = Payments.getInstance({
+  nvmApiKey: process.env.NVM_API_KEY!,
+  environment: 'sandbox' as EnvironmentName,
+})
+
+app.post('/api/v1/tasks', async (req, res) => {
+  // 1. Extract token
+  const accessToken = req.headers['payment-signature'] as string
+
+  if (!accessToken) {
+    const paymentRequired = buildPaymentRequired(planId, {
+      endpoint: req.url,
+      agentId: agentId,
+      httpVerb: req.method,
+    })
+
+    return res
+      .status(402)
+      .set('PAYMENT-REQUIRED', Buffer.from(JSON.stringify(paymentRequired)).toString('base64'))
+      .json({ error: 'Payment required' })
+  }
+
+  // 2. Build payment required
+  const paymentRequired = buildPaymentRequired(planId, {
+    endpoint: req.url,
+    agentId: agentId,
+    httpVerb: req.method,
+  })
+
+  try {
+    // 3. Verify permissions
+    const verification = await agentPayments.facilitator.verifyPermissions({
+      paymentRequired,
+      x402AccessToken: accessToken,
+      maxAmount: 2n,
+    })
+
+    if (!verification.isValid) {
+      return res
+        .status(402)
+        .set('PAYMENT-REQUIRED', Buffer.from(JSON.stringify(paymentRequired)).toString('base64'))
+        .json({ error: 'Insufficient credits' })
+    }
+
+    // 4. Execute task
+    const result = await processTask(req.body)
+
+    // 5. Settle permissions
+    const settlement = await agentPayments.facilitator.settlePermissions({
+      paymentRequired,
+      x402AccessToken: accessToken,
+      maxAmount: 2n,
+    })
+
+    // 6. Return response with PAYMENT-RESPONSE header
+    const paymentResponse = {
+      success: settlement.success,
+      network: settlement.network,
+      transaction: settlement.transaction,
+      creditsRedeemed: settlement.creditsRedeemed,
+    }
+
+    return res
+      .status(200)
+      .set('PAYMENT-RESPONSE', Buffer.from(JSON.stringify(paymentResponse)).toString('base64'))
+      .json({ result })
+
+  } catch (error) {
+    res.status(500).json({ error: error.message })
+  }
+})
+
+app.listen(3000)
+```
+
+## buildPaymentRequired Helper
+
+Simplifies creating X402PaymentRequired objects:
+
+```typescript
+import { buildPaymentRequired } from '@nevermined-io/payments'
+
+// Scheme auto-detected from plan metadata when omitted
+const paymentRequired = buildPaymentRequired(
+  planId,
+  {
+    endpoint: '/api/v1/tasks',      // Resource URL
+    agentId: 'did:nv:agent-456',    // Agent ID
+    httpVerb: 'POST',               // HTTP method
+    network: 'eip155:84532',        // Blockchain (default for nvm:erc4337)
+    description: 'Task execution',  // Description
+    scheme: 'nvm:erc4337'           // Optional: omit to auto-detect from plan metadata
+  }
+)
+```
+
+When `scheme` is set to `'nvm:card-delegation'`, the `network` is automatically set to `'stripe'`.
+
+## Best Practices
+
+1. **Always Verify Before Execute**: Never skip token verification
+2. **Settle After Success**: Only burn credits after successful execution
+3. **Use X402 v2 Headers**: Prefer `payment-signature` over Authorization
+4. **Return 402 Properly**: Include `PAYMENT-REQUIRED` header with details
+5. **Log Transactions**: Record settlement transaction hashes
+6. **Handle Errors**: Provide clear error messages in 402 responses
+7. **Token Reuse**: Subscribers can reuse tokens for multiple requests
+8. **Restrict Cards to API Keys**: When running multiple agents, restrict each card to specific NVM API Keys using `allowedApiKeyIds` to prevent unauthorized spending
+9. **Reuse Delegations**: Pass `delegationId` to reuse existing delegations instead of creating new ones on each request — this avoids delegation sprawl and keeps spending consolidated
+
+## Related Documentation
+
+- [Querying an Agent](./querying-an-agent) - How subscribers use X402 tokens
+- [Validation of Requests](./validation-of-requests) - How agents verify and settle
+- [MCP Integration](./mcp-integration) - Automatic X402 handling in MCP
+- [A2A Integration](./a2a-integration) - Automatic X402 handling in A2A
+
+---
+
+**Source References**:
+- `src/x402/token.ts` (getX402AccessToken)
+- `src/x402/delegation-api.ts` (DelegationAPI: listPaymentMethods, listDelegations, updatePaymentMethod)
+- `src/x402/facilitator-api.ts` (verifyPermissions, settlePermissions, buildPaymentRequired)
+- `tests/e2e/test_x402_e2e.test.ts` (complete X402 flow)