Migration Guides

# Remove old packages
npm uninstall x402-core x402-express x402-fetch x402-evm
 
# Install new packages
npm install @t402/core @t402/express @t402/fetch @t402/evm

// v1
import { PaymentRequirements } from "x402-core";
import { createExactEvmScheme } from "x402-evm";
 
// v2
import { PaymentRequirements } from "@t402/core";
import { ExactEvmScheme } from "@t402/evm";

// v1
const network = "base-sepolia";
const network = "ethereum";
const network = "arbitrum";
 
// v2
const network = "eip155:84532";  // Base Sepolia
const network = "eip155:1";       // Ethereum Mainnet
const network = "eip155:42161";   // Arbitrum One

// v1
const requirements: PaymentRequirementsV1 = {
  scheme: "exact",
  network: "base-sepolia",
  maxAmountRequired: "1000000",  // 1 USDC
  resource: "https://api.example.com/data",
  description: "Premium API access",
  mimeType: "application/json",
  outputSchema: {},
  payTo: "0x...",
  maxTimeoutSeconds: 60,
  asset: "0x...",
  extra: {}
};

// v2
const requirements: PaymentRequirements = {
  scheme: "exact",
  network: "eip155:84532",
  amount: "1000000",  // Renamed from maxAmountRequired
  payTo: "0x...",
  maxTimeoutSeconds: 60,
  asset: "0x...",
  extra: {}
};
 
const paymentRequired: PaymentRequired = {
  t402Version: 2,
  resource: {
    url: "https://api.example.com/data",
    description: "Premium API access",
    mimeType: "application/json"
  },
  accepts: [requirements],
  extensions: {}  // New in v2
};

// v1
const payload: PaymentPayloadV1 = {
  t402Version: 1,
  scheme: "exact",
  network: "base-sepolia",
  payload: {
    signature: "0x...",
    // scheme-specific fields
  }
};

// v2
const payload: PaymentPayload = {
  t402Version: 2,
  resource: {
    url: "https://api.example.com/data",
    description: "Premium API access",
    mimeType: "application/json"
  },
  accepted: {
    scheme: "exact",
    network: "eip155:84532",
    amount: "1000000",
    asset: "0x...",
    payTo: "0x...",
    maxTimeoutSeconds: 60,
    extra: {}
  },
  payload: {
    signature: "0x...",
    // scheme-specific fields
  },
  extensions: {}
};

// v1 - Request
headers["X-PAYMENT"] = encodedPayload;
 
// v2 - Request
headers["PAYMENT-SIGNATURE"] = encodedPayload;
 
// v1 - Response
headers["X-PAYMENT-RESPONSE"] = encodedResponse;
 
// v2 - Response
headers["PAYMENT-RESPONSE"] = encodedResponse;

// Server reads both formats
const header = adapter.getHeader("payment-signature")
  || adapter.getHeader("x-payment");
 
// Client sends v2 header, server accepts both

// v1
import { createPaymentMiddleware } from "x402-express";
 
app.use("/api", createPaymentMiddleware({
  requirements: {
    scheme: "exact",
    network: "base-sepolia",
    maxAmountRequired: "1000000",
    // ...flat structure
  }
}));
 
// v2
import { t402Middleware } from "@t402/express";
 
app.use("/api", t402Middleware({
  routes: {
    "/premium": {
      price: "1.00",  // Human-readable, auto-converted
      payTo: "0x...",
      network: "eip155:84532",
      asset: "0x..."
    }
  },
  facilitator: "https://facilitator.t402.io"
}));

// v1
import { createPaymentClient } from "x402-fetch";
 
const client = createPaymentClient({
  wallet: privateKey,
  network: "base-sepolia"
});
 
// v2
import { t402Fetch, createEvmWallet } from "@t402/fetch";
 
const wallet = createEvmWallet(privateKey);
const response = await t402Fetch("https://api.example.com/data", {
  wallet,
  network: "eip155:84532"
});

// v1
const verifyRequest: VerifyRequestV1 = {
  paymentPayload: payload,
  paymentRequirements: requirements  // Flat structure
};
 
// v2
const verifyRequest: VerifyRequest = {
  paymentPayload: payload,
  paymentRequirements: requirements,
  resource: resourceInfo
};

// v1 - No extensions
const supported: SupportedResponseV1 = {
  kinds: [
    { t402Version: 1, scheme: "exact", network: "base-sepolia" }
  ]
};
 
