docs: add auto-order guide for x402 flow

docs.json

@@ -108,6 +108,7 @@
                         "pages": [
                             "docs/integrate/patterns/fiat-payments",
                             "docs/integrate/patterns/stablecoin-payments",
+                            "docs/integrate/patterns/auto-order",
                             "docs/development-guide/nevermined-x402",
                             "docs/integrate/patterns/payment-models",
                             "docs/integrate/patterns/validate-requests",

docs/development-guide/nevermined-x402.mdx

@@ -1,12 +1,12 @@
 ---
 title: "Nevermined x402"
 description: "Nevermined provides first-class support for the x402 payment protocol, enabling AI agents, APIs, and services to charge per-request using secure, locally-signed payment authorizations."
 icon: "credit-card"
 ---
 
 # Nevermined x402
 
 Nevermined provides first-class support for the x402 payment protocol, enabling AI agents, APIs, and services to charge per-request using secure, locally-signed payment authorizations.
 
 <Note>
 For the complete technical specification, see the [x402 Smart Accounts Extension Spec](/docs/specs/x402-smart-accounts).
@@ -17,7 +17,7 @@
 This section explains:
 
 - The x402 HTTP 402 handshake and `PAYMENT-SIGNATURE` retry pattern
 - How Nevermined extends x402 with Smart Account-based settlement
 - How subscribers generate and sign x402 payment proofs
 - How delegations, session keys, and delegated execution work
 - How the facilitator verifies and settles requests
@@ -28,7 +28,7 @@
 
 - [Payment Models](/docs/integrate/patterns/payment-models)
 
 Nevermined's x402 implementation is compatible with the standard protocol while adding programmable settlement layers powered by Nevermined smart contracts.
 
 ## Background: What x402 Solves
 
@@ -43,21 +43,21 @@
    - Checks balance/permissions
    - Settles payment on-chain (EIP-3009 or equivalent)
 
 Nevermined extends this with ERC-4337 Smart Accounts, session keys, and programmable billing models, allowing much more complex behavior than standard EIP-3009-based transfers.
 
 ## Why Nevermined Extends x402
 
 x402 itself focuses on single ERC-20, pay-per-request flows.
 
 Nevermined introduces:
 
 | Area                  | x402            | Nevermined                                                          |
 | --------------------- | --------------- | ------------------------------------------------------------------- |
 | Payment authorization | EIP-3009        | ERC-4337 UserOps + session keys                                     |
 | Wallet model          | EOA signatures  | Smart Accounts with granular permissions                            |
 | Billing models        | Pay-per-request | Subscriptions, credits, time windows, credit-burning                |
 | Delegated execution   | Basic           | Fully programmable “burn”, “order”, “redeem”, plan-specific actions |
 | Settlement layer      | ERC-20          | Nevermined smart-contract settlement                                |
 
 
 This means a subscriber can grant a server the ability to redeem credits or burn usage units while maintaining strict control over what the server can do.
@@ -79,17 +79,17 @@
 
 - Subscriber: owns a Smart Account; delegates permissions through smart account policies
 - Server/Agent: exposes an API secured by x402
 - Facilitator: Nevermined component that verifies and settles payments
 - Blockchain: executes credit burns, orders, or other plan-specific actions
 
 
 ## The Nevermined x402 Extensions
 
 Nevermined introduces two x402 schemes for different payment rails:
 
 | Scheme | Network | Use Case | Settlement |
 |--------|---------|----------|------------|
 | `nvm:erc4337` | `eip155:84532` | Crypto payments | ERC-4337 UserOps + session keys |
 | `nvm:card-delegation` | `stripe` | Fiat/credit card | Stripe PaymentIntent + credit burn |
 
 For the complete delegation specification, see the [Delegation Spec](/docs/specs/x402-card-delegation).
@@ -111,7 +111,7 @@
 
 When a server requires payment, it returns a `402` response with a `payment-required` header. The scheme depends on the plan's pricing configuration:
 
 **Crypto plan (`nvm:erc4337`):**
 
 ```json
 {
@@ -204,7 +204,7 @@
 
 ## Complete Payment & Execution Flow
 
 Below is the Nevermined x402 Smart Account flow (verification + settlement).
 
 ```mermaid
 sequenceDiagram
@@ -267,7 +267,7 @@
 - Execute order (if needed) to top up credits
 - Execute burn to deduct usage
 - Submit UserOps on-chain
 - Return tx hashes to the server
 
 ## Developer Guide: Subscriber Flow
 
@@ -281,7 +281,7 @@
 
 ### Step 2 — Build a payment payload
 
 Using Nevermined Payments libraries (Python or TS), you generate an x402 access token. Token generation requires a `delegationConfig` that controls spending limits and duration. You can either auto-create a delegation inline (Pattern A) or create one explicitly and reuse its ID (Pattern B).
 
 <Tabs>
   <Tab title="TypeScript">
@@ -328,7 +328,7 @@
     import base64
     import json
     import requests
     from payments_py import Payments, PaymentOptions
 
     payments = Payments.get_instance(
         PaymentOptions(nvm_api_key="nvm:subscriber-key", environment="sandbox")
@@ -348,9 +348,17 @@
         agent_id = payment_required["accepts"][0].get("extra", {}).get("agentId")
 
         # Pattern A: Auto-create a delegation inline
-        token_res = payments.x402.get_x402_access_token(plan_id, agent_id, {
-            'delegationConfig': { 'spendingLimitCents': 10000, 'durationSecs': 604800 }
-        })
+        from payments_py.x402 import X402TokenOptions, DelegationConfig
+        token_res = payments.x402.get_x402_access_token(
+            plan_id,
+            agent_id,
+            token_options=X402TokenOptions(
+                delegation_config=DelegationConfig(
+                    spending_limit_cents=10000,
+                    duration_secs=604800
+                )
+            )
+        )
         access_token = token_res["accessToken"]
 
         # Pattern B: Create a delegation explicitly, then reuse its ID
@@ -368,9 +376,13 @@
 </Tabs>
 
 <Note>
 The SDK auto-detects the payment scheme from plan metadata. For fiat plans (`isCrypto: false`), use `resolveScheme()` (TypeScript) or `resolve_scheme()` (Python) to determine the correct scheme. For fiat plans, use `provider: 'stripe'` in the delegation; for crypto plans, use `provider: 'erc4337'`. Middleware handles this automatically — see the [Express.js](/docs/integrate/add-to-your-agent/express) and [FastAPI](/docs/integrate/add-to-your-agent/fastapi) integration guides.
 </Note>
 
+<Tip>
+When a delegation is in place, the facilitator can auto-purchase credits if the balance runs out at settlement — no manual `order_plan()` calls needed. See the [Auto-Order guide](/docs/integrate/patterns/auto-order) for details, spending controls, and A2A examples.
+</Tip>
+
 ### Step 3 — Submit with HTTP header
 
 Clients include the x402 access token in the `payment-signature` header:
@@ -500,7 +512,7 @@
   </Tab>
   <Tab title="Python">
     ```python
     from payments_py import Payments, PaymentOptions
 
     payments = Payments.get_instance(
         PaymentOptions(nvm_api_key="nvm:agent-key", environment="sandbox")

docs/getting-started/quickstart.mdx

@@ -1,29 +1,29 @@
 ---
 title: "Quickstart"
 description: "Get started with Nevermined Pay in 5 minutes"
 icon: "rocket-launch"
 ---
 
 This guide provides a quick path to integrating Nevermined, whether you're an AI Builder looking to monetize an AI agent or service, or a User wanting to access one. You can interact with Nevermined through our user-friendly Web App or programmatically via our SDKs.
 
 ## For AI Builders: Monetize Your Agent
 
 ### Using the Nevermined Web App (No Code)
 
 The easiest way to get started is by using the [Nevermined App](https://nevermined.app/) to register your agent and create payment plans through a visual interface.
 
 1. **Log In**: Access the app via Web3Auth (socials or wallet).
 2. **Register Agent**: Navigate to the "Agents" tab to "Register New Agent". Fill in your agent's metadata (name, description) and register all API endpoints.
 3. **Create Pricing Plan**: Define one or more pricing plans for your agent, specifying price, payment currency (fiat or crypto), and usage terms (per-request pricing).
 4. **Done\!**: Your agent is now discoverable and ready to accept payments.
 
 ### Using the SDKs (Programmatic)
 
 For developers who need to automate and integrate directly, our SDKs are the perfect tool.
 
 <Steps>
   <Step title="1. Get 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, then store it as an environment variable:
 
     ```bash
     export NVM_API_KEY="sandbox:your-api-key-here"
@@ -243,13 +243,13 @@
 
 ## For Users (Subscribers): Access an AI Agent
 
 ### Using the Nevermined Web App
 
 1. **Discover**: Find agents in the [Nevermined App](https://nevermined.app/) or other marketplaces.
 2. **Purchase**: Select a pricing plan and purchase it with crypto or a credit card.
 3. **Get Credentials**: Once purchased, you'll receive API credentials to access the agent.
 
 ### Using the SDKs
 
 <Tabs>
   <Tab title="TypeScript">
@@ -337,4 +337,8 @@
     print(f'Agent response: {result}')
     ```
   </Tab>
-</Tabs>
+</Tabs>
+
+<Tip>
+In autonomous or agent-to-agent workflows, skip the manual `order_plan()` loop — when a delegation is in place the facilitator tops up credits automatically if the balance runs out. See the [Auto-Order guide](/docs/integrate/patterns/auto-order).
+</Tip>

docs/integrate/patterns/auto-order.mdx

@@ -0,0 +1,143 @@
+---
+title: "Auto-Order"
+description: "When a subscriber has no credits, calling get_x402_access_token with a delegation automatically purchases credits for the plan — no manual order_plan step needed."
+icon: "arrows-rotate"
+---
+
+By default, subscribers purchase a plan first and then generate an access token. Auto-order removes the manual purchase step: when you call `getX402AccessToken` / `get_x402_access_token` with a delegation and the subscriber has no credits, the system purchases credits for the plan automatically before returning the token.
+
+## Manual flow vs. auto-order
+
+<Tabs>
+  <Tab title="TypeScript">
+    ```typescript
+    // Manual flow — check balance, order if needed, wait for settlement
+    const balance = await payments.plans.getPlanBalance(planId)
+    if (Number(balance.balance) <= 0) {
+      await payments.plans.orderPlan(planId)
+      await new Promise(resolve => setTimeout(resolve, 5000)) // wait for on-chain confirmation
+    }
+    const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {
+      delegationConfig: { spendingLimitCents: 10000, durationSecs: 604800 }
+    })
+
+    // Auto-order — one step: if no credits, the system purchases them automatically
+    const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {
+      delegationConfig: { spendingLimitCents: 10000, durationSecs: 604800 }
+    })
+    ```
+  </Tab>
+  <Tab title="Python">
+    ```python
+    import time
+    from payments_py.x402 import X402TokenOptions, DelegationConfig
+
+    # Manual flow — check balance, order if needed, wait for settlement
+    balance = payments.plans.get_plan_balance(plan_id)
+    if balance.get('balance', 0) <= 0:
+        payments.plans.order_plan(plan_id)
+        time.sleep(5)  # wait for on-chain confirmation
+    token_res = payments.x402.get_x402_access_token(plan_id, agent_id)
+
+    # Auto-order — one step: if no credits, the system purchases them automatically
+    token_res = payments.x402.get_x402_access_token(
+        plan_id, agent_id,
+        token_options=X402TokenOptions(
+            delegation_config=DelegationConfig(spending_limit_cents=10000, duration_secs=604800)
+        )
+    )
+    access_token = token_res['accessToken']
+    ```
+  </Tab>
+</Tabs>
+
+<Note>
+The code is identical — the difference is that with a delegation in place you can skip the explicit `order_plan` / `orderPlan` call. If the subscriber already has credits the token is returned immediately; if not, the purchase happens first.
+</Note>
+
+## Setting up the delegation
+
+The delegation authorizes the system to spend on the subscriber's behalf. The two required fields when creating a new delegation are:
+
+| Field | Description |
+|---|---|
+| `spendingLimitCents` | Total spending cap for this delegation's lifetime, in cents. `10000` = $100. |
+| `durationSecs` | How long the delegation is valid in seconds. `604800` = 7 days. |
+
+For long-running agents, create the delegation once and reuse its ID across requests:
+
+<Tabs>
+  <Tab title="TypeScript">
+    ```typescript
+    // Create once
+    const delegation = await payments.delegation.createDelegation({
+      provider: 'erc4337',
+      spendingLimitCents: 50000, // $500 total budget
+      durationSecs: 2592000       // 30 days
+    })
+
+    // Reuse across all requests — spending tracked cumulatively
+    const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {
+      delegationConfig: { delegationId: delegation.delegationId }
+    })
+    ```
+  </Tab>
+  <Tab title="Python">
+    ```python
+    from payments_py.x402 import X402TokenOptions, DelegationConfig, CreateDelegationPayload
+
+    # Create once
+    delegation = payments.delegation.create_delegation(
+        CreateDelegationPayload(
+            provider='erc4337',
+            spending_limit_cents=50000,  # $500 total budget
+            duration_secs=2592000         # 30 days
+        )
+    )
+
+    # Reuse across all requests — spending tracked cumulatively
+    token_res = payments.x402.get_x402_access_token(
+        plan_id, agent_id,
+        token_options=X402TokenOptions(
+            delegation_config=DelegationConfig(delegation_id=delegation.delegation_id)
+        )
+    )
+    access_token = token_res['accessToken']
+    ```
+  </Tab>
+</Tabs>
+
+## Fiat plans (`nvm:card-delegation`)
+
+Auto-order works the same way for card-delegation plans. If the subscriber has no credits, the system creates a Stripe charge automatically when `get_x402_access_token` is called. The `spendingLimitCents` in the delegation controls the total charge ceiling.
+
+See [Fiat Payments](/docs/integrate/patterns/fiat-payments) and [Nevermined Pay](/docs/products/nvm-pay/overview) for how to enroll a card.
+
+## When auto-order stops
+
+| Condition | What happens |
+|---|---|
+| Delegation `spendingLimitCents` exhausted | Purchase is rejected. Token generation fails with a payment error. |
+| Delegation expired (`durationSecs` elapsed) | Delegation is invalid. Token generation fails. |
+| Subscriber wallet has insufficient token balance (crypto) | On-chain purchase fails. Token generation fails. |
+
+<Warning>
+In A2A pipelines, handle token generation failures explicitly. When a delegation is exhausted or expired, surface a clear payment error to the orchestrator rather than retrying indefinitely.
+</Warning>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Stablecoin Payments" icon="coins" href="/docs/integrate/patterns/stablecoin-payments">
+    Understand the crypto payment model and how delegations work on-chain
+  </Card>
+  <Card title="Fiat Payments" icon="credit-card" href="/docs/integrate/patterns/fiat-payments">
+    Accept cards via Stripe or Visa with per-request auto-charging
+  </Card>
+  <Card title="Nevermined x402" icon="handshake" href="/docs/development-guide/nevermined-x402">
+    Deep dive into the x402 protocol, session keys, and settlement flow
+  </Card>
+  <Card title="A2A Monetization" icon="robot" href="/docs/solutions/agent-to-agent-monetization">
+    Build autonomous agent pipelines with built-in payment rails
+  </Card>
+</CardGroup>

docs/integrate/patterns/fiat-payments.mdx

@@ -1,16 +1,16 @@
 ---
 title: "Fiat Payments"
 description: "Accept credit cards via Stripe or Visa with no crypto wallet required. The easiest path for mainstream and enterprise adoption."
 icon: "credit-card"
 ---
 
 Accept credit cards in **USD or EUR**, with no crypto wallet required. Fiat payments are the fastest path to mainstream adoption. Your users can start paying with a card they already have, either through Stripe Checkout or by enrolling their card via [Nevermined Pay](/docs/products/nvm-pay/overview) for autonomous agent charging.
 
 ## When to Use Fiat Payments
 
 <CardGroup cols={2}>
   <Card title="Enterprise Adoption" icon="building">
     Organizations that already pay for SaaS with corporate cards can onboard without touching crypto.
   </Card>
 
   <Card title="Mainstream Users" icon="users">
@@ -28,14 +28,14 @@
 
 ## Fiat Payment Scenarios
 
 Nevermined supports fiat payments in two scenarios:
 
 - **Human-to-Agent**: A user visits the Nevermined App checkout page and purchases a plan with their credit card. This is the simplest flow for onboarding new customers.
 - **Agent-to-Agent**: An agent owner enrolls a credit card via [Nevermined Pay](/docs/products/nvm-pay/overview) (Visa or Stripe) and creates a spending mandate or delegation. The agent can then make autonomous payments on behalf of the owner, charging the card per request within the defined limits.
 
 ## Pay-per-request or a bundle of credits
 
 Nevermined offers two distinct fiat payment flows depending on whether you want upfront plan purchases or per-request charging.
 
 <CardGroup cols={2}>
   <Card title="Plan Purchase" icon="cart-shopping">
@@ -49,15 +49,15 @@
 
 ## Human-to-Agent Purchase Flow
 
 The simplest way to accept fiat. Users complete a standard Stripe Checkout session, and Nevermined handles the rest.
 
 <Steps>
   <Step title="Select a plan">
     The user browses available plans in the Nevermined App or your custom UI and selects one priced in fiat.
   </Step>
 
   <Step title="Redirect to Stripe Checkout">
     Nevermined creates a Stripe Checkout session and redirects the user to complete payment with their card.
   </Step>
 
   <Step title="Payment completes">
@@ -65,7 +65,7 @@
   </Step>
 
   <Step title="Webhook confirms payment">
     Nevermined receives a webhook from Stripe confirming the successful payment.
   </Step>
 
   <Step title="Credits minted on-chain">
@@ -73,20 +73,20 @@
   </Step>
 </Steps>
 
 Both one-time and recurring plan purchases are supported. For recurring plans, Stripe handles rebilling and Nevermined mints fresh credits each billing cycle.
 
 ## Agent-to-Agent Purchase Flow (Nevermined Pay)
 
 Fully autonomous agent-to-agent payments in fiat are enabled through [Nevermined Pay](/docs/products/nvm-pay/overview). This allows an agent to charge a user's card on-demand, without the user needing to pre-purchase credits. Instead of buying credits upfront, the user enrolls a card and creates a spending mandate or delegation with defined limits.
 
 NVM Pay supports two card enrollment providers:
 
 - **Visa** - Cards tokenized via Visa Token Service (VTS) with passkey (FIDO2) authentication
 - **Stripe** - Cards captured via Stripe Elements with SetupIntent tokenization
 
 <Steps>
   <Step title="Card Enrollment">
     The user enrolls a card via the [Nevermined Pay dashboard](https://pay.nevermined.app). Card data is tokenized by the provider (Visa or Stripe) and NVM Pay never stores raw card numbers. See [Card Enrollment](/docs/products/nvm-pay/card-enrollment) for the full flow.
   </Step>
 
   <Step title="Create a spending authorization">
@@ -103,7 +103,7 @@
 </Steps>
 
 <Note>
-Card delegation is what enables fiat-based agent-to-agent payments. An agent owner enrolls their card and sets spending limits, and the agent can autonomously pay for services from other agents, all settled in fiat. See the [NVM Pay FAQ](/docs/products/nvm-pay/faq) for common questions.
+Card delegation is what enables fiat-based agent-to-agent payments. An agent owner enrolls their card and sets spending limits, and the agent can autonomously pay for services from other agents, all settled in fiat. Auto-ordering is built into card delegations: if a subscriber's credit balance runs out during a request, the facilitator automatically creates a new Stripe charge within the delegation limits — no extra parameters needed. See the [Auto-Order guide](/docs/integrate/patterns/auto-order) and the [NVM Pay FAQ](/docs/products/nvm-pay/faq) for details.
 </Note>
 
 ## Permission Model
@@ -129,7 +129,7 @@
 
 ## Security and PCI Compliance
 
 Card data never reaches Nevermined servers. Depending on the provider:
 
 - **Visa path** - Card data is captured via a PCI-compliant VGS vault and tokenized by Visa Token Service (VTS). Each payment generates a one-time VIC credential.
 - **Stripe path** - Card data goes directly to Stripe via Stripe Elements. Stripe manages secure storage and charging.
@@ -141,7 +141,7 @@
 
 ## Revenue Routing with Stripe Connect
 
 When a user pays with a card, Nevermined routes the revenue to the builder's connected Stripe account using Stripe Connect. Fees are deducted automatically before the payout reaches the builder.
 
 This means you receive funds directly in your Stripe account -- no manual transfers or reconciliation needed.
 
@@ -149,13 +149,13 @@
 
 | Item | Cost |
 |------|------|
 | Nevermined fee | 2% of the transaction amount |
 | Stripe processing fee | Fixed fee + % per transaction (varies by currency/region; see Stripe pricing) |
 | Supported currencies | USD, EUR |
 | Settlement | Via Stripe PaymentIntents to builder's connected account |
 
 <Warning>
 Fiat payments carry higher fees than stablecoin payments (2% + Stripe fees vs. 1% flat). For high-volume or high-value use cases, consider [stablecoin payments](/docs/integrate/patterns/stablecoin-payments) to reduce costs.
 </Warning>
 
 ## Supported Plan Types
@@ -174,7 +174,7 @@
   </Card>
 
   <Card title="Recurring" icon="arrows-rotate">
     Automatic rebilling at the end of each period. Stripe manages the billing cycle.
   </Card>
 </CardGroup>
 
@@ -186,7 +186,7 @@
   </Card>
 
   <Card title="Stablecoin Payments" icon="coins" href="/docs/integrate/patterns/stablecoin-payments">
     Accept crypto payments with the lowest fees and on-chain transparency
   </Card>
 
   <Card title="Payment Models" icon="calculator" href="/docs/integrate/patterns/payment-models">
@@ -194,6 +194,6 @@
   </Card>
 
   <Card title="Manage Plans" icon="sliders" href="https://nevermined.app">
     Create and manage payment plans in the Nevermined App
   </Card>
 </CardGroup>

docs/integrate/patterns/stablecoin-payments.mdx

@@ -1,12 +1,12 @@
 ---
 title: "Stablecoin Payments"
 description: "Accept USDC, EURC, or any ERC-20 token on-chain with the lowest fees and full transparency."
 icon: "coins"
 ---
 
 Accept USDC, EURC, or any ERC-20 token directly on-chain. Stablecoin payments are Nevermined's native payment method, purpose-built for crypto users and autonomous agent-to-agent commerce.
 
 ## When to Use Stablecoins
 
 <CardGroup cols={2}>
   <Card title="Agent-to-Agent Payments" icon="robot">
@@ -14,19 +14,19 @@
   </Card>
 
   <Card title="Human-to-Agent Purchases" icon="user">
     Users buy plans through the Nevermined App checkout page, paying with tokens from their connected wallet.
   </Card>
 
   <Card title="Crypto-Native Users" icon="wallet">
     Your audience already holds stablecoins and prefers on-chain payments over traditional card flows.
   </Card>
 
   <Card title="Lowest Fees" icon="piggy-bank">
     Just 1% Nevermined fee with no additional processing surcharges. Ideal for high-volume or high-value use cases.
   </Card>
 
   <Card title="On-Chain Transparency" icon="magnifying-glass">
     Every payment settles on-chain, giving both parties a verifiable, auditable record of every transaction.
   </Card>
 </CardGroup>
 
@@ -34,7 +34,7 @@
 
 <Steps>
   <Step title="Fund a smart account">
     The subscriber funds their Nevermined smart account with ERC-20 tokens (USDC, EURC, or another supported token). This account is an ERC-4337 smart account that supports programmable permissions.
   </Step>
 
   <Step title="Create a delegation">
@@ -54,18 +54,18 @@
 
 Payments settle on the **Base** network. The most common tokens are:
 
 | Token | Description | Base Mainnet | Base Sepolia |
 |-------|-------------|-------------|-------------|
 | USDC  | USD-pegged stablecoin by Circle | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
 | EURC  | EUR-pegged stablecoin by Circle | `0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42` | `0x808456652fdb597867f38412077A9182bf77359F` |
 
 <Tip>
 Nevermined supports any ERC-20 token on Base. If you need to accept a custom token, you can specify its contract address when creating your plan's price configuration.
 </Tip>
 
 ## Permission Model
 
 Delegations are the core of the stablecoin permission model. Instead of giving the facilitator full control over a wallet, subscribers create scoped delegations that limit exactly what can be done. The delegation model is shared between crypto (`erc4337`) and fiat (`stripe`) payment providers.
 
 Each delegation enforces the **principle of least privilege** through two limits:
 
@@ -95,11 +95,11 @@
 
 | Item | Cost |
 |------|------|
 | Nevermined fee | 1% of the plan price |
 | Processing surcharge | None |
 | Settlement | On-chain via Nevermined smart contracts on Base |
 
 Because there's no payment processor in the middle, stablecoin payments carry no additional fees beyond the 1% Nevermined fee. This makes them the most cost-effective option, especially for high-volume use cases.
 
 ## Supported Plan Types
 
@@ -129,19 +129,13 @@
   </Card>
 </CardGroup>
 
-## Auto-Ordering
+## Auto-Order (Pay-As-You-Go)
 
-When a subscriber's credit balance runs low, the system can automatically purchase more credits on their behalf. This happens seamlessly if:
+When a subscriber's credit balance runs low, the x402 facilitator can automatically purchase more credits on their behalf — no manual balance checks required. This keeps agent-to-agent pipelines running without interruption.
 
-- The subscriber's wallet has sufficient token balance
-- The active delegation has remaining spending capacity (`spendingLimitCents` not exhausted)
-- The plan supports re-ordering
+Configure a delegation with `spendingLimitCents` when generating the access token and the facilitator handles the rest. Total spending is always bounded by that limit, enforced on-chain.
 
-This keeps agent-to-agent workflows running without interruption.
-
-<Warning>
-If the delegation's `spendingLimitCents` is exhausted or the delegation has expired, auto-ordering stops. The subscriber must create a new delegation with fresh limits to resume.
-</Warning>
+See the [Auto-Order guide](/docs/integrate/patterns/auto-order) for enabling this, safety controls, failure handling, and full A2A examples.
 
 ## Next Steps
 

docs/integrate/quickstart/python.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Python Quick Start"
 description: "Get started with Nevermined payments in Python"
 icon: "python"
 ---
 
 <Note>
   **Start here:** need to register a service and create a plan first or get your Nevermined API Key? Follow the
   [5-minute setup](/docs/integrate/quickstart/5-minute-setup).
 </Note>
 
@@ -232,7 +232,7 @@
     plan_id = os.environ['PLAN_ID']
     agent_id = os.environ['AGENT_ID']
 
-    # 1. Order the plan
+    # 1. Order the plan (purchases credits upfront)
     print('Purchasing plan...')
     order_result = payments.plans.order_plan(plan_id)
 
@@ -259,6 +259,10 @@
     purchase_and_query()
 ```
 
