T402 v2.8.0—Stellar support + 39 packages across 45 networks→
AdvancedMigration Guide (v2.2→v2.3)

Migration Guide: v2.2 to v2.3

This guide covers upgrading from T402 TypeScript SDK v2.2 to v2.3. The v2.3 release adds multi-chain support, a shared EVM utilities package, and enhanced WDK integration. There is one minor breaking change.

Quick Summary

Changev2.2v2.3
Chains supportedEVM, Solana, TON, TRON+ NEAR, Aptos, Tezos, Polkadot, Stacks, Cosmos
EVM shared utilsInline in @t402/evmExtracted to @t402/evm-core
Legacy USDTNot supported@t402/evm/exact-legacy for non-EIP-3009 tokens
WDK factorynew T402WDK(wdk)T402WDK.create() / T402WDK.fromWDK()
WDK swapNot availablecanSwap(), getSwapQuote(), swapAndPay()
Base tsconfigPer-package onlyShared tsconfig.base.json

New Packages

Mechanism Packages (v2.3.1)

Six new blockchain mechanism packages are available:

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)

All use the exact-direct scheme — the client executes the transfer on-chain, then provides the transaction hash as proof.

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

@t402/evm-core (v2.3.0)

Shared EVM utilities extracted from @t402/evm. If you only need EVM helpers without the full mechanism, you can import from here:

npm install @t402/evm-core

This package is a dependency of @t402/evm — no action required if you already use @t402/evm.

New Feature: EVM Exact-Legacy Scheme

v2.3 adds support for legacy USDT tokens that don’t implement EIP-3009 (e.g., on BNB Chain, Avalanche, Fantom, Celo, Kaia):

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

This uses standard ERC-20 approve + transferFrom instead of transferWithAuthorization.

WDK Changes

Factory Methods (Recommended)

v2.3.1 introduces static factory methods for T402WDK. The old constructor still works but the factory methods are recommended:

// 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);

Multi-Chain Signer Discovery

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

Swap Integration

// 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);

Breaking Change

as const Arrays in Type Definitions

If you extend T402 types that use as const arrays, you may need to update your code:

// 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);
}

This only affects code that calls .includes() on as const arrays. Most users won’t be impacted.

Version Compatibility

Packagev2.2v2.3.0v2.3.1
@t402/core2.2.02.3.02.3.1
@t402/evm2.2.02.3.02.3.1
@t402/wdk2.2.02.3.02.3.1
WDK SDKbeta.4beta.5beta.5
wallet-evm1.x2.0.0-rc.12.0.0-rc.1

Upgrading

# 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

No code changes are required unless you hit the as const breaking change above. All existing v2.2 code is compatible with v2.3.

Need Help?

Migration Guide (v1→v2)