@dexterai/x402 6.0.0-rc.5 → 6.0.0

package/dist/types-DolSK-3d.d.ts

@@ -0,0 +1,237 @@
+/**
+ * x402 v2 SDK — Shared Types
+ *
+ * Chain-agnostic types for x402 v2 payments.
+ * Works with Solana, Base, and any future x402-compatible networks.
+ */
+
+/**
+ * Context passed to a PayToProvider function.
+ * Contains request-scoped information for dynamic address resolution.
+ */
+interface PayToContext {
+    /** The PAYMENT-SIGNATURE header value (present on retry/verify, undefined on initial 402) */
+    paymentHeader?: string;
+    /** Amount in atomic units (e.g., '10000' for 0.01 USDC) */
+    amountAtomic?: string;
+    /** The resource URL being accessed */
+    resourceUrl?: string;
+}
+/**
+ * Optional defaults a PayToProvider can advertise for auto-configuration.
+ * Attached as `_x402Defaults` on the provider function.
+ */
+interface PayToProviderDefaults {
+    /** Default CAIP-2 network (e.g., 'eip155:8453' for Base) */
+    network?: string;
+    /** Default facilitator URL */
+    facilitatorUrl?: string;
+}
+/**
+ * A function that dynamically resolves a payment address.
+ * Used for providers like Stripe that generate per-request deposit addresses.
+ *
+ * @example
+ * ```typescript
+ * import { stripePayTo } from '@dexterai/x402/server';
+ *
+ * const provider = stripePayTo(process.env.STRIPE_SECRET_KEY);
+ * const address = await provider({ amountAtomic: '10000' });
+ * ```
+ */
+type PayToProvider = ((context: PayToContext) => Promise<string>) & {
+    /** Auto-configuration defaults (set by provider factories like stripePayTo) */
+    _x402Defaults?: PayToProviderDefaults;
+};
+/**
+ * Resource info included in payment requirements
+ */
+interface ResourceInfo {
+    /** Resource URL */
+    url: string;
+    /** Human-readable description */
+    description?: string;
+    /** MIME type of the resource */
+    mimeType?: string;
+}
+/**
+ * Extra fields in payment requirements
+ * Chain-specific fields may vary
+ */
+interface AcceptsExtra {
+    /** Facilitator address that pays tx fees (required for Solana) */
+    feePayer?: string;
+    /** Token decimals (optional - defaults to 6 for USDC) */
+    decimals?: number;
+    /** EIP-712: Token name (EVM only) */
+    name?: string;
+    /** EIP-712: Token version (EVM only) */
+    version?: string;
+    /**
+     * batch-settlement: on-chain authorizer that the escrow channel pays into.
+     * Provided by the facilitator's batch-settlement kind. EVM only.
+     */
+    receiverAuthorizer?: string;
+    /** Tab seller-wire header advertised by the default hosted scheme. */
+    voucherHeader?: string;
+    /** Tab registration encoding carried inside each seller voucher. */
+    registrationEncoding?: string;
+    /** Immutable commercial-terms version for this Tab offer. */
+    termsVersion?: string;
+    /** Event that makes usage accepted under the advertised terms version. */
+    acceptanceRule?: string;
+    /** Additional chain-specific fields */
+    [key: string]: unknown;
+}
+/**
+ * A single payment option in the accepts array
+ */
+interface PaymentAccept {
+    /** x402 version (1 or 2, defaults to 2 if not specified) */
+    x402Version?: 1 | 2;
+    /**
+     * Payment scheme: 'exact' for EIP-3009 chains, 'exact-approval' for
+     * approval-based chains like BSC, 'batch-settlement' for the EVM
+     * escrow-channel batching scheme (discrete API purchases, gas-amortized),
+     * 'tab' (SVM only) for streaming session-key vouchers against an
+     * on-chain vault.
+     */
+    scheme: 'exact' | 'exact-approval' | 'batch-settlement' | 'tab';
+    /** CAIP-2 network identifier (v1: 'solana', v2: 'solana:5eykt...') */
+    network: string;
+    /** Payment amount in atomic units (x402 v2 spec field) */
+    amount: string;
+    /** @deprecated v1 field — use `amount` instead. Kept for backwards compatibility with v1 data. */
+    maxAmountRequired?: string;
+    /** Token address */
+    asset: string;
+    /** Seller's address to receive payment */
+    payTo: string;
+    /** Maximum seconds until payment expires */
+    maxTimeoutSeconds: number;
+    /** Chain-specific extra data */
+    extra?: AcceptsExtra;
+}
+/**
+ * Full PaymentRequired structure (sent in PAYMENT-REQUIRED header)
+ */
+interface PaymentRequired {
+    /** x402 version (always 2) */
+    x402Version: 2;
+    /** Resource being accessed */
+    resource: ResourceInfo;
+    /** Available payment options */
+    accepts: PaymentAccept[];
+    /** Optional error message */
+    error?: string;
+    /** Protocol extensions */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Response from /verify endpoint
+ */
+interface VerifyResponse {
+    /** Whether the payment is valid */
+    isValid: boolean;
+    /** Reason for invalidity (if invalid) */
+    invalidReason?: string;
+    /** Payer address */
+    payer?: string;
+}
+/**
+ * Response from /settle endpoint
+ */
+interface SettleResponse {
+    /** Whether settlement succeeded */
+    success: boolean;
+    /** Transaction signature/hash */
+    transaction?: string;
+    /** Network the payment was made on */
+    network: string;
+    /** Error reason (if failed) */
+    errorReason?: string;
+    /** Error code (if failed) */
+    errorCode?: string;
+    /** Payer address */
+    payer?: string;
+    /** Protocol extensions returned by the facilitator (e.g., sponsored-access recommendations) */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * A single access pass tier offered by a seller
+ */
+interface AccessPassTier {
+    /** Tier ID (e.g., '1h', '24h') */
+    id: string;
+    /** Human-readable label (e.g., '1 hour') */
+    label: string;
+    /** Duration in seconds */
+    seconds: number;
+    /** Price in USD (e.g., '0.50') */
+    price: string;
+    /** Price in atomic units (e.g., '500000') */
+    priceAtomic: string;
+}
+/**
+ * Access pass info returned in X-ACCESS-PASS-TIERS header
+ */
+interface AccessPassInfo {
+    /** Available tiers (if tier-based pricing) */
+    tiers?: AccessPassTier[];
+    /** Rate per hour in USD (if custom duration pricing) */
+    ratePerHour?: string;
+    /** Pass issuer identifier */
+    issuer?: string;
+}
+/**
+ * JWT claims inside an access pass token
+ */
+interface AccessPassClaims {
+    /** Subject — always 'x402-access-pass' */
+    sub: string;
+    /** Tier ID or 'custom' */
+    tier: string;
+    /** Duration in seconds */
+    duration: number;
+    /** Issued at (unix seconds) */
+    iat: number;
+    /** Expires at (unix seconds) */
+    exp: number;
+    /** Payer wallet address */
+    payer: string;
+    /** Network used for payment */
+    network: string;
+    /** Issuer identifier */
+    iss: string;
+}
+/**
+ * Client-side access pass configuration
+ */
+interface AccessPassClientConfig {
+    /** Enable access pass mode (default: true when this config is present) */
+    enabled?: boolean;
+    /** Preferred tier ID (e.g., '1h') — pick this tier if available */
+    preferTier?: string;
+    /** Preferred custom duration in seconds (e.g., 3600) */
+    preferDuration?: number;
+    /** Maximum amount willing to spend in USD (e.g., '2.00') */
+    maxSpend?: string;
+    /** Auto-renew expired passes (default: true) */
+    autoRenew?: boolean;
+}
+/**
+ * SDK error codes
+ */
+type X402ErrorCode = 'missing_payment_required_header' | 'invalid_payment_required' | 'unsupported_network' | 'no_matching_payment_option' | 'missing_fee_payer' | 'missing_decimals' | 'missing_amount' | 'amount_exceeds_max' | 'insufficient_balance' | 'wallet_missing_sign_transaction' | 'wallet_not_connected' | 'wallet_disconnected' | 'user_rejected_signature' | 'transaction_build_failed' | 'payment_rejected' | 'rpc_timeout' | 'facilitator_timeout' | 'invalid_payment_signature' | 'facilitator_verify_failed' | 'facilitator_settle_failed' | 'facilitator_request_failed' | 'no_matching_requirement' | 'access_pass_expired' | 'access_pass_invalid' | 'access_pass_tier_not_found' | 'access_pass_exceeds_max_spend';
+/**
+ * Custom error class for x402 operations
+ */
+declare class X402Error extends Error {
+    /** Error code for programmatic handling */
+    code: X402ErrorCode;
+    /** Additional error details */
+    details?: unknown;
+    constructor(code: X402ErrorCode, message: string, details?: unknown);
+}
+
+export { type AccessPassClientConfig as A, type PaymentAccept as P, type ResourceInfo as R, type SettleResponse as S, type VerifyResponse as V, X402Error as X, type AccessPassInfo as a, type AccessPassTier as b, type PaymentRequired as c, type PayToProvider as d, type AccessPassClaims as e, type PayToContext as f, type PayToProviderDefaults as g };

package/dist/{types-JpkrtFbZ.d.cts → types-RauRuMb7.d.cts}

@@ -1,6 +1,6 @@
 import { RequestHandler } from 'express';
 import { ChannelStorage } from '@x402/evm/batch-settlement/server';
-import { b as CloseReceipt } from './types-BbvuPNXl.cjs';
+import { b as CloseReceipt } from './types-DGVtb7cl.cjs';
 
 /**
  * Result of closing one channel from the seller side. Either a settlement

package/docs/mcp.md

@@ -0,0 +1,98 @@
+# Paid MCP tools
+
+`@dexterai/x402/mcp` implements the published [x402 v2 MCP exchange](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/mcp.md). A seller returns payment requirements as a tool error, the buyer sends an object under `params._meta["x402/payment"]`, and the seller returns the receipt under `result._meta["x402/payment-response"]`.
+
+The adapters accept ordinary `tools/call` parameters and return complete tool results. Connect them to your MCP server or client through the transport you already use. Structured content, resources and unrelated metadata are retained.
+
+## Supported combinations
+
+| Component | Supported behavior |
+| --- | --- |
+| Wire helpers and buyer dispatch | x402 v2 object metadata binding; caller supplies an approved, signed payment |
+| Default facilitator processor | `exact` on explicitly configured EVM or Solana networks |
+| EVM proof forms | EIP-3009, or Permit2 with `extra.assetTransferMethod: "permit2"`; mixed forms are rejected |
+| Solana proof | Signed transaction with omitted `assetTransferMethod` or `"default"`, using the SPL transfer implementation |
+| Payment flow | Authorization followed by completed tool execution and settlement; omit `paymentFlow` or set it to `"authorization"` |
+| MCP lifecycle | Ordinary completed tool results, including July's `resultType: "complete"` when supplied by your transport |
+
+Other payment schemes need an explicit `McpPaymentProcessor` with a stable authorization identity and tested settlement behavior. Tabs, channel payments, upfront payments and escrow require their own lifecycle integration. The wrapper rejects task handles as completed delivery. MCP Tasks support belongs in the application that runs and stores the work.
+
+The maintained conformance tests exercise the published `@x402/mcp` 2.26.0 client over an MCP SDK in-memory transport. A second independently written peer tests complete result preservation. Those tests stub payment verification and settlement; deployment still needs a funded test for each advertised network and scheme.
+
+## Seller
+
+```ts
+import { createPaidMcpTool, createMcpFacilitatorProcessor } from '@dexterai/x402/mcp';
+
+const paidReport = createPaidMcpTool({
+  name: 'report',
+  serviceScope: 'reports.example/customer-reports',
+  requirements: {
+    x402Version: 2,
+    resource: { url: 'mcp://reports.example/tools/report' },
+    accepts: [{
+      scheme: 'exact', network: 'eip155:8453', amount: '10000',
+      asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+      payTo: sellerAddress, maxTimeoutSeconds: 60,
+      extra: { name: 'USD Coin', version: '2' },
+    }],
+  },
+  payments: createMcpFacilitatorProcessor({ networks: ['eip155:8453'] }),
+  store: durablePaymentStore,
+  authorize: async (_request, context) => requireCustomerAccount(context),
+  execute: async (request, { paymentId }) => {
+    const report = await buildReport(request.arguments, paymentId);
+    return { content: [{ type: 'text', text: report.summary }], structuredContent: report };
+  },
+});
+
+// In your server's tools/call handler, pass the complete params and auth context.
+return paidReport(call.params, authenticatedContext);
+```
+
+`durablePaymentStore`, authentication and `buildReport` are application dependencies. [The typed example](../examples/mcp-paid-tool.ts) makes those dependencies explicit. Your service owns its hosting, delivery and customer accounts.
+
+`authorize` runs before both execution and cached retrieval. Return a stable customer identity, and reject revoked access there. A deliberately public service can return a fixed access scope; this makes possession of the original payment proof sufficient to retrieve its cached result. Keep private services tied to authenticated accounts.
+
+All charge-affecting inputs belong in the tool arguments and advertised requirements. The first verified admission binds the payment to the service, arguments and caller. The x402 signature itself does not automatically sign arbitrary tool arguments.
+
+## Durable storage and recovery
+
+Implement `McpPaymentStore` against your database:
+
+- `claim` inserts the payment ID once atomically across every worker and paid tool sharing these payments. Use a uniqueness constraint; duplicate callers receive the existing record.
+- `compareAndSwap` updates only the expected revision and acknowledges success after durable commit. Persist output before settlement and the receipt before returning completion.
+- Protect records as private data. They contain payment proofs and outputs. Retain them for the payment's validity and your promised result-access period. Keep unresolved records until reconciliation completes.
+
+The package intentionally requires this store; it supplies no default memory store. Database outages stop new work before execution. An interrupted execution remains admitted. A settlement timeout, pending transaction or uncertain database acknowledgement requires reconciliation of that same operation. The wrapper avoids repeating execution or settlement automatically.
+
+After admission, errors return a recovery state under `dexter/payment-state`. They do not issue a fresh payment challenge, which could prompt another authorization. Pending receipts retain their transaction and extensions. A definite settlement failure also withholds the service output. Application recovery can inspect the saved result and original proof, reconcile the chain or provider, then commit the recovered result using the store's revision check.
+
+Successful duplicate requests return the saved result. The adapter rechecks authorization and binding, so another caller or changed arguments cannot retrieve it. Current price changes do not invalidate a completed purchase. The application can expose authenticated result retrieval using the same stored record without demanding another payment.
+
+Tool errors are saved without settlement. If the handler throws after making an external change, the operation remains unresolved for application recovery. Use the supplied payment ID to connect those external effects to the admitted work.
+
+## Buyer
+
+```ts
+import { probeMcpTool, callMcpToolWithPayment } from '@dexterai/x402/mcp';
+
+const request = { name: 'report', arguments: { ticker: 'ABC' } };
+const transport = params => connectedMcpClient.callTool(params);
+const probe = await probeMcpTool(transport, request);
+if (!probe.paymentRequired) return probe.result;
+
+const payment = await approveAndSign(probe.paymentRequired, request);
+const outcome = await callMcpToolWithPayment({
+  transport, request, paymentRequired: probe.paymentRequired, payment,
+  beforeDispatch: exactPaidRequest => journal.recordDispatch({
+    serverIdentity, exactPaidRequest, requirements: probe.paymentRequired,
+  }),
+});
+```
+
+The transport must remain connected to the selected server. The caller owns authorization, spend limits, signing, connection security and recording the server identity. An unpaid probe can execute a free tool; check the tool's semantics before probing.
+
+`callMcpToolWithPayment` waits for the durable hook and then makes one paid call. It reports payment and delivery separately. `seller_reported_settled` records the seller's receipt; independent chain verification remains the caller's responsibility. Missing receipts, malformed responses and `settlement_pending` remain unknown. Preserve the original operation for recovery rather than creating another authorization.
+
+Lower-level integrations can use `getMcpPaymentRequired`, `attachMcpPayment` and `getMcpPaymentReceipt` while retaining their own dispatch and recovery code. Resource information in a v2 proof is optional; when present, it must match the approved resource. The server always stores its authoritative resource and request binding.

package/examples/mcp-paid-tool.ts

@@ -0,0 +1,39 @@
+import {
+  createMcpFacilitatorProcessor, createPaidMcpTool,
+  type McpPaymentStore,
+} from '@dexterai/x402/mcp';
+
+interface CustomerContext { accountId?: string }
+
+/** Supply the application's existing durable store and report execution. */
+export function createReportTool(dependencies: {
+  sellerAddress: string;
+  store: McpPaymentStore;
+  requireAccount(context: CustomerContext): Promise<string>;
+  buildReport(arguments_: Record<string, unknown>, paymentId: string): Promise<{
+    summary: string;
+    sources: string[];
+  }>;
+}) {
+  return createPaidMcpTool<CustomerContext>({
+    name: 'report',
+    serviceScope: 'reports.example/customer-reports',
+    requirements: {
+      x402Version: 2,
+      resource: { url: 'mcp://reports.example/tools/report', mimeType: 'application/json' },
+      accepts: [{
+        scheme: 'exact', network: 'eip155:8453', amount: '10000',
+        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        payTo: dependencies.sellerAddress, maxTimeoutSeconds: 60,
+        extra: { name: 'USD Coin', version: '2' },
+      }],
+    },
+    payments: createMcpFacilitatorProcessor({ networks: ['eip155:8453'] }),
+    store: dependencies.store,
+    authorize: (_request, context) => dependencies.requireAccount(context),
+    execute: async (request, { paymentId }) => {
+      const report = await dependencies.buildReport(request.arguments ?? {}, paymentId);
+      return { content: [{ type: 'text', text: report.summary }], structuredContent: report };
+    },
+  });
+}

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@dexterai/x402",
-  "version": "6.0.0-rc.5",
+  "version": "6.0.0",
   "description": "Full-stack x402 SDK - add paid API monetization to any endpoint. Express middleware, React hooks, Access Pass, dynamic pricing. Solana, Base, Polygon, Arbitrum, Optimism, Avalanche, World Chain, Monad, Robinhood Chain, SKALE.",
   "author": "Dexter",
   "license": "MIT",
   "type": "module",
   "exports": {
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js",
+      "require": "./dist/mcp/index.cjs"
+    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js",
@@ -62,6 +67,8 @@
     "README.md",
     "REFERENCE.md",
     "CHANGELOG.md",
+    "docs/mcp.md",
+    "examples/mcp-paid-tool.ts",
     "LICENSE",
     "assets/*.svg"
   ],
@@ -73,10 +80,7 @@
     "test:watch": "vitest",
     "test:real": "echo 'Real payment tests require funded wallets. Run: npx tsx test/real-payment-solana.ts'",
     "prepublishOnly": "npm run build",
-    "release": "npm version patch && npm publish --access public",
-    "release:minor": "npm version minor && npm publish --access public",
-    "release:major": "npm version major && npm publish --access public",
-    "release:next": "npm publish --access public --tag next"
+    "verify:tab:package": "node scripts/verify-packed-tab.mjs"
   },
   "dependencies": {
     "@dexterai/x402-ads-types": "^0.2.0",
@@ -85,18 +89,20 @@
     "@noble/hashes": "^1.8.0",
     "@solana/spl-token": "^0.4.9",
     "@solana/web3.js": "^1.98.0",
-    "@x402/core": "2.12.0",
-    "@x402/evm": "2.12.0",
-    "@x402/extensions": "2.12.0",
+    "@x402/core": "2.26.0",
+    "@x402/evm": "2.26.0",
+    "@x402/extensions": "2.26.0",
     "bs58": "^6.0.0",
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {
-    "@dexterai/vault": "0.43.3-rc.1",
+    "@dexterai/vault": "0.43.4",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "@types/aws-lambda": "^8.10.161",
     "@types/express": "^5.0.6",
     "@types/node": "^22.10.0",
     "@types/react": "^18.0.0",
+    "@x402/mcp": "2.26.0",
     "ethers": "^6.13.0",
     "express": "^5.2.1",
     "react": "^18.0.0",
@@ -106,7 +112,7 @@
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@dexterai/vault": "0.43.3-rc.1",
+    "@dexterai/vault": "0.43.4",
     "@solana/wallet-adapter-base": "^0.9.0",
     "react": "^18.0.0 || ^19.0.0",
     "stripe": "^20.0.0",