// v2 - With extensions
const supported: SupportedResponse = {
  kinds: [
    { t402Version: 2, scheme: "exact", network: "eip155:84532" }
  ],
  extensions: {
    bazaar: { enabled: true },
    siwx: { enabled: true }
  }
};

import { BazaarExtension, SIWXExtension } from "@t402/extensions";
 
// Server advertises extensions
const paymentRequired: PaymentRequired = {
  t402Version: 2,
  resource: { /* ... */ },
  accepts: [/* ... */],
  extensions: {
    bazaar: {
      info: { discoveryUrl: "https://api.example.com/.well-known/bazaar" },
      schema: { /* JSON Schema */ }
    }
  }
};
 
// Client echoes extensions
const payload: PaymentPayload = {
  t402Version: 2,
  // ...
  extensions: {
    bazaar: {
      info: { /* ... */ }
    }
  }
};

Error: Unknown network: base-sepolia

// Wrong
network: "base-sepolia"
 
// Correct
network: "eip155:84532"

Error: PaymentRequired.resource is required

const paymentRequired = {
  t402Version: 2,
  resource: {
    url: "https://api.example.com/data",
    description: "API access",
    mimeType: "application/json"
  },
  accepts: [/* ... */]
};

Error: amount is required

// Wrong
{ maxAmountRequired: "1000000" }
 
// Correct
{ amount: "1000000" }

import { PaymentRequiredV1 } from "@t402/core/v1";
import { PaymentRequired } from "@t402/core";
 
function createPaymentRequired(config) {
  // v2 format (default)
  const v2: PaymentRequired = {
    t402Version: 2,
    resource: {
      url: config.resource,
      description: config.description,
      mimeType: config.mimeType
    },
    accepts: [{
      scheme: config.scheme,
      network: config.network,
      amount: config.amount,
      // ...
    }]
  };
 
  // v1 format (legacy support)
  const v1: PaymentRequiredV1 = {
    t402Version: 1,
    accepts: [{
      scheme: config.scheme,
      network: convertToLegacyNetwork(config.network),
      maxAmountRequired: config.amount,
      resource: config.resource,
      description: config.description,
      mimeType: config.mimeType,
      // ...
    }]
  };
 
  return { v1, v2 };
}

npm install @t402/near      # NEAR Protocol (NEP-141)
npm install @t402/aptos     # Aptos (Fungible Asset)
npm install @t402/tezos     # Tezos (FA2 / TZIP-12)
npm install @t402/polkadot  # Polkadot Asset Hub
npm install @t402/stacks    # Stacks (Bitcoin L2)
npm install @t402/cosmos    # Cosmos (Noble USDC)

// Example: NEAR payment client
import { createExactDirectNearClient } from "@t402/near/exact-direct/client";
 
const client = createExactDirectNearClient({ signer: myNearSigner });
const payload = await client.createPaymentPayload(2, requirements);

npm install @t402/evm-core

import { ExactLegacyEvmClient } from "@t402/evm/exact-legacy/client";
import { ExactLegacyEvmFacilitator } from "@t402/evm/exact-legacy/facilitator";

// v2.2 (still works)
import { T402WDK } from "@t402/wdk";
const t402 = new T402WDK(wdkInstance);
 
// v2.3 (recommended)
import { T402WDK } from "@t402/wdk";
 
// Create with full configuration
const t402 = await T402WDK.create({
  wdk: wdkInstance,
  network: "eip155:8453",
});
 
// Quick setup from existing WDK
const t402 = T402WDK.fromWDK(wdkInstance);

// New in v2.3.1
const signers = await t402.getAllSigners();
// Returns signers for all available chains

// New in v2.3.1
const canDoSwap = await t402.canSwap("eip155:8453");
const quote = await t402.getSwapQuote({
  fromAsset: "0x...",
  toAsset: "0x...",
  amount: "1000000",
});
const result = await t402.swapAndPay(requirements, quote);

// v2.2 -- worked
const NETWORKS = ["eip155:1", "eip155:8453"] as const;
function isSupported(n: string) {
  return NETWORKS.includes(n); // Error in v2.3
}
 
// v2.3 -- fix
function isSupported(n: string) {
  return (NETWORKS as readonly string[]).includes(n);
}

# Update all T402 packages
npm update @t402/core @t402/evm @t402/wdk
 
# Or update everything at once
npx npm-check-updates -f '@t402/*' -u && npm install