+<Tip>
+For autonomous agents that run continuously, set up a delegation when generating the access token — the facilitator tops up credits automatically when balance runs out, with no manual `order_plan()` loop needed. See the [Auto-Order guide](/docs/integrate/patterns/auto-order).
+</Tip>
+
 ## Flask Alternative
 
 ```python filename="flask_app.py"

docs/integrate/quickstart/typescript.mdx

@@ -1,11 +1,11 @@
 ---
 title: "TypeScript Quick Start"
 description: "Get started with Nevermined payments in TypeScript/Node.js"
 icon: "js"
 ---
 
 <Note>
   **Start here:** need to register a service and create a plan first or get your Nevermined API Key? Follow the
   [5-minute setup](/docs/integrate/quickstart/5-minute-setup).
 </Note>
 
@@ -221,7 +221,7 @@
 })
 
 async function purchaseAndQuery() {
-  // 1. Order the plan
+  // 1. Order the plan (purchases credits upfront)
   console.log('Purchasing plan...')
   await payments.plans.orderPlan(process.env.PLAN_ID!)
 
@@ -251,6 +251,10 @@
 purchaseAndQuery()
 ```
 
+<Tip>
+For autonomous agents that run continuously, set up a delegation when generating the access token — the facilitator tops up credits automatically when balance runs out, with no manual `orderPlan()` loop needed. See the [Auto-Order guide](/docs/integrate/patterns/auto-order).
+</Tip>
+
 ## Project Structure
 
 ```

skills/nevermined-payments/references/client-integration.md

@@ -23,14 +23,11 @@ const payments = Payments.getInstance({
   environment: 'sandbox'
 })
 
-// Order the plan
+// Order the plan (first purchase only)
 await payments.plans.orderPlan(PLAN_ID)
 
-// Check balance
-const balance = await payments.plans.getPlanBalance(PLAN_ID)
-console.log(`Credits remaining: ${balance}`)
-
-// Generate x402 access token (requires delegationConfig)
+// Generate x402 access token with a delegation
+// The facilitator will auto-order credits if balance runs out at settlement
 const { accessToken } = await payments.x402.getX402AccessToken(PLAN_ID, AGENT_ID, {
   delegationConfig: { spendingLimitCents: 10000, durationSecs: 604800 }
 })
@@ -47,23 +44,31 @@ payments = Payments.get_instance(
     PaymentOptions(nvm_api_key=os.environ["NVM_API_KEY"], environment="sandbox")
 )
 
-# Order the plan
+# Order the plan (first purchase only)
 payments.plans.order_plan(plan_id)
 
-# Check balance
-balance = payments.plans.get_plan_balance(plan_id)
-print(f"Credits remaining: {balance}")
-
-# Generate x402 access token (requires delegationConfig)
+# Generate x402 access token with a delegation
+# The facilitator will auto-order credits if balance runs out at settlement
 token_res = payments.x402.get_x402_access_token(
-    plan_id, agent_id,
+    plan_id,
+    agent_id,
     token_options=X402TokenOptions(
         delegation_config=DelegationConfig(spending_limit_cents=10000, duration_secs=604800)
     )
 )
 access_token = token_res["accessToken"]
 ```
 
+## Auto-Order
+
+When a delegation is configured, the facilitator can automatically purchase more credits at settlement time if the subscriber's balance is insufficient — no manual balance-check loop needed.
+
+- **Crypto plans (`nvm:erc4337`)**: pass `delegationConfig` with `spendingLimitCents` and `durationSecs`
+- **Fiat plans (`nvm:card-delegation`)**: auto-order is built into the card delegation — no extra parameter needed
+- **Spending cap**: always controlled by `spendingLimitCents` in the delegation, enforced on-chain
+- **When it stops**: delegation exhausted, expired, or wallet has insufficient token balance → request returns 402
+- Handle 402 responses in A2A pipelines explicitly — surface a clear payment error rather than retrying indefinitely
+
 ## Call a Protected HTTP API
 
 ### TypeScript