@ic-pay/icpay-sdk 1.3.95 → 1.4.12

package/dist/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IcpayWallet = exports.IcpayError = exports.Icpay = void 0;
+const builders_1 = require("./x402/builders");
 const errors_1 = require("./errors");
 const events_1 = require("./events");
 const wallet_1 = require("./wallet");
@@ -32,6 +33,7 @@ class Icpay {
         this.icpayCanisterId = null;
         this.accountInfoCache = null;
         this.verifiedLedgersCache = { data: null, timestamp: 0 };
+        this.chainsCache = { data: null, timestamp: 0 };
         this.icpLedgerCanisterId = 'ryjl3-tyaaa-aaaaa-aaaba-cai';
         this.config = {
             environment: 'production',
@@ -193,7 +195,9 @@ class Icpay {
                 id: ledger.id,
                 name: ledger.name,
                 symbol: ledger.symbol,
+                shortcode: ledger.shortcode ?? null,
                 canisterId: ledger.canisterId,
+                chainId: ledger.chainId,
                 decimals: ledger.decimals,
                 logoUrl: ledger.logoUrl,
                 verified: ledger.verified,
@@ -219,6 +223,45 @@ class Icpay {
             throw err;
         }
     }
+    /**
+     * Get enabled chains (public method)
+     */
+    async getChains() {
+        this.emitMethodStart('getChains');
+        const now = Date.now();
+        const cacheAge = 60 * 60 * 1000; // 60 minutes cache
+        if (this.chainsCache.data && (now - this.chainsCache.timestamp) < cacheAge) {
+            return this.chainsCache.data;
+        }
+        try {
+            const resp = await this.publicApiClient.get('/sdk/public/chains');
+            const chains = resp.map((c) => ({
+                id: c.id,
+                chainType: c.chainType,
+                chainName: c.chainName,
+                chainId: c.chainId,
+                shortcode: c.shortcode ?? null,
+                contractAddress: c.contractAddress ?? null,
+                enabled: !!c.enabled,
+                rpcUrlPublic: c.rpcUrlPublic ?? null,
+                explorerUrl: c.explorerUrl ?? null,
+                nativeSymbol: c.nativeSymbol ?? null,
+                confirmationsRequired: typeof c.confirmationsRequired === 'number' ? c.confirmationsRequired : parseInt(String(c.confirmationsRequired || 0), 10) || 0,
+            }));
+            this.chainsCache = { data: chains, timestamp: now };
+            this.emitMethodSuccess('getChains', { count: chains.length });
+            return chains;
+        }
+        catch (error) {
+            const err = new errors_1.IcpayError({
+                code: errors_1.ICPAY_ERROR_CODES.API_ERROR,
+                message: 'Failed to fetch chains',
+                details: error,
+            });
+            this.emitMethodError('getChains', err);
+            throw err;
+        }
+    }
     /**
      * Get a verified ledger's canister ID by its symbol (public helper)
      */
@@ -292,6 +335,375 @@ class Icpay {
             });
         }
     }
