Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.delegare.dev/llms.txt

Use this file to discover all available pages before exploring further.

The @delegare/x402 package lets merchants monetize API endpoints using the x402 protocol while crucially implementing Google’s AP2 (Agentic Payment Protocol). This guarantees secure, autonomous transactions where the AI agent never holds private keys, credit card credentials, or raw funds. Instead, agents operate strictly via pre-authorized intent mandates (SD-JWT-VC). Beyond security, it handles the 402 challenge, payment verification, and settlement across multiple payment rails, and automatically embeds discovery metadata. This makes your endpoint seamlessly indexable on Delegare Market, agentic.market (CDP Bazaar), and mppscan.com (MPP) — one middleware, zero exposed credentials, three directories.

​
🔒 Secured by Google’s AP2 Protocol

Traditional agentic payments force developers to provision wallets with live funds or inject raw credit card details into the LLM context window—a massive security vulnerability. @delegare/x402 natively implements Google’s AP2 (Agentic Payment Protocol):
  1. No Keys in Context: Agents are issued an Intent Mandate (SD-JWT-VC) rather than returning raw card details or wallet seeds.
  2. Bounded Authority: Mandates define strict, server-side enforced spending limits and permitted rails.
  3. Zero-Trust Validation: The middleware cryptographically verifies the mandate before settling the payment on-chain or via fiat fallbacks.

​
Installation

npm install @delegare/x402

​
Quick Start

import express from 'express';
import { requireX402Payment } from '@delegare/x402';

const app = express();

app.get('/premium-data',
  requireX402Payment({
    price: '0.05',                  // 5 cents USDC per call
    payTo: '0xYourWalletAddress',   // Your Base wallet
  }),
  (req, res) => {
    res.json({ data: 'premium content' });
  }
);

app.listen(4000);

​
Dual-Rail Payments (Fiat Fallback)

Not all agent developers have a crypto wallet. Configure a Credit Bundle Fallback to add a Stripe-backed fiat path alongside the crypto path. 
app.post('/api/agent',
  requireX402Payment({
    price: '0.02',
    payTo: '0xYourWalletAddress',
    creditBundle: {
      tiers: [
        { name: 'Starter', usdCents: 1000, requests: 500 },
        { name: 'Pro', usdCents: 5000, requests: 3000 }
      ],
      purchaseUrl: 'https://yourapp.com/billing/bundles',
      validateAndDeduct: async (token: string) => {
        return { valid: true, creditsRemaining: 499, tenantId: 'org-123' };
      },
    },
  }),
  (req, res) => res.json({ success: true })
);
Clients pay once via Stripe, receive a bundle token, and send it via X-Bundle-Token to bypass crypto.

​
Agent Discovery (Delegare Market, CDP Bazaar + MPPScan)

Use declareDiscoveryExtension to make your endpoint automatically discoverable on Delegare Market, agentic.market, and mppscan.com. Place it before requireX402Payment. The metadata is embedded in both the PAYMENT-REQUIRED header (x402 v2, read by CDP Bazaar) and the WWW-Authenticate header (MPP/RFC 7235, read by MPPScan) on every 402 response. 
import { requireX402Payment, declareDiscoveryExtension } from '@delegare/x402';

app.post('/api/extract',
  declareDiscoveryExtension({
    description: "Extract structured financial data from documents. $0.15/page.",
    inputSchema: {
      type: "object",
      properties: {
        documentId: { type: "string", description: "Document ID" },
        domain: { type: "string", enum: ["commercial_loan", "equity_investment"] }
      },
      required: ["documentId"]
    },
    bodyType: "json",
    output: {
      example: { extractedData: { gross_income: 1250000 }, costCents: 150 },
      schema: {
        type: "object",
        properties: {
          extractedData: { type: "object" },
          costCents: { type: "number" }
        }
      }
    }
  }),
  requireX402Payment({ price: '0.15', payTo: '0xYourWalletAddress' }),
  async (req, res) => { res.json({ data: '...' }); }
);
output.schema is required (not just example) for CDP Bazaar to accept the index entry. Without it, the validator will report “schema is invalid” even if all other checks pass.

​
How Bazaar Indexing Works

CDP Bazaar indexes your endpoint the first time a PAYMENT-SIGNATURE credential is settled through their facilitator. The middleware handles this automatically:
  1. An agent hits your endpoint with PAYMENT-SIGNATURE (x402 v2 credential from @x402/fetch)
  2. The middleware passes the full payment payload — including your declareDiscoveryExtension metadata — directly to CDP’s /settle endpoint
  3. CDP settles on-chain and writes the catalog entry
  4. Your endpoint appears on agentic.market within ~10 minutes
To trigger indexing for existing endpoints without waiting for organic traffic, use the @x402/fetch client with your own wallet to make one test payment per endpoint. See the CDP Bazaar docs for details.

​
Required Environment Variables for Bazaar

COINBASE_API_KEY=your-cdp-key-id       # CDP API key UUID
COINBASE_API_SECRET=your-cdp-secret    # Base64-encoded Ed25519 key (64 bytes)
When set, the middleware automatically authenticates CDP settlement calls with a signed JWT — required for Bazaar catalog writes.

​
What the 402 Response Emits

Every unauthenticated request receives three parallel discovery headers:
HeaderProtocolRead by
PAYMENT-REQUIREDx402 v2Delegare Market, CDP Bazaar, agentic.market, @x402/fetch
WWW-Authenticate: Payment ...MPP / RFC 7235Delegare Market, MPPScan, MPP-compatible wallets
BAZAAR-EXTENSIONDelegare debugCustom clients
Plus a JSON body for backward-compatible x402 v1 clients.

​
Payment Rails (Priority Order)

The middleware accepts five types of payment credentials in this order:
Client headerRailSettlement
X-Bundle-TokenFiat credit bundleYour backend (Stripe)
PAYMENT-SIGNATUREx402 v2 USDCCDP Facilitator → Base
X-PAYMENTx402 v1 USDCDelegare Facilitator → Base
X-DELEGARE-MANDATEAP2 intent mandateDelegare Vault
Authorization: PaymentMPP/RFC 7235Delegare Facilitator

​
Configuration

requireX402Payment({
  // Required
  price: '0.05',                    // Decimal USDC (e.g. "0.05" = 5 cents)
  payTo: '0xYourWallet',            // Base wallet receiving payment

  // Optional
  testMode: true,                   // Use Base Sepolia (default: false)
  apiUrl: 'https://api.sandbox.delegare.dev/v1',
  resource: 'https://yourapi.com/api/endpoint', // Full URL — used as catalog key
  mimeType: 'application/json',
  maxTimeoutSeconds: 300,
  creditBundle: { ... }
});

​
Accessing Payment Context

app.get('/premium-data',
  requireX402Payment({ price: '0.05', payTo: '0xYourWallet' }),
  (req, res) => {
    const payer = (req as any).x402Payer;        // Payer's wallet address
    const txHash = (req as any).x402Transaction;  // On-chain tx hash
    res.json({ data: '...', paidBy: payer });
  }
);

​
Testing with Sandbox

requireX402Payment({
  price: '0.01',
  payTo: '0xYourTestnetWallet',
  testMode: true,
  apiUrl: 'https://api.sandbox.delegare.dev/v1',
});