+    async processPaymentByChain(params) {
+        const normalized = (params.chainType || '').toLowerCase();
+        switch (normalized) {
+            case 'ic':
+            case 'icp':
+            case 'internet-computer':
+                return await this.processICPayment(params);
+            case 'evm':
+            case 'ethereum':
+                return await this.processEvmPayment(params);
+            case 'solana':
+                throw new errors_1.IcpayError({
+                    code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
+                    message: 'Solana payments are not implemented yet',
+                    details: { chainType: params.chainType, chainId: params.chainId }
+                });
+            case 'sui':
+                throw new errors_1.IcpayError({
+                    code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
+                    message: 'Sui payments are not implemented yet',
+                    details: { chainType: params.chainType, chainId: params.chainId }
+                });
+            case 'onramp':
+                return {
+                    transactionId: 0,
+                    status: 'pending',
+                    amount: params.resolvedAmountStr || params.amount.toString(),
+                    recipientCanister: params.ledgerCanisterId,
+                    timestamp: new Date(),
+                    metadata: { paymentIntentId: params.paymentIntentId, onramp: params.onrampData || true },
+                };
+            default:
+                throw new errors_1.IcpayError({
+                    code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
+                    message: 'Unknown or missing chain type for payment processing',
+                    details: { chainType: params.chainType, chainId: params.chainId }
+                });
+        }
+    }
+    // Public helper: build EVM bytes32 id from accountId and intentCode
+    // Layout matches PaymentProcessor.packId(accountId, appId):
+    // high 8 bytes = uint64(accountId) big-endian; low 24 bytes = bytes24 with intentCode in the lowest 4 bytes (big-endian)
+    packEvmId(accountCanisterId, intentCode) {
+        const accountIdNum = BigInt(accountCanisterId);
+        const intentCodeNum = BigInt(intentCode);
+        const out = new Uint8Array(32);
+        // high 8 bytes (big-endian) accountId
+        for (let i = 0; i < 8; i++) {
+            out[i] = Number((accountIdNum >> BigInt(8 * (7 - i))) & 0xffn);
+        }
+        // next 20 bytes are zero
+        // last 4 bytes = intentCode big-endian
+        out[28] = Number((intentCodeNum >> 24n) & 0xffn);
+        out[29] = Number((intentCodeNum >> 16n) & 0xffn);
+        out[30] = Number((intentCodeNum >> 8n) & 0xffn);
+        out[31] = Number(intentCodeNum & 0xffn);
+        const bytesToHex = (u) => Array.from(u).map(b => b.toString(16).padStart(2, '0')).join('');
+        return bytesToHex(out);
+    }
+    async processICPayment(params) {
+        const { ledgerCanisterId, amount, memo, paymentIntentId, request, metadata } = params;
+        // Prefer contractAddress from intent (for IC, this is the canister id)
+        let toPrincipal = (params.contractAddress && typeof params.contractAddress === 'string') ? params.contractAddress : undefined;
+        const host = this.icHost;
+        if (!toPrincipal) {
+            if (!this.icpayCanisterId) {
+                await this.fetchAccountInfo();
+            }
+            if (!this.icpayCanisterId) {
+                try {
+                    const acct = await this.getAccountInfo();
+                    if (acct?.icpayCanisterId) {
+                        this.icpayCanisterId = acct.icpayCanisterId.toString();
+                    }
+                }
+                catch { }
+            }
+            if (!this.icpayCanisterId || typeof this.icpayCanisterId !== 'string') {
+                const err = new errors_1.IcpayError({
+                    code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
+                    message: 'Could not resolve ICPay canister ID from account info',
+                    details: { accountInfoCache: this.accountInfoCache }
+                });
+                this.emitMethodError('createPayment', err);
+                throw err;
+            }
+            toPrincipal = this.icpayCanisterId;
+        }
+        this.icpayCanisterId = toPrincipal;
+        // Ensure Plug has whitelisted the target application canister before initiating transfer
+        try {
+            const isBrowser = typeof window !== 'undefined';
+            const appCanisterId = (typeof toPrincipal === 'string' && toPrincipal.trim().length > 0) ? toPrincipal : null;
+            if (isBrowser && appCanisterId && window?.ic?.plug?.requestConnect) {
+                await window.ic.plug.requestConnect({ host, whitelist: [appCanisterId] });
+            }
+        }
+        catch {
+            // Non-fatal; continue even if whitelist step fails (wallet may already trust canister)
+        }
+        let transferResult;
+        try {
+            // ICP Ledger: use ICRC-1 transfer (ICP ledger supports ICRC-1)
+            (0, utils_1.debugLog)(this.config.debug || false, 'sending ICRC-1 transfer (ICP)');
+            transferResult = await this.sendFundsToLedger(ledgerCanisterId, toPrincipal, amount, memo, host);
+        }
+        catch (transferError) {
+            // Some wallets/networks return a timeout or transient 5xx even when the transfer was accepted.
+            // Treat these as processing and continue with intent notification so users don't double-send.
+            const msg = String(transferError?.message || '');
+            const lower = msg.toLowerCase();
+            const isTimeout = lower.includes('request timed out');
+            const isProcessing = isTimeout && lower.includes('processing');
+            // DFINITY HTTP agent transient error when subnet has no healthy nodes (e.g., during upgrade)
+            const isNoHealthyNodes = lower.includes('no_healthy_nodes') || lower.includes('service unavailable') || lower.includes('503');
+            // Plug inpage transport sometimes throws readState errors after a signed call even though the tx went through
+            const isPlugReadState = lower.includes('read state request') || lower.includes('readstate') || lower.includes('response could not be found');
+            if (isTimeout || isProcessing || isNoHealthyNodes || isPlugReadState) {
+                (0, utils_1.debugLog)(this.config.debug || false, 'transfer timed out, proceeding with intent notification', { message: msg });
+                // Long-poll the public notify endpoint using only the intent id (no canister tx id available)
+                const publicNotify = await this.performNotifyPaymentIntent({
+                    paymentIntentId: paymentIntentId,
+                    maxAttempts: 120,
+                    delayMs: 1000,
+                });
+                // Derive status from API response
+                let statusString = 'pending';
+                const apiStatus = publicNotify?.paymentIntent?.status || publicNotify?.payment?.status || publicNotify?.status;
+                if (typeof apiStatus === 'string') {
+                    const norm = apiStatus.toLowerCase();
+                    if (norm === 'completed' || norm === 'succeeded')
+                        statusString = 'completed';
+                    else if (norm === 'failed' || norm === 'canceled' || norm === 'cancelled')
+                        statusString = 'failed';
+                }
+                const response = {
+                    transactionId: 0,
+                    status: statusString,
+                    amount: amount.toString(),
+                    recipientCanister: ledgerCanisterId,
+                    timestamp: new Date(),
+                    description: 'Fund transfer',
+                    metadata: request.metadata,
+                    payment: publicNotify,
+                };
+                if (statusString === 'completed') {
+                    const requested = publicNotify?.payment?.requestedAmount || null;
+                    const paid = publicNotify?.payment?.paidAmount || null;
+                    const isMismatched = publicNotify?.payment?.status === 'mismatched';
+                    if (isMismatched) {
+                        this.emit('icpay-sdk-transaction-mismatched', { ...response, requestedAmount: requested, paidAmount: paid });
+                        this.emit('icpay-sdk-transaction-updated', { ...response, status: 'mismatched', requestedAmount: requested, paidAmount: paid });
+                    }
+                    else {
+                        this.emit('icpay-sdk-transaction-completed', response);
+                    }
+                }
+                else if (statusString === 'failed') {
+                    this.emit('icpay-sdk-transaction-failed', response);
+                }
+                else {
+                    this.emit('icpay-sdk-transaction-updated', response);
+                }
+                return response;
+            }
+            throw transferError;
+        }
+        // Assume transferResult returns a block index or transaction id
+        const blockIndex = transferResult?.Ok?.toString() || transferResult?.blockIndex?.toString() || `temp-${Date.now()}`;
+        (0, utils_1.debugLog)(this.config.debug || false, 'transfer result', { blockIndex });
+        // First, notify the canister about the ledger transaction (best-effort)
+        let canisterTransactionId;
+        try {
+            (0, utils_1.debugLog)(this.config.debug || false, 'notifying canister about ledger tx', { icpayCanisterId: this.icpayCanisterId, ledgerCanisterId, blockIndex });
+            const notifyRes = await this.notifyLedgerTransaction(this.icpayCanisterId, ledgerCanisterId, BigInt(blockIndex));
+            if (typeof notifyRes === 'string') {
+                const parsed = parseInt(notifyRes, 10);
+                canisterTransactionId = Number.isFinite(parsed) ? parsed : undefined;
+            }
+            else if (notifyRes && typeof notifyRes.id !== 'undefined') {
+                const parsed = parseInt(String(notifyRes.id), 10);
+                canisterTransactionId = Number.isFinite(parsed) ? parsed : undefined;
+            }
+            else {
+                canisterTransactionId = undefined;
+            }
+            (0, utils_1.debugLog)(this.config.debug || false, 'canister notified', { canisterTransactionId });
+        }
+        catch (notifyError) {
+            // Do not fall back to ledger block index as canister tx id; let API resolve by intent id
+            canisterTransactionId = undefined;
+            (0, utils_1.debugLog)(this.config.debug || false, 'notify failed; proceeding without canister tx id', { error: notifyError?.message });
+        }
+        // Durable wait until API returns terminal status (completed/mismatched/failed/canceled)
+        const finalResponse = await this.awaitIntentTerminal({
+            paymentIntentId: paymentIntentId,
+            canisterTransactionId: (typeof canisterTransactionId === 'number' && Number.isFinite(canisterTransactionId)) ? String(canisterTransactionId) : undefined,
+            ledgerCanisterId: ledgerCanisterId,
+            amount: amount.toString(),
+            metadata: metadata ?? request.metadata,
+        });
+        return finalResponse;
+    }
+    async processEvmPayment(params) {
+        const contractAddress = params.contractAddress;
+        if (!contractAddress) {
+            throw new errors_1.IcpayError({
+                code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
+                message: 'Missing EVM contract address in payment intent',
+            });
+        }
+        const eth = this.config?.evmProvider || globalThis?.ethereum || (typeof window !== 'undefined' ? window.ethereum : null);
+        if (!eth || !eth.request) {
+            throw new errors_1.IcpayError({
+                code: errors_1.ICPAY_ERROR_CODES.WALLET_PROVIDER_NOT_AVAILABLE,
+                message: 'EVM provider not available (window.ethereum)',
+            });
+        }
+        // Ensure correct chain if provided
+        try {
+            const desiredChain = params.rpcChainId ?? null;
+            if (desiredChain != null) {
+                const currentHex = await eth.request({ method: 'eth_chainId' });
+                const currentDec = parseInt(currentHex, 16);
+                const desiredDec = typeof desiredChain === 'string' && String(desiredChain).startsWith('0x') ? parseInt(String(desiredChain), 16) : parseInt(String(desiredChain), 10);
+                if (Number.isFinite(desiredDec) && currentDec !== desiredDec) {
+                    const hex = '0x' + desiredDec.toString(16);
+                    try {
+                        await eth.request({ method: 'wallet_switchEthereumChain', params: [{ chainId: hex }] });
+                    }
+                    catch (e) {
+                        // best-effort add & switch if we have chainName/rpcUrlPublic
+                        const rpcUrls = (params.rpcUrlPublic ? [String(params.rpcUrlPublic)] : []).filter(Boolean);
+                        const chainName = String(params.chainName || `Network ${desiredDec}`);
+                        if (rpcUrls.length > 0) {
+                            try {
+                                await eth.request({
+                                    method: 'wallet_addEthereumChain',
+                                    params: [{ chainId: hex, chainName, rpcUrls }],
+                                });
+                            }
+                            catch (e2) {
+                                throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG, message: 'Wrong EVM network. Switch wallet to the correct chain.' });
+                            }
+                        }
+                        else {
+                            throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG, message: 'Wrong EVM network. Switch wallet to the correct chain.' });
+                        }
+                    }
+                }
+            }
+        }
+        catch { }
+        const tokenAddress = params.ledgerCanisterId || null;
+        const isNative = !tokenAddress || /^0x0{40}$/i.test(String(tokenAddress));
+        const amountHex = '0x' + params.amount.toString(16);
+        // ABI encoding helpers
+        const toUint64 = (n) => n.toString(16).padStart(64, '0');
+        const toAddressPadded = (addr) => addr.replace(/^0x/i, '').padStart(64, '0');
+        const toUint256 = (n) => n.toString(16).padStart(64, '0');
+        // Prefer selectors from API; otherwise fallback to constants provided by backend
+        const apiSelectors = params.request.__functionSelectors || {};
+        const selector = {
+            payNative: apiSelectors.payNative || '0x320ca36d',
+            payERC20: apiSelectors.payERC20 || '0x1d8be466',
+        };
+        // Build EVM id bytes32 using shared helper
+        const accountIdNum = BigInt(params.accountCanisterId || 0);
+        const idHex = this.packEvmId(String(accountIdNum), Number(params.paymentIntentCode ?? 0));
+        // Debug: summarize EVM call parameters
+        try {
+            (0, utils_1.debugLog)(this.config.debug || false, 'evm params', {
+                chainId: params.chainId,
+                contractAddress,
+                tokenAddress,
+                isNative,
+                amount: params.amount?.toString?.(),
+                amountHex,
+                accountCanisterId: params.accountCanisterId,
+                memoLen: params.memo?.length,
+                idHexLen: idHex?.length,
+                selectorPayNative: selector.payNative,
+                selectorPayERC20: selector.payERC20,
+            });
+        }
+        catch { }
+        // Helper to poll receipt until mined or timeout
+        const waitForReceipt = async (hash, attempts = 60, delayMs = 1000) => {
+            for (let i = 0; i < attempts; i++) {
+                try {
+                    const receipt = await eth.request({ method: 'eth_getTransactionReceipt', params: [hash] });
+                    if (receipt && receipt.blockNumber)
+                        return receipt;
+                }
+                catch { }
+                await new Promise(r => setTimeout(r, delayMs));
+            }
+            return null;
+        };
+        let txHash;
+        try {
+            // Resolve owner (from address) once for all EVM calls
+            const accounts = await eth.request({ method: 'eth_requestAccounts' });
+            const lowerAccounts = Array.isArray(accounts) ? accounts.map((a) => String(a).toLowerCase()) : [];
+            const provided = (params.request?.expectedSenderPrincipal || '').toString().toLowerCase();
+            let owner = '';
+            if (provided && lowerAccounts.includes(provided)) {
+                owner = accounts[lowerAccounts.indexOf(provided)] || '';
+            }
+            else {
+                owner = (accounts && accounts[0]) || '';
+            }
+            if (!owner)
+                throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.WALLET_NOT_CONNECTED, message: 'EVM wallet not connected' });
+            (0, utils_1.debugLog)(this.config.debug || false, 'evm from account', { owner });
+            if (isNative) {
+                const data = selector.payNative + idHex + toUint64(accountIdNum);
+                (0, utils_1.debugLog)(this.config.debug || false, 'evm native tx', { to: contractAddress, from: owner, dataLen: data.length, value: amountHex });
+                txHash = await eth.request({ method: 'eth_sendTransaction', params: [{ from: owner, to: contractAddress, data, value: amountHex }] });
+            }
+            else {
+                // Ensure allowance(owner -> spender=contractAddress)
+                const allowanceSelector = '0xdd62ed3e'; // allowance(address,address)
+                const approveSelector = '0x095ea7b3'; // approve(address,uint256)
+                const allowanceData = allowanceSelector + toAddressPadded(owner) + toAddressPadded(contractAddress);
+                (0, utils_1.debugLog)(this.config.debug || false, 'evm erc20 allowance', { owner, spender: contractAddress, token: tokenAddress, data: allowanceData });
+                let allowanceHex = await eth.request({ method: 'eth_call', params: [{ to: String(tokenAddress), data: allowanceData }, 'latest'] });
+                if (typeof allowanceHex === 'string' && allowanceHex.startsWith('0x')) {
+                    const allowance = BigInt(allowanceHex);
+                    (0, utils_1.debugLog)(this.config.debug || false, 'evm erc20 allowance result', { allowance: allowance.toString() });
+                    if (allowance < params.amount) {
+                        const approveData = approveSelector + toAddressPadded(contractAddress) + toUint256(params.amount);
+                        (0, utils_1.debugLog)(this.config.debug || false, 'evm erc20 approve', { to: tokenAddress, from: owner, dataLen: approveData.length, amount: params.amount.toString() });
+                        const approveTx = await eth.request({ method: 'eth_sendTransaction', params: [{ from: owner, to: String(tokenAddress), data: approveData }] });
+                        (0, utils_1.debugLog)(this.config.debug || false, 'evm erc20 approve sent', { tx: approveTx });
+                        await waitForReceipt(approveTx, 90, 1000);
+                    }
+                }
+                const data = selector.payERC20 + idHex + toUint64(accountIdNum) + toAddressPadded(String(tokenAddress)) + toUint256(params.amount);
+                (0, utils_1.debugLog)(this.config.debug || false, 'evm erc20 pay', { to: contractAddress, from: owner, token: tokenAddress, dataLen: data.length });
+                txHash = await eth.request({ method: 'eth_sendTransaction', params: [{ from: owner, to: contractAddress, data }] });
+            }
+        }
+        catch (e) {
+            try {
+                (0, utils_1.debugLog)(this.config.debug || false, 'evm tx error', { message: e?.message, code: e?.code, data: e?.data, error: e });
+            }
+            catch { }
+            throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.TRANSACTION_FAILED, message: 'EVM transaction failed', details: e });
+        }
+        // Notify API with tx hash and wait for terminal status
+        try {
+            this.emitMethodSuccess('notifyLedgerTransaction', { paymentIntentId: params.paymentIntentId });
+        }
+        catch { }
+        // Inform API immediately with tx hash so it can start indexing
+        try {
+            await this.performNotifyPaymentIntent({ paymentIntentId: params.paymentIntentId, transactionId: txHash, maxAttempts: 1 });
+        }
+        catch { }
+        const finalResponse = await this.awaitIntentTerminal({
+            paymentIntentId: params.paymentIntentId,
+            transactionId: txHash,
+            ledgerCanisterId: params.ledgerCanisterId,
+            amount: params.amount.toString(),
+            metadata: { ...(params.metadata || {}), evmTxHash: txHash },
+        });
+        return finalResponse;
+    }
     /**
      * Show wallet connection modal
      */
@@ -424,182 +836,52 @@ class Icpay {
         this.emitMethodStart('createPayment', { request: { ...request, amount: typeof request.amount === 'string' ? request.amount : String(request.amount) } });
         try {
             (0, utils_1.debugLog)(this.config.debug || false, 'createPayment start', { request });
-            // Resolve ledgerCanisterId from symbol if needed
+            // Resolve ledgerCanisterId from symbol if needed (legacy). If tokenShortcode provided, no resolution required.
             let ledgerCanisterId = request.ledgerCanisterId;
-            if (!ledgerCanisterId && request.symbol) {
-                ledgerCanisterId = await this.getLedgerCanisterIdBySymbol(request.symbol);
-            }
-            if (!ledgerCanisterId) {
+            const tokenShortcode = request?.tokenShortcode;
+            if (!ledgerCanisterId && !tokenShortcode && !request.symbol) {
                 const err = new errors_1.IcpayError({
                     code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
-                    message: 'Either ledgerCanisterId or symbol must be provided',
+                    message: 'Provide either tokenShortcode or ledgerCanisterId (symbol is deprecated).',
                     details: { request }
                 });
                 this.emitMethodError('createPayment', err);
                 throw err;
             }
-            // Fetch account info to get accountCanisterId if not provided
-            let accountCanisterId = request.accountCanisterId;
-            if (!accountCanisterId) {
-                (0, utils_1.debugLog)(this.config.debug || false, 'fetching account info for accountCanisterId');
-                const accountInfo = await this.getAccountInfo();
-                accountCanisterId = accountInfo.accountCanisterId.toString();
-                (0, utils_1.debugLog)(this.config.debug || false, 'accountCanisterId resolved', { accountCanisterId });
-            }
-            // Always use icpayCanisterId as toPrincipal
-            if (!this.icpayCanisterId) {
-                await this.fetchAccountInfo();
-            }
-            // Fallback: try public getAccountInfo if still missing
-            if (!this.icpayCanisterId) {
-                try {
-                    const acct = await this.getAccountInfo();
-                    if (acct?.icpayCanisterId) {
-                        this.icpayCanisterId = acct.icpayCanisterId.toString();
-                    }
-                }
-                catch { }
-            }
-            if (!this.icpayCanisterId || typeof this.icpayCanisterId !== 'string') {
-                const err = new errors_1.IcpayError({
-                    code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
-                    message: 'Could not resolve ICPay canister ID from account info',
-                    details: { accountInfoCache: this.accountInfoCache }
-                });
-                this.emitMethodError('createPayment', err);
-                throw err;
-            }
-            const toPrincipal = this.icpayCanisterId;
-            const host = this.icHost;
             let memo = undefined;
-            // If onrampPayment is enabled (request or global config), branch to onramp flow
-            const onramp = (request.onrampPayment === true || this.config.onrampPayment === true) && this.config.onrampDisabled !== true ? true : false;
-            if (onramp) {
-                // Only ICP ledger is allowed for onramp
-                if (ledgerCanisterId !== this.icpLedgerCanisterId) {
-                    const err = new errors_1.IcpayError({
-                        code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
-                        message: 'Onramp is only supported for ICP ledger',
-                        details: { provided: ledgerCanisterId, expected: this.icpLedgerCanisterId },
-                    });
-                    this.emitError(err);
-                    throw err;
-                }
-                // Ensure amountUsd is provided or compute it
-                let amountUsd = request.amountUsd;
-                if (amountUsd == null) {
-                    try {
-                        const res = await this.calculateTokenAmountFromUSD({
-                            usdAmount: 1, // placeholder to fetch price
-                            ledgerCanisterId,
-                        });
-                        // If price is P = USD per token, then amountUsd = amountTokens * P
-                        const price = res.currentPrice;
-                        const tokenAmount = typeof request.amount === 'string' ? Number(request.amount) : Number(request.amount);
-                        amountUsd = price * (tokenAmount / Math.pow(10, res.decimals));
-                    }
-                    catch { }
-                }
-                // Create payment intent directly (without requiring connected wallet), flagging onrampPayment
-                let paymentIntentId = null;
-                let paymentIntentCode = null;
-                try {
-                    (0, utils_1.debugLog)(this.config.debug || false, 'creating onramp payment intent');
-                    const intentResp = await this.publicApiClient.post('/sdk/public/payments/intents', {
-                        amount: request.amount,
-                        symbol: request.symbol,
-                        ledgerCanisterId,
-                        // expectedSenderPrincipal omitted in onramp
-                        metadata: request.metadata || {},
-                        onrampPayment: true,
-                        widgetParams: request.widgetParams || {},
-                        amountUsd: typeof amountUsd === 'string' ? amountUsd : (amountUsd != null ? amountUsd.toFixed(2) : undefined),
-                    });
-                    paymentIntentId = intentResp?.paymentIntentId || intentResp?.paymentIntent?.id || null;
-                    paymentIntentCode = intentResp?.paymentIntentCode ?? null;
-                    const onrampData = intentResp?.onramp || {};
-                    // Return minimally required response and attach onramp data for widget init
-                    return {
-                        transactionId: 0,
-                        status: 'pending',
-                        amount: request.amount,
-                        recipientCanister: this.icpayCanisterId,
-                        timestamp: new Date(),
-                        metadata: {
-                            paymentIntentId,
-                            paymentIntentCode,
-                            onramp: onrampData,
-                        },
-                    };
-                }
-                catch (e) {
-                    const err = new errors_1.IcpayError({
-                        code: errors_1.ICPAY_ERROR_CODES.API_ERROR,
-                        message: 'Failed to create onramp payment intent',
-                        details: e,
-                        retryable: true,
-                        userAction: 'Try again',
-                    });
-                    this.emitError(err);
-                    throw err;
-                }
-            }
-            // Pre-flight: compute required amount for balance check before creating intent to avoid dangling intents
-            let preAmountStr = typeof request.amount === 'string' ? request.amount : (request.amount != null ? String(request.amount) : undefined);
-            if (!preAmountStr && request.amountUsd != null) {
-                try {
-                    const calc = await this.calculateTokenAmountFromUSD({ usdAmount: Number(request.amountUsd), ledgerCanisterId });
-                    preAmountStr = calc.tokenAmountDecimals;
-                }
-                catch { }
-            }
-            if (!preAmountStr) {
-                const err = new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.API_ERROR, message: 'Either amount or amountUsd must be provided' });
-                this.emitError(err);
-                throw err;
-            }
-            // Check balance before sending
-            const requiredAmount = BigInt(preAmountStr);
-            (0, utils_1.debugLog)(this.config.debug || false, 'checking balance', { ledgerCanisterId, requiredAmount: requiredAmount.toString() });
-            // Helper function to make amounts human-readable
-            const formatAmount = (amount, decimals = 8, symbol = '') => {
-                const divisor = BigInt(10 ** decimals);
-                const whole = amount / divisor;
-                const fraction = amount % divisor;
-                const fractionStr = fraction.toString().padStart(decimals, '0').replace(/0+$/, '');
-                return `${whole}${fractionStr ? '.' + fractionStr : ''} ${symbol}`.trim();
-            };
-            // Check if user has sufficient balance based on ledger type
-            try {
-                // Get the actual balance from the specific ledger (works for all ICRC ledgers including ICP)
-                const actualBalance = await this.getLedgerBalance(ledgerCanisterId);
-                if (actualBalance < requiredAmount) {
-                    const requiredFormatted = formatAmount(requiredAmount, 8, 'tokens');
-                    const availableFormatted = formatAmount(actualBalance, 8, 'tokens');
-                    throw (0, errors_1.createBalanceError)(requiredFormatted, availableFormatted, {
-                        required: requiredAmount,
-                        available: actualBalance,
-                        ledgerCanisterId
-                    });
-                }
-                (0, utils_1.debugLog)(this.config.debug || false, 'balance ok', { actualBalance: actualBalance.toString() });
-            }
-            catch (balanceError) {
-                // If we can't fetch the specific ledger balance, fall back to the old logic
-                throw new errors_1.IcpayError({
-                    code: 'INSUFFICIENT_BALANCE',
-                    message: 'Insufficient balance',
-                    details: { required: requiredAmount, available: 0 }
-                });
-            }
             // 1) Create payment intent via API (backend will finalize amount/price)
             let paymentIntentId = null;
             let paymentIntentCode = null;
+            let intentChainType;
+            let intentChainId;
+            let accountCanisterId;
             let resolvedAmountStr = typeof request.amount === 'string' ? request.amount : (request.amount != null ? String(request.amount) : undefined);
             try {
                 (0, utils_1.debugLog)(this.config.debug || false, 'creating payment intent');
-                // Get the expected sender principal from connected wallet
-                const expectedSenderPrincipal = this.connectedWallet?.owner || this.connectedWallet?.principal?.toString();
+                // Expected sender principal: allow override via request, fallback to connected wallet, then EVM provider
+                let expectedSenderPrincipal = request.expectedSenderPrincipal
+                    || this.connectedWallet?.owner
+                    || this.connectedWallet?.principal?.toString();
+                const evm = this.config?.evmProvider || globalThis?.ethereum;
+                if (evm?.request) {
+                    try {
+                        const accounts = await evm.request({ method: 'eth_accounts' });
+                        if (Array.isArray(accounts) && accounts[0]) {
+                            const lowerAccounts = accounts.map((a) => String(a).toLowerCase());
+                            const providedRaw = request?.expectedSenderPrincipal;
+                            if (providedRaw) {
+                                const provided = String(providedRaw).toLowerCase();
+                                expectedSenderPrincipal = lowerAccounts.includes(provided)
+                                    ? accounts[lowerAccounts.indexOf(provided)]
+                                    : (expectedSenderPrincipal || accounts[0]);
+                            }
+                            else if (!expectedSenderPrincipal) {
+                                expectedSenderPrincipal = accounts[0];
+                            }
+                        }
+                    }
+                    catch { }
+                }
                 if (!expectedSenderPrincipal) {
                     throw new errors_1.IcpayError({
                         code: errors_1.ICPAY_ERROR_CODES.WALLET_NOT_CONNECTED,
@@ -609,17 +891,39 @@ class Icpay {
                         userAction: 'Connect your wallet first'
                     });
                 }
+                const onramp = (request.onrampPayment === true || this.config.onrampPayment === true) && this.config.onrampDisabled !== true ? true : false;
                 const intentResp = await this.publicApiClient.post('/sdk/public/payments/intents', {
-                    amount: request.amount,
-                    symbol: request.symbol,
-                    ledgerCanisterId,
+                    amount: (typeof request.amount === 'string' ? request.amount : (request.amount != null ? String(request.amount) : undefined)),
+                    // Prefer tokenShortcode if provided
+                    tokenShortcode: tokenShortcode || undefined,
+                    // Legacy fields for backwards compatibility
+                    symbol: tokenShortcode ? undefined : request.symbol,
+                    ledgerCanisterId: tokenShortcode ? undefined : ledgerCanisterId,
+                    description: request.description,
                     expectedSenderPrincipal,
                     metadata: request.metadata || {},
                     amountUsd: request.amountUsd,
+                    // With tokenShortcode, backend derives chain. Keep legacy chainId for old flows.
+                    chainId: tokenShortcode ? undefined : request.chainId,
+                    onrampPayment: onramp || undefined,
+                    widgetParams: request.widgetParams || undefined,
                 });
                 paymentIntentId = intentResp?.paymentIntent?.id || null;
                 paymentIntentCode = intentResp?.paymentIntent?.intentCode ?? null;
                 resolvedAmountStr = intentResp?.paymentIntent?.amount || resolvedAmountStr;
+                intentChainType = intentResp?.paymentIntent?.chainType || intentResp?.paymentIntent?.networkType || intentResp?.chainType;
+                intentChainId = intentResp?.paymentIntent?.chainId || intentResp?.chainId || request.chainId;
+                const onrampData = intentResp?.onramp || null;
+                const contractAddress = intentResp?.paymentIntent?.contractAddress || null;
+                const rpcUrlPublic = intentResp?.paymentIntent?.rpcUrlPublic || null;
+                const chainNameFromIntent = intentResp?.paymentIntent?.chainName || null;
+                const rpcChainId = intentResp?.paymentIntent?.rpcChainId || null;
+                const functionSelectors = intentResp?.paymentIntent?.functionSelectors || null;
+                accountCanisterId = intentResp?.paymentIntent?.accountCanisterId || null;
+                // Backfill ledgerCanisterId from intent if not provided in request (tokenShortcode flow)
+                if (!ledgerCanisterId && intentResp?.paymentIntent?.ledgerCanisterId) {
+                    ledgerCanisterId = intentResp.paymentIntent.ledgerCanisterId;
+                }
                 (0, utils_1.debugLog)(this.config.debug || false, 'payment intent created', { paymentIntentId, paymentIntentCode, expectedSenderPrincipal, resolvedAmountStr });
                 // Emit transaction created event
                 if (paymentIntentId) {
@@ -627,9 +931,16 @@ class Icpay {
                         paymentIntentId,
                         amount: resolvedAmountStr,
                         ledgerCanisterId,
-                        expectedSenderPrincipal
+                        expectedSenderPrincipal,
+                        accountCanisterId,
                     });
                 }
+                request.__onramp = onrampData;
+                request.__contractAddress = contractAddress;
+                request.__rpcUrlPublic = rpcUrlPublic;
+                request.__chainName = chainNameFromIntent;
+                request.__functionSelectors = functionSelectors;
+                request.__rpcChainId = rpcChainId;
             }
             catch (e) {
                 // Do not proceed without a payment intent
@@ -652,108 +963,31 @@ class Icpay {
                 throw err;
             }
             const amount = BigInt(resolvedAmountStr);
-            // Build packed memo if possible
+            // Build packed memo
             const acctIdNum = parseInt(accountCanisterId);
             if (!isNaN(acctIdNum) && paymentIntentCode != null) {
                 memo = this.createPackedMemo(acctIdNum, Number(paymentIntentCode));
                 (0, utils_1.debugLog)(this.config.debug || false, 'built packed memo', { accountCanisterId: acctIdNum, paymentIntentCode });
             }
-            (0, utils_1.debugLog)(this.config.debug || false, 'memo', { memo });
-            let transferResult;
-            try {
-                // ICP Ledger: use ICRC-1 transfer (ICP ledger supports ICRC-1)
-                (0, utils_1.debugLog)(this.config.debug || false, 'sending ICRC-1 transfer (ICP)');
-                transferResult = await this.sendFundsToLedger(ledgerCanisterId, toPrincipal, amount, memo, host);
-            }
-            catch (transferError) {
-                // Some wallets/networks return a timeout or transient 5xx even when the transfer was accepted.
-                // Treat these as processing and continue with intent notification so users don't double-send.
-                const msg = String(transferError?.message || '');
-                const lower = msg.toLowerCase();
-                const isTimeout = lower.includes('request timed out');
-                const isProcessing = isTimeout && lower.includes('processing');
-                // DFINITY HTTP agent transient error when subnet has no healthy nodes (e.g., during upgrade)
-                const isNoHealthyNodes = lower.includes('no_healthy_nodes') || lower.includes('service unavailable') || lower.includes('503');
-                // Plug inpage transport sometimes throws readState errors after a signed call even though the tx went through
-                const isPlugReadState = lower.includes('read state request') || lower.includes('readstate') || lower.includes('response could not be found');
-                if (isTimeout || isProcessing || isNoHealthyNodes || isPlugReadState) {
-                    (0, utils_1.debugLog)(this.config.debug || false, 'transfer timed out, proceeding with intent notification', { message: msg });
-                    // Long-poll the public notify endpoint using only the intent id (no canister tx id available)
-                    const publicNotify = await this.performNotifyPaymentIntent({
-                        paymentIntentId: paymentIntentId,
-                        maxAttempts: 120,
-                        delayMs: 1000,
-                    });
-                    // Derive status from API response
-                    let statusString = 'pending';
-                    const apiStatus = publicNotify?.paymentIntent?.status || publicNotify?.payment?.status || publicNotify?.status;
-                    if (typeof apiStatus === 'string') {
-                        const norm = apiStatus.toLowerCase();
-                        if (norm === 'completed' || norm === 'succeeded')
-                            statusString = 'completed';
-                        else if (norm === 'failed' || norm === 'canceled' || norm === 'cancelled')
-                            statusString = 'failed';
-                    }
-                    const response = {
-                        transactionId: 0,
-                        status: statusString,
-                        amount: amount.toString(),
-                        recipientCanister: ledgerCanisterId,
-                        timestamp: new Date(),
-                        description: 'Fund transfer',
-                        metadata: request.metadata,
-                        payment: publicNotify,
-                    };
-                    if (statusString === 'completed') {
-                        const requested = publicNotify?.payment?.requestedAmount || null;
-                        const paid = publicNotify?.payment?.paidAmount || null;
-                        const isMismatched = publicNotify?.payment?.status === 'mismatched';
-                        if (isMismatched) {
-                            this.emit('icpay-sdk-transaction-mismatched', { ...response, requestedAmount: requested, paidAmount: paid });
-                            this.emit('icpay-sdk-transaction-updated', { ...response, status: 'mismatched', requestedAmount: requested, paidAmount: paid });
-                        }
-                        else {
-                            this.emit('icpay-sdk-transaction-completed', response);
-                        }
-                    }
-                    else if (statusString === 'failed') {
-                        this.emit('icpay-sdk-transaction-failed', response);
-                    }
-                    else {
-                        this.emit('icpay-sdk-transaction-updated', response);
-                    }
-                    this.emitMethodSuccess('createPayment', response);
-                    return response;
-                }
-                throw transferError;
-            }
-            // Assume transferResult returns a block index or transaction id
-            const blockIndex = transferResult?.Ok?.toString() || transferResult?.blockIndex?.toString() || `temp-${Date.now()}`;
-            (0, utils_1.debugLog)(this.config.debug || false, 'transfer result', { blockIndex });
-            // First, notify the canister about the ledger transaction (best-effort)
-            let canisterTransactionId;
-            try {
-                (0, utils_1.debugLog)(this.config.debug || false, 'notifying canister about ledger tx');
-                const notifyRes = await this.notifyLedgerTransaction(this.icpayCanisterId, ledgerCanisterId, BigInt(blockIndex));
-                if (typeof notifyRes === 'string') {
-                    canisterTransactionId = parseInt(notifyRes, 10);
-                }
-                else {
-                    canisterTransactionId = parseInt(notifyRes.id, 10);
-                }
-                (0, utils_1.debugLog)(this.config.debug || false, 'canister notified', { canisterTransactionId });
-            }
-            catch (notifyError) {
-                canisterTransactionId = parseInt(blockIndex, 10);
-                (0, utils_1.debugLog)(this.config.debug || false, 'notify failed, using blockIndex as tx id', { canisterTransactionId });
-            }
-            // Durable wait until API returns terminal status (completed/mismatched/failed/canceled)
-            const finalResponse = await this.awaitIntentTerminal({
-                paymentIntentId: paymentIntentId,
-                canisterTransactionId: canisterTransactionId?.toString(),
+            (0, utils_1.debugLog)(this.config.debug || false, 'memo', { memo, accountCanisterId, paymentIntentCode });
+            // Delegate to chain-specific processing
+            const finalResponse = await this.processPaymentByChain({
+                chainType: intentChainType,
+                chainId: intentChainId,
                 ledgerCanisterId,
-                amount: amount.toString(),
+                amount,
+                memo,
+                paymentIntentId: paymentIntentId,
+                request,
+                resolvedAmountStr: amount.toString(),
                 metadata: request.metadata,
+                onrampData: request.__onramp,
+                contractAddress: request.__contractAddress,
+                accountCanisterId,
+                rpcUrlPublic: request.__rpcUrlPublic,
+                chainName: request.__chainName,
+                rpcChainId: request.__rpcChainId,
+                paymentIntentCode,
             });
             this.emitMethodSuccess('createPayment', finalResponse);
             return finalResponse;
@@ -881,6 +1115,7 @@ class Icpay {
                 const agent = new agent_1.HttpAgent({ host: this.icHost });
                 const actor = agent_1.Actor.createActor(icpay_canister_backend_did_js_1.idlFactory, { agent, canisterId });
                 result = await actor.notify_ledger_transaction({
+                    // Canister expects text for ledger_canister_id
                     ledger_canister_id: ledgerCanisterId,
                     block_index: blockIndex
                 });
@@ -1004,68 +1239,67 @@ class Icpay {
     }
     // ===== NEW ENHANCED SDK FUNCTIONS =====
     /**
-     * Get balance for all verified ledgers for the connected wallet (public method)
+     * Public: Get balances for an external wallet (IC principal or EVM address) using publishable key
      */
-    async getAllLedgerBalances() {
-        this.emitMethodStart('getAllLedgerBalances');
+    async getExternalWalletBalances(params) {
+        this.emitMethodStart('getExternalWalletBalances', { params });
         try {
-            if (!this.isWalletConnected()) {
-                throw new errors_1.IcpayError({
-                    code: 'WALLET_NOT_CONNECTED',
-                    message: 'Wallet must be connected to fetch balances'
-                });
-            }
-            const verifiedLedgers = await this.getVerifiedLedgers();
-            const balances = [];
-            let totalBalancesUSD = 0;
-            for (const ledger of verifiedLedgers) {
-                try {
-                    const rawBalance = await this.getLedgerBalance(ledger.canisterId);
-                    const formattedBalance = this.formatBalance(rawBalance.toString(), ledger.decimals);
-                    const balance = {
-                        ledgerId: ledger.id,
-                        ledgerName: ledger.name,
-                        ledgerSymbol: ledger.symbol,
-                        canisterId: ledger.canisterId,
-                        balance: rawBalance.toString(),
-                        formattedBalance,
-                        decimals: ledger.decimals,
-                        currentPrice: ledger.currentPrice || undefined,
-                        lastPriceUpdate: ledger.lastPriceUpdate ? new Date(ledger.lastPriceUpdate) : undefined,
-                        lastUpdated: new Date()
-                    };
-                    balances.push(balance);
-                    // Calculate USD value if price is available
-                    if (ledger.currentPrice && rawBalance > 0) {
-                        const humanReadableBalance = parseFloat(formattedBalance);
-                        totalBalancesUSD += humanReadableBalance * ledger.currentPrice;
-                    }
-                }
-                catch (error) {
-                    this.emit('icpay-sdk-method-error', {
-                        name: 'getAllLedgerBalances.getLedgerBalance',
-                        error,
-                        ledgerSymbol: ledger.symbol,
-                        ledgerCanisterId: ledger.canisterId
-                    });
-                    // Continue with other ledgers even if one fails
-                }
-            }
+            const search = new URLSearchParams();
+            if (params.network)
+                search.set('network', params.network);
+            if (params.address)
+                search.set('address', params.address);
+            if (params.principal)
+                search.set('principal', params.principal);
+            if (params.chainId)
+                search.set('chainId', params.chainId);
+            if (typeof params.amountUsd === 'number' && isFinite(params.amountUsd))
+                search.set('amountUsd', String(params.amountUsd));
+            if (typeof params.amount === 'string' && params.amount)
+                search.set('amount', params.amount);
+            if (Array.isArray(params.chainShortcodes) && params.chainShortcodes.length > 0)
+                search.set('chainShortcodes', params.chainShortcodes.join(','));
+            if (Array.isArray(params.tokenShortcodes) && params.tokenShortcodes.length > 0)
+                search.set('tokenShortcodes', params.tokenShortcodes.join(','));
+            const response = await this.publicApiClient.get(`/sdk/public/wallet/external-balances?${search.toString()}`);
             const result = {
-                balances,
-                totalBalancesUSD: totalBalancesUSD > 0 ? totalBalancesUSD : undefined,
-                lastUpdated: new Date()
+                balances: (response?.balances || []).map((balance) => ({
+                    ledgerId: balance.ledgerId,
+                    ledgerName: balance.ledgerName,
+                    ledgerSymbol: balance.ledgerSymbol,
+                    tokenShortcode: (balance?.tokenShortcode ?? balance?.shortcode) ?? null,
+                    canisterId: balance.canisterId,
+                    eip3009Version: balance?.eip3009Version ?? null,
+                    x402Accepts: balance?.x402Accepts != null ? Boolean(balance.x402Accepts) : undefined,
+                    balance: balance.balance,
+                    formattedBalance: balance.formattedBalance,
+                    decimals: balance.decimals,
+                    currentPrice: balance.currentPrice,
+                    lastPriceUpdate: balance.lastPriceUpdate ? new Date(balance.lastPriceUpdate) : undefined,
+                    lastUpdated: balance.lastUpdated ? new Date(balance.lastUpdated) : new Date(),
+                    // Chain metadata passthrough for multichain UX
+                    chainId: typeof balance.chainId === 'string' ? balance.chainId : (typeof balance.chainId === 'number' ? String(balance.chainId) : undefined),
+                    chainName: balance.chainName ?? (balance.chain && (balance.chain.name || balance.chain.chainName)) ?? null,
+                    rpcUrlPublic: balance.rpcUrlPublic ?? null,
+                    chainUuid: balance.chainUuid ?? null,
+                    requiredAmount: balance.requiredAmount,
+                    requiredAmountFormatted: balance.requiredAmountFormatted,
+                    hasSufficientBalance: balance.hasSufficientBalance,
+                    logoUrl: balance.logoUrl ?? null,
+                })),
+                totalBalancesUSD: response?.totalBalancesUSD,
+                lastUpdated: new Date(response?.lastUpdated || Date.now()),
             };
-            this.emitMethodSuccess('getAllLedgerBalances', { count: balances.length, totalUSD: result.totalBalancesUSD });
+            this.emitMethodSuccess('getExternalWalletBalances', { count: result.balances.length, totalUSD: result.totalBalancesUSD });
             return result;
         }
         catch (error) {
             const err = new errors_1.IcpayError({
-                code: 'BALANCES_FETCH_FAILED',
-                message: 'Failed to fetch all ledger balances',
-                details: error
+                code: 'ACCOUNT_WALLET_BALANCES_FETCH_FAILED',
+                message: 'Failed to fetch external wallet balances (public)',
+                details: error,
             });
-            this.emitMethodError('getAllLedgerBalances', err);
+            this.emitMethodError('getExternalWalletBalances', err);
             throw err;
         }
     }
@@ -1177,14 +1411,33 @@ class Icpay {
     /**
      * Get detailed ledger information including price data (public method)
      */
-    async getLedgerInfo(ledgerCanisterId) {
-        this.emitMethodStart('getLedgerInfo', { ledgerCanisterId });
+    async getLedgerInfo(ledgerCanisterId, opts) {
+        this.emitMethodStart('getLedgerInfo', { ledgerCanisterId, opts });
         try {
-            const ledger = await this.publicApiClient.get(`/sdk/public/ledgers/${ledgerCanisterId}`);
+            const isZeroAddress = typeof ledgerCanisterId === 'string' && /^0x0{40}$/i.test(ledgerCanisterId);
+            // Back-compat safety: require chainId for native token (zero address)
+            let url = `/sdk/public/ledgers/${encodeURIComponent(ledgerCanisterId)}`;
+            if (isZeroAddress) {
+                const chainId = opts?.chainId;
+                if (!chainId && this.config?.debug) {
+                    (0, utils_1.debugLog)(true, 'getLedgerInfo requires chainId for zero address', { ledgerCanisterId });
+                }
+                if (!chainId) {
+                    throw new errors_1.IcpayError({
+                        code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
+                        message: 'chainId is required when querying native token (0x000…000). Prefer tokenShortcode in new flows.',
+                    });
+                }
+                const chainStr = typeof chainId === 'number' ? String(chainId) : chainId;
+                url = `${url}?chainId=${encodeURIComponent(chainStr || '')}`;
+            }
+            const ledger = await this.publicApiClient.get(url);
             const result = {
                 id: ledger.id,
                 name: ledger.name,
                 symbol: ledger.symbol,
+                chainId: ledger.chainId,
+                shortcode: ledger.shortcode ?? null,
                 canisterId: ledger.canisterId,
                 standard: ledger.standard,
                 decimals: ledger.decimals,
@@ -1222,28 +1475,29 @@ class Icpay {
         try {
             // Convert usdAmount to number if it's a string
             const usdAmount = typeof request.usdAmount === 'string' ? parseFloat(request.usdAmount) : request.usdAmount;
-            // Resolve ledgerCanisterId from symbol if needed
+            // If tokenShortcode provided, skip canister resolution; otherwise resolve from symbol if needed
+            const tokenShortcode = request?.tokenShortcode;
             let ledgerCanisterId = request.ledgerCanisterId;
-            if (!ledgerCanisterId && request.symbol) {
-                ledgerCanisterId = await this.getLedgerCanisterIdBySymbol(request.symbol);
-            }
-            if (!ledgerCanisterId) {
+            if (!ledgerCanisterId && !tokenShortcode && !request.symbol) {
                 const err = new errors_1.IcpayError({
                     code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
-                    message: 'Either ledgerCanisterId or symbol must be provided',
+                    message: 'Provide either tokenShortcode or ledgerCanisterId (symbol is deprecated).',
                     details: { request }
                 });
-                this.emitMethodError('createPaymentUsd', err);
+                this.emitMethodError('createPayment', err);
                 throw err;
             }
             const createTransactionRequest = {
-                ledgerCanisterId,
-                symbol: request.symbol,
+                ledgerCanisterId: tokenShortcode ? undefined : ledgerCanisterId,
+                symbol: tokenShortcode ? undefined : request.symbol,
+                tokenShortcode,
                 amountUsd: usdAmount,
+                description: request.description,
                 accountCanisterId: request.accountCanisterId,
                 metadata: request.metadata,
                 onrampPayment: request.onrampPayment,
                 widgetParams: request.widgetParams,
+                chainId: tokenShortcode ? undefined : request.chainId,
             };
             const res = await this.createPayment(createTransactionRequest);
             this.emitMethodSuccess('createPaymentUsd', res);
@@ -1263,6 +1517,212 @@ class Icpay {
             throw err;
         }
     }
+    /**
+     * Create an X402 payment from a USD amount
+     * Falls back to regular flow at caller level if unavailable.
+     */
+    async createPaymentX402Usd(request) {
+        this.emitMethodStart('createPaymentX402Usd', { request });
+        try {
+            const usdAmount = typeof request.usdAmount === 'string' ? parseFloat(request.usdAmount) : request.usdAmount;
+            // For X402, the backend will resolve ledger/symbol as needed from the intent.
+            // We forward both amountUsd and amount (if provided), and do not resolve canister here.
+            const ledgerCanisterId = request.ledgerCanisterId || '';
+            const tokenShortcode = request?.tokenShortcode;
+            // Hit X402 endpoint
+            const body = {
+                amount: request.amount,
+                amountUsd: usdAmount,
+                // Prefer tokenShortcode; keep legacy fields if not provided
+                tokenShortcode: tokenShortcode || undefined,
+                symbol: tokenShortcode ? undefined : request.symbol,
+                ledgerCanisterId: tokenShortcode ? undefined : ledgerCanisterId,
+                description: request.description,
+                metadata: request.metadata,
+                chainId: tokenShortcode ? undefined : request.chainId,
+                x402: true,
+            };
+            try {
+                const resp = await this.publicApiClient.post('/sdk/public/payments/intents/x402', body);
+                // If backend indicates x402 is unavailable (failed + fallback), immediately switch to normal flow
+                const respStatus = (resp?.status || '').toString().toLowerCase();
+                const fallbackSuggested = Boolean(resp?.fallbackSuggested);
+                if (respStatus === 'failed' && fallbackSuggested) {
+                    const fallback = await this.createPaymentUsd(request);
+                    this.emitMethodSuccess('createPaymentX402Usd', fallback);
+                    return fallback;
+                }
+                // If backend returned normal flow (no accepts), skip x402 and proceed with regular flow
+                const hasAccepts = Array.isArray(resp?.accepts) && resp.accepts.length > 0;
+                if (!hasAccepts) {
+                    const fallback = await this.createPaymentUsd(request);
+                    this.emitMethodSuccess('createPaymentX402Usd', fallback);
+                    return fallback;
+                }
+                // If backend returned accepts despite 200, keep previous behavior (pending with x402 metadata)
+                const normalized = {
+                    transactionId: 0,
+                    status: 'pending',
+                    amount: (resp?.paymentIntent?.amount || resp?.amount || request.usdAmount)?.toString?.() || String(request.usdAmount),
+                    recipientCanister: ledgerCanisterId,
+                    timestamp: new Date(),
+                    metadata: { ...(request.metadata || {}), x402: true },
+                    payment: resp,
+                };
+                this.emitMethodSuccess('createPaymentX402Usd', normalized);
+                return normalized;
+            }
+            catch (e) {
+                // If API responds with HTTP 402 to trigger wallet X402 flow, begin settlement wait instead of erroring
+                if (e && typeof e.status === 'number' && e.status === 402) {
+                    // Try to extract paymentIntentId from response data to start polling
+                    const data = e?.data || {};
+                    // Support new x402 Payment Required Response body:
+                    // { x402Version, accepts: [{ ..., extra: { intentId } }], error }
+                    let paymentIntentId = data?.paymentIntentId || null;
+                    if (!paymentIntentId && Array.isArray(data?.accepts) && data.accepts[0]?.extra?.intentId) {
+                        paymentIntentId = String(data.accepts[0].extra.intentId);
+                    }
+                    if (paymentIntentId) {
+                        // Prefer ledgerCanisterId from request/body; fallback to server response if present
+                        const acceptsArr = Array.isArray(data?.accepts) ? data.accepts : [];
+                        let requirement = acceptsArr.length > 0 ? acceptsArr[0] : null;
+                        if (requirement) {
+                            try {
+                                const paymentHeader = await (0, builders_1.buildAndSignX402PaymentHeader)(requirement, {
+                                    x402Version: Number(data?.x402Version || 1),
+                                    debug: this.config?.debug || false,
+                                    provider: this.config?.evmProvider || (typeof globalThis?.ethereum !== 'undefined' ? globalThis.ethereum : undefined),
+                                });
+                                // Start verification stage while we wait for settlement to process
+                                try {
+                                    this.emitMethodStart('notifyLedgerTransaction', { paymentIntentId });
+                                }
+                                catch { }
+                                const settleResp = await this.publicApiClient.post('/sdk/public/payments/x402/settle', {
+                                    paymentIntentId,
+                                    paymentHeader,
+                                    paymentRequirements: requirement,
+                                });
+                                try {
+                                    (0, utils_1.debugLog)(this.config?.debug || false, 'x402 settle response (from icpay-services via api)', {
+                                        ok: settleResp?.ok,
+                                        status: settleResp?.status,
+                                        txHash: settleResp?.txHash,
+                                        paymentIntentId: settleResp?.paymentIntent?.id,
+                                        paymentId: settleResp?.payment?.id,
+                                        rawKeys: Object.keys(settleResp || {}),
+                                    });
+                                }
+                                catch { }
+                                // Move to "Payment confirmation" stage (confirm loading)
+                                try {
+                                    this.emitMethodSuccess('notifyLedgerTransaction', { paymentIntentId });
+                                }
+                                catch { }
+                                const status = (settleResp?.status || settleResp?.paymentIntent?.status || 'completed').toString().toLowerCase();
+                                const amountStr = (settleResp?.paymentIntent?.amount && String(settleResp.paymentIntent.amount)) ||
+                                    (typeof usdAmount === 'number' ? String(usdAmount) : request?.amount?.toString?.() || '0');
+                                const out = {
+                                    transactionId: Number(settleResp?.canisterTxId || 0),
+                                    status: status === 'succeeded' ? 'completed' : status,
+                                    amount: amountStr,
+                                    recipientCanister: ledgerCanisterId,
+                                    timestamp: new Date(),
+                                    metadata: { ...(request.metadata || {}), x402: true },
+                                    payment: settleResp || null,
+                                };
+                                // If x402 failed due to minimal limits, emit failure and fall back to normal flow
+                                const failMsg = settleResp?.message || settleResp?.error || '';
+                                if (out.status === 'failed' && (failMsg === 'x402_minimal_platform_fee_not_met' || failMsg === 'x402_minimum_amount_not_met')) {
+                                    try {
+                                        this.emit('icpay-sdk-transaction-failed', { ...out, reason: failMsg });
+                                    }
+                                    catch { }
+                                    // Initiate regular flow (non-x402) with the same request
+                                    const fallback = await this.createPaymentUsd(request);
+                                    this.emitMethodSuccess('createPaymentX402Usd', fallback);
+                                    return fallback;
+                                }
+                                const isTerminal = (() => {
+                                    const s = String(out.status || '').toLowerCase();
+                                    return s === 'completed' || s === 'succeeded' || s === 'failed' || s === 'canceled' || s === 'cancelled' || s === 'mismatched';
+                                })();
+                                if (isTerminal) {
+                                    if (out.status === 'completed') {
+                                        this.emit('icpay-sdk-transaction-completed', out);
+                                    }
+                                    else if (out.status === 'failed') {
+                                        this.emit('icpay-sdk-transaction-failed', out);
+                                    }
+                                    else {
+                                        this.emit('icpay-sdk-transaction-updated', out);
+                                    }
+                                    this.emitMethodSuccess('createPaymentX402Usd', out);
+                                    return out;
+                                }
+                                // Non-terminal (e.g., requires_payment). Continue notifying until terminal.
+                                try {
+                                    this.emit('icpay-sdk-transaction-updated', out);
+                                }
+                                catch { }
+                                const waited = await this.awaitIntentTerminal({
+                                    paymentIntentId,
+                                    ledgerCanisterId: ledgerCanisterId,
+                                    amount: amountStr,
+                                    metadata: { ...(request.metadata || {}), x402: true },
+                                });
+                                this.emitMethodSuccess('createPaymentX402Usd', waited);
+                                return waited;
+                            }
+                            catch {
+                                // Fall through to notify-based wait if settle endpoint not available
+                            }
+                        }
+                        // Fallback: wait until terminal via notify loop
+                        const amountStr = (data?.paymentIntent?.amount && String(data.paymentIntent.amount)) ||
+                            (Array.isArray(data?.accepts) && data.accepts[0]?.maxAmountRequired && String(data.accepts[0].maxAmountRequired)) ||
+                            (typeof usdAmount === 'number' ? String(usdAmount) : request?.amount?.toString?.() || '0');
+                        const finalResponse = await this.awaitIntentTerminal({
+                            paymentIntentId,
+                            ledgerCanisterId: ledgerCanisterId,
+                            amount: amountStr,
+                            metadata: { ...(request.metadata || {}), x402: true },
+                        });
+                        this.emitMethodSuccess('createPaymentX402Usd', finalResponse);
+                        return finalResponse;
+                    }
+                    // No intent id provided: return a pending response with x402 metadata
+                    const pending = {
+                        transactionId: 0,
+                        status: 'pending',
+                        amount: (typeof usdAmount === 'number' ? String(usdAmount) : request?.amount?.toString?.() || '0'),
+                        recipientCanister: ledgerCanisterId || null,
+                        timestamp: new Date(),
+                        metadata: { ...(request.metadata || {}), x402: true },
+                        payment: null,
+                    };
+                    this.emitMethodSuccess('createPaymentX402Usd', pending);
+                    return pending;
+                }
+                // Any other error: rethrow to allow caller fallback
+                throw e;
+            }
+        }
+        catch (error) {
+            if (error instanceof errors_1.IcpayError) {
+                this.emitMethodError('createPaymentX402Usd', error);
+                throw error;
+            }
+            const err = new errors_1.IcpayError({
+                code: errors_1.ICPAY_ERROR_CODES.API_ERROR,
+                message: 'X402 payment flow not available',
+                details: error,
+            });
+            this.emitMethodError('createPaymentX402Usd', err);
+            throw err;
+        }
+    }
     /**
      * Continuously notifies the API about a payment intent (no canister tx id) for Onramp.
      * Uses publishable-key public endpoint. Emits icpay-sdk-transaction-updated only when
@@ -1319,6 +1779,8 @@ class Icpay {
                 const body = { paymentIntentId: params.paymentIntentId };
                 if (params.canisterTransactionId)
                     body.canisterTxId = params.canisterTransactionId;
+                if (params.transactionId)
+                    body.transactionId = params.transactionId;
                 if (params.orderId)
                     body.orderId = params.orderId;
                 const resp = await notifyClient.post(notifyPath, body);
@@ -1364,6 +1826,7 @@ class Icpay {
                 const resp = await this.performNotifyPaymentIntent({
                     paymentIntentId: params.paymentIntentId,
                     canisterTransactionId: params.canisterTransactionId,
+                    transactionId: params.transactionId || (params?.metadata?.evmTxHash ? String(params.metadata.evmTxHash) : undefined),
                     maxAttempts: 1,
                     delayMs: 0,
                 });
@@ -1426,6 +1889,8 @@ class Icpay {
                 id: ledger.id,
                 name: ledger.name,
                 symbol: ledger.symbol,
+                chainId: ledger.chainId,
+                shortcode: ledger.shortcode ?? null,
                 canisterId: ledger.canisterId,
                 standard: ledger.standard,
                 decimals: ledger.decimals,