@ic-pay/icpay-sdk 1.4.26 → 1.4.67

package/dist/index.js

@@ -26,6 +26,120 @@ const principal_1 = require("@dfinity/principal");
 const utils_1 = require("./utils");
 const protected_1 = require("./protected");
 const http_1 = require("./http");
+// Minimal helpers to support Phantom's base58 "message" signing without extra deps
+const B58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+function base58Encode(bytes) {
+    if (!bytes || bytes.length === 0)
+        return '';
+    // Count leading zeros
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0)
+        zeros++;
+    // Convert base-256 to base-58
+    const digits = [0];
+    for (let i = zeros; i < bytes.length; i++) {
+        let carry = bytes[i];
+        for (let j = 0; j < digits.length; j++) {
+            const x = digits[j] * 256 + carry;
+            digits[j] = x % 58;
+            carry = Math.floor(x / 58);
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = Math.floor(carry / 58);
+        }
+    }
+    // Leading zero bytes are represented by '1'
+    let out = '';
+    for (let k = 0; k < zeros; k++)
+        out += '1';
+    for (let q = digits.length - 1; q >= 0; q--)
+        out += B58_ALPHABET[digits[q]];
+    return out;
+}
+function base58Decode(s) {
+    if (!s || s.length === 0)
+        return new Uint8Array(0);
+    const MAP = {};
+    for (let i = 0; i < B58_ALPHABET.length; i++)
+        MAP[B58_ALPHABET.charAt(i)] = i;
+    let zeros = 0;
+    while (zeros < s.length && s.charAt(zeros) === '1')
+        zeros++;
+    const bytes = [0];
+    for (let i = zeros; i < s.length; i++) {
+        const ch = s.charAt(i);
+        const val = MAP[ch];
+        if (val === undefined)
+            throw new Error('invalid base58');
+        let carry = val;
+        for (let j = 0; j < bytes.length; j++) {
+            const prev = bytes[j];
+            const x = (prev * 58) + carry;
+            bytes[j] = x & 0xff;
+            carry = x >> 8;
+        }
+        while (carry > 0) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    const outArr = new Uint8Array(zeros + bytes.length);
+    let p = 0;
+    for (; p < zeros; p++)
+        outArr[p] = 0;
+    for (let q = bytes.length - 1; q >= 0; q--)
+        outArr[p++] = (bytes[q] == null ? 0 : bytes[q]);
+    return outArr;
+}
+function b64FromBytes(bytes) {
+    try {
+        const Buf = globalThis.Buffer;
+        if (Buf)
+            return Buf.from(bytes).toString('base64');
+    }
+    catch { }
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    // btoa expects binary string
+    return globalThis?.btoa ? globalThis.btoa(bin) : '';
+}
+function u8FromBase64(b64) {
+    try {
+        const Buf = globalThis.Buffer;
+        if (Buf)
+            return new Uint8Array(Buf.from(b64, 'base64'));
+    }
+    catch { }
+    const bin = globalThis?.atob ? globalThis.atob(b64) : '';
+    const arr = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        arr[i] = bin.charCodeAt(i);
+    return arr;
+}
+// Normalize metadata so internal icpay-managed fields are nested under metadata.icpay.
+// If icpay exists, merge; otherwise create. Move known internal keys and icpay_* keys under icpay.
+function normalizeSdkMetadata(base) {
+    const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+    const incoming = isObj(base) ? { ...base } : {};
+    const hasGroup = isObj(incoming.icpay);
+    const INTERNAL_KEYS = ['context', 'senderPrincipal', 'onrampProvider'];
+    const moved = {};
+    for (const [k, v] of Object.entries(incoming)) {
+        if (INTERNAL_KEYS.includes(k) || k.startsWith('icpay_')) {
+            moved[k] = v;
+            delete incoming[k];
+        }
+    }
+    if (hasGroup) {
+        incoming.icpay = { ...(incoming.icpay || {}), ...moved };
+    }
+    else {
+        incoming.icpay = moved;
+    }
+    return incoming;
+}
 class Icpay {
     constructor(config) {
         this.privateApiClient = null;
@@ -41,7 +155,7 @@ class Icpay {
             debug: false,
             enableEvents: true,
             ...config,
-            onrampDisabled: true,
+            onrampDisabled: false,
         };
         (0, utils_1.debugLog)(this.config.debug || false, 'constructor', { config: this.config });
         // Validate authentication configuration
@@ -421,12 +535,9 @@ class Icpay {
             case 'evm':
             case 'ethereum':
                 return await this.processEvmPayment(params);
+            case 'sol':
             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 }
-                });
+                return await this.processSolanaPayment(params);
             case 'sui':
                 throw new errors_1.IcpayError({
                     code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
@@ -588,7 +699,35 @@ class Icpay {
         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));
+            // Attempt to decode accountCanisterId from packed memo (high 32 bits)
+            let acctFromMemo = undefined;
+            try {
+                if (memo && memo.length > 0) {
+                    let big = 0n;
+                    for (let i = 0; i < memo.length; i++) {
+                        big |= BigInt(memo[i] & 0xff) << BigInt(8 * i);
+                    }
+                    const acct = Number(big >> 32n);
+                    if (Number.isFinite(acct) && acct > 0)
+                        acctFromMemo = acct;
+                }
+            }
+            catch { }
+            // Derive recipient principal for relay from request payload (IC address)
+            const recipientPrincipal = (() => {
+                const addrAny = request;
+                const icAddr = (addrAny?.recipientAddresses?.ic || addrAny?.recipientAddress || '').toString().trim();
+                // Heuristic: treat non-hex, non-empty as IC principal candidate
+                if (icAddr && !/^0x[a-fA-F0-9]{40}$/.test(icAddr))
+                    return icAddr;
+                return undefined;
+            })();
+            const externalCostAmount = request.__externalCostAmount ?? request?.externalCostAmount ?? request?.metadata?.externalCostAmount;
+            const notifyRes = await this.notifyLedgerTransaction(this.icpayCanisterId, ledgerCanisterId, BigInt(blockIndex), {
+                accountCanisterId: acctFromMemo,
+                externalCostAmount,
+                recipientPrincipal
+            });
             if (typeof notifyRes === 'string') {
                 const parsed = parseInt(notifyRes, 10);
                 canisterTransactionId = Number.isFinite(parsed) ? parsed : undefined;
@@ -617,6 +756,117 @@ class Icpay {
         });
         return finalResponse;
     }
+    async processSolanaPayment(params) {
+        if (!params.contractAddress) {
+            throw new errors_1.IcpayError({
+                code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
+                message: 'Missing Solana program address in payment intent',
+            });
+        }
+        const w = globalThis?.window || globalThis;
+        const sol = this.config?.solanaProvider || w?.solana;
+        if (!sol) {
+            throw new errors_1.IcpayError({
+                code: errors_1.ICPAY_ERROR_CODES.WALLET_PROVIDER_NOT_AVAILABLE,
+                message: 'Solana provider not available (window.solana)',
+            });
+        }
+        // Ensure connected & resolve payer pubkey
+        let payerKey = null;
+        try {
+            if (!sol.publicKey) {
+                await (sol.connect ? sol.connect() : sol.request?.({ method: 'connect' }));
+            }
+            const pk = sol.publicKey || sol?.wallet?.publicKey;
+            payerKey = pk ? String(pk) : null;
+        }
+        catch { }
+        if (!payerKey) {
+            throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.WALLET_NOT_CONNECTED, message: 'Solana wallet not connected' });
+        }
+        // If the intent already provided an unsigned transaction, use it (no extra API roundtrip)
+        const prebuiltBase64 = params.request?.__transactionBase64;
+        if (typeof prebuiltBase64 === 'string' && prebuiltBase64.length > 0) {
+            let signature;
+            try {
+                if (sol?.request) {
+                    // Treat as Phantom only if the selected provider itself reports isPhantom,
+                    // or it is literally the same object as window.phantom.solana.
+                    const isPhantom = !!(sol?.isPhantom ||
+                        ((w?.phantom?.solana) && (w.phantom.solana === sol)));
+                    if (isPhantom) {
+                        // Phantom expects base58-encoded serialized message under "message"
+                        const msgB58 = base58Encode(u8FromBase64(prebuiltBase64));
+                        (0, utils_1.debugLog)(this.config.debug || false, 'solana phantom request', { method: 'signAndSendTransaction', param: 'message(base58)' });
+                        const r = await sol.request({ method: 'signAndSendTransaction', params: { message: msgB58 } });
+                        signature = (r && (r.signature || r));
+                    }
+                    else {
+                        // Other wallets may accept base64 "transaction"
+                        (0, utils_1.debugLog)(this.config.debug || false, 'solana generic request', { method: 'signAndSendTransaction', param: 'transaction(base64)' });
+                        const r1 = await sol.request({ method: 'signAndSendTransaction', params: { transaction: prebuiltBase64 } });
+                        signature = (r1 && (r1.signature || r1));
+                    }
+                }
+                else if (typeof sol?.signAndSendTransaction === 'function') {
+                    // Some providers (e.g., Backpack) expose direct signAndSendTransaction without request API.
+                    // Try common parameter shapes in order.
+                    const msgB58 = base58Encode(u8FromBase64(prebuiltBase64));
+                    let r2 = null;
+                    try {
+                        (0, utils_1.debugLog)(this.config.debug || false, 'solana direct call', { fn: 'signAndSendTransaction', param: 'message(base58)' });
+                        r2 = await sol.signAndSendTransaction({ message: msgB58 });
+                    }
+                    catch { }
+                    if (!r2) {
+                        try {
+                            (0, utils_1.debugLog)(this.config.debug || false, 'solana direct call', { fn: 'signAndSendTransaction', param: 'transaction(base64)' });
+                            r2 = await sol.signAndSendTransaction({ transaction: prebuiltBase64 });
+                        }
+                        catch { }
+                    }
+                    if (!r2) {
+                        try {
+                            (0, utils_1.debugLog)(this.config.debug || false, 'solana direct call', { fn: 'signAndSendTransaction', param: 'transaction(uint8array)' });
+                            r2 = await sol.signAndSendTransaction(u8FromBase64(prebuiltBase64));
+                        }
+                        catch { }
+                    }
+                    signature = (r2 && (r2.signature || r2));
+                }
+                else {
+                    throw new Error('Unsupported Solana wallet interface');
+                }
+                if (!signature)
+                    throw new Error('Missing Solana transaction signature');
+            }
+            catch (e) {
+                try {
+                    (0, utils_1.debugLog)(this.config.debug || false, 'solana tx error (prebuilt)', { message: e?.message });
+                }
+                catch { }
+                throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.TRANSACTION_FAILED, message: 'Solana transaction failed', details: e });
+            }
+            try {
+                this.emitMethodSuccess('notifyLedgerTransaction', { paymentIntentId: params.paymentIntentId });
+            }
+            catch { }
+            try {
+                await this.performNotifyPaymentIntent({ paymentIntentId: params.paymentIntentId, transactionId: signature, maxAttempts: 1 });
+            }
+            catch { }
+            const finalQuick = await this.awaitIntentTerminal({
+                paymentIntentId: params.paymentIntentId,
+                transactionId: signature,
+                ledgerCanisterId: params.ledgerCanisterId,
+                amount: params.amount.toString(),
+                metadata: { ...(params.metadata || {}), icpay_solana_tx_sig: signature },
+            });
+            return finalQuick;
+        }
+        // No prebuilt transaction available and builder fallback disabled
+        throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.API_ERROR, message: 'Payment intent missing transactionBase64 for Solana' });
+    }
     async processEvmPayment(params) {
         const contractAddress = params.contractAddress;
         if (!contractAddress) {
@@ -677,9 +927,9 @@ class Icpay {
         // Prefer selectors from API; otherwise fallback to constants provided by backend
         const apiSelectors = params.request.__functionSelectors || {};
         const selector = {
-            // API provides the overloaded signatures under these names
-            payNative: apiSelectors.payNative || '0x4e47ff88', // payNative(bytes32,uint64,uint256)
-            payERC20: apiSelectors.payERC20 || '0x87b9fed2', // payERC20(bytes32,uint64,address,uint256,uint256)
+            // Always use relay overloads; server maps payNative/payERC20 to relay selectors
+            payNative: apiSelectors.payNative || '0x8062dd66', // payNative(bytes32,uint64,uint256,address)
+            payERC20: apiSelectors.payERC20 || '0xc20b92c7', // payERC20(bytes32,uint64,address,uint256,uint256,address)
         };
         // Build EVM id bytes32 using shared helper
         const accountIdNum = BigInt(params.accountCanisterId || 0);
@@ -698,6 +948,7 @@ class Icpay {
                 idHexLen: idHex?.length,
                 selectorPayNative: selector.payNative,
                 selectorPayERC20: selector.payERC20,
+                recipientAddress: params.request?.recipientAddress || null,
             });
         }
         catch { }
@@ -730,15 +981,21 @@ class Icpay {
             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 });
+            const ZERO = '0x0000000000000000000000000000000000000000';
+            const reqAny = params.request;
+            const recipientPrimary = String(reqAny?.recipientAddress || '').trim();
+            const recipientFromMap = String((reqAny?.recipientAddresses || {})?.evm || '').trim();
+            const recipientCandidate = recipientPrimary || recipientFromMap;
+            const recipient = /^0x[a-fA-F0-9]{40}$/.test(recipientCandidate) ? recipientCandidate : ZERO;
             if (isNative) {
                 const externalCostStr = params.request?.__externalCostAmount;
                 const externalCost = externalCostStr != null && externalCostStr !== '' ? BigInt(String(externalCostStr)) : 0n;
                 const extSel = selector.payNative;
                 if (!extSel) {
-                    throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG, message: 'Missing payNative overload selector from API; update API/chain metadata.' });
+                    throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG, message: 'Missing payNative selector from API; update API/chain metadata.' });
                 }
-                const data = extSel + idHex + toUint64(accountIdNum) + toUint256(externalCost);
-                (0, utils_1.debugLog)(this.config.debug || false, 'evm native tx', { to: contractAddress, from: owner, dataLen: data.length, value: amountHex });
+                const data = extSel + idHex + toUint64(accountIdNum) + toUint256(externalCost) + toAddressPadded(recipient);
+                (0, utils_1.debugLog)(this.config.debug || false, 'evm native tx', { to: contractAddress, from: owner, dataLen: data.length, value: amountHex, recipient });
                 txHash = await eth.request({ method: 'eth_sendTransaction', params: [{ from: owner, to: contractAddress, data, value: amountHex }] });
             }
             else {
@@ -763,10 +1020,11 @@ class Icpay {
                 const externalCost = externalCostStr != null && externalCostStr !== '' ? BigInt(String(externalCostStr)) : 0n;
                 const extSel = selector.payERC20;
                 if (!extSel) {
-                    throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG, message: 'Missing payERC20 overload selector from API; update API/chain metadata.' });
+                    throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG, message: 'Missing payERC20 selector from API; update API/chain metadata.' });
                 }
-                const data = extSel + idHex + toUint64(accountIdNum) + toAddressPadded(String(tokenAddress)) + toUint256(params.amount) + toUint256(externalCost);
-                (0, utils_1.debugLog)(this.config.debug || false, 'evm erc20 pay', { to: contractAddress, from: owner, token: tokenAddress, dataLen: data.length });
+                const base = idHex + toUint64(accountIdNum) + toAddressPadded(String(tokenAddress)) + toUint256(params.amount) + toUint256(externalCost);
+                const data = extSel + base + toAddressPadded(recipient);
+                (0, utils_1.debugLog)(this.config.debug || false, 'evm erc20 pay', { to: contractAddress, from: owner, token: tokenAddress, dataLen: data.length, recipient });
                 txHash = await eth.request({ method: 'eth_sendTransaction', params: [{ from: owner, to: contractAddress, data }] });
             }
         }
@@ -931,7 +1189,8 @@ class Icpay {
             // Resolve ledgerCanisterId from symbol if needed (legacy). If tokenShortcode provided, no resolution required.
             let ledgerCanisterId = request.ledgerCanisterId;
             const tokenShortcode = request?.tokenShortcode;
-            if (!ledgerCanisterId && !tokenShortcode && !request.symbol) {
+            const isOnrampFlow = (request?.onrampPayment === true) || (this?.config?.onrampPayment === true);
+            if (!ledgerCanisterId && !tokenShortcode && !request.symbol && !isOnrampFlow) {
                 const err = new errors_1.IcpayError({
                     code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
                     message: 'Provide either tokenShortcode or ledgerCanisterId (symbol is deprecated).',
@@ -948,33 +1207,45 @@ class Icpay {
             let intentChainId;
             let accountCanisterId;
             let resolvedAmountStr = typeof request.amount === 'string' ? request.amount : (request.amount != null ? String(request.amount) : undefined);
+            let intentResp;
             try {
                 (0, utils_1.debugLog)(this.config.debug || false, 'creating payment intent');
-                // 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];
+                // Resolve expected sender principal:
+                // Start with any value explicitly provided on the request or via connectedWallet.
+                let expectedSenderPrincipal = request.expectedSenderPrincipal ||
+                    this.connectedWallet?.owner ||
+                    this.connectedWallet?.principal?.toString();
+                // If none yet and a Solana provider is present (e.g., Phantom), prefer its publicKey (base58).
+                try {
+                    const solProv = this.config?.solanaProvider || globalThis?.solana;
+                    const solPk = solProv?.publicKey ? String(solProv.publicKey) : undefined;
+                    if (!expectedSenderPrincipal && solPk) {
+                        expectedSenderPrincipal = String(solPk);
+                    }
+                }
+                catch { }
+                // Only if still missing, fall back to EVM accounts.
+                if (!expectedSenderPrincipal) {
+                    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)] : accounts[0];
+                                }
+                                else {
+                                    expectedSenderPrincipal = accounts[0];
+                                }
                             }
                         }
+                        catch { }
                     }
-                    catch { }
                 }
-                if (!expectedSenderPrincipal) {
+                if (!expectedSenderPrincipal && !((request?.onrampPayment === true) || (this?.config?.onrampPayment === true))) {
                     throw new errors_1.IcpayError({
                         code: errors_1.ICPAY_ERROR_CODES.WALLET_NOT_CONNECTED,
                         message: 'Wallet must be connected to create payment intent',
@@ -986,7 +1257,19 @@ class Icpay {
                 const onramp = (request.onrampPayment === true || this.config.onrampPayment === true) && this.config.onrampDisabled !== true ? true : false;
                 const meta = request?.metadata || {};
                 const isAtxp = Boolean(meta?.icpay_atxp_request) && typeof (meta?.atxp_request_id) === 'string';
-                let intentResp;
+                // Resolve recipientAddress only for non-onramp flows
+                const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+                const reqAny = request;
+                const addrObj = (reqAny?.recipientAddresses) || {};
+                const candidateEvm = addrObj.evm ? addrObj.evm : undefined;
+                const candidateIC = addrObj.ic ? addrObj.ic : undefined;
+                const candidateSol = addrObj.sol ? addrObj.sol : undefined;
+                let recipientAddress = undefined;
+                if (!onramp) {
+                    // Choose a default to persist on the intent; EVM will override to ZERO if non-hex when building tx
+                    recipientAddress = (reqAny?.recipientAddress) || candidateEvm || candidateIC || candidateSol || ZERO_ADDRESS;
+                    (0, utils_1.debugLog)(this.config.debug || false, 'recipientAddress resolved for intent', { recipientAddress });
+                }
                 if (isAtxp) {
                     // Route ATXP intents to the ATXP endpoint so they link to the request
                     const atxpRequestId = String(meta.atxp_request_id);
@@ -994,25 +1277,42 @@ class Icpay {
                     intentResp = await this.publicApiClient.post(endpoint, {
                         tokenShortcode: tokenShortcode || undefined,
                         description: request.description,
+                        recipientAddress,
+                        recipientAddresses: request?.recipientAddresses || undefined,
+                        externalCostAmount: request?.externalCostAmount ?? request?.metadata?.externalCostAmount ?? undefined,
                     });
                 }
                 else {
-                    intentResp = await this.publicApiClient.post('/sdk/public/payments/intents', {
-                        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,
-                    });
+                    if (onramp) {
+                        // Route onramp flows to the dedicated onramp endpoint without requiring token/ledger
+                        intentResp = await this.publicApiClient.post('/sdk/public/onramp/intents', {
+                            usdAmount: request.amountUsd,
+                            description: request.description,
+                            metadata: normalizeSdkMetadata(request.metadata || {}),
+                            widgetParams: request.widgetParams || undefined,
+                            recipientAddresses: request?.recipientAddresses || undefined,
+                        });
+                    }
+                    else {
+                        intentResp = await this.publicApiClient.post('/sdk/public/payments/intents', {
+                            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: normalizeSdkMetadata(request.metadata || {}),
+                            amountUsd: request.amountUsd,
+                            // With tokenShortcode, backend derives chain. Keep legacy chainId for old flows.
+                            chainId: tokenShortcode ? undefined : request.chainId,
+                            widgetParams: request.widgetParams || undefined,
+                            recipientAddress,
+                            recipientAddresses: request?.recipientAddresses || undefined,
+                            externalCostAmount: request?.externalCostAmount ?? request?.metadata?.externalCostAmount ?? undefined,
+                        });
+                    }
                 }
                 paymentIntentId = intentResp?.paymentIntent?.id || null;
                 paymentIntentCode = intentResp?.paymentIntent?.intentCode ?? null;
@@ -1026,21 +1326,35 @@ class Icpay {
                 const rpcChainId = intentResp?.paymentIntent?.rpcChainId || null;
                 const functionSelectors = intentResp?.paymentIntent?.functionSelectors || null;
                 const externalCostAmount = intentResp?.paymentIntent?.externalCostAmount || null;
+                const transactionBase64 = intentResp?.paymentIntent?.transactionBase64 || 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
+                // Emit transaction created event only for non-onramp flows
                 if (paymentIntentId) {
-                    this.emit('icpay-sdk-transaction-created', {
-                        paymentIntentId,
-                        amount: resolvedAmountStr,
-                        ledgerCanisterId,
-                        expectedSenderPrincipal,
-                        accountCanisterId,
-                    });
+                    if (!isOnrampFlow) {
+                        this.emit('icpay-sdk-transaction-created', {
+                            paymentIntentId,
+                            amount: resolvedAmountStr,
+                            ledgerCanisterId,
+                            expectedSenderPrincipal,
+                            accountCanisterId,
+                        });
+                    }
+                    else {
+                        // Optional: emit an onramp-specific event for UI
+                        try {
+                            this.emit?.('icpay-sdk-onramp-intent-created', {
+                                paymentIntentId,
+                                amountUsd: request.amountUsd,
+                                onramp: intentResp?.onramp,
+                            });
+                        }
+                        catch { }
+                    }
                 }
                 request.__onramp = onrampData;
                 request.__contractAddress = contractAddress;
@@ -1049,6 +1363,7 @@ class Icpay {
                 request.__functionSelectors = functionSelectors;
                 request.__rpcChainId = rpcChainId;
                 request.__externalCostAmount = externalCostAmount;
+                request.__transactionBase64 = transactionBase64;
             }
             catch (e) {
                 // Do not proceed without a payment intent
@@ -1070,6 +1385,18 @@ class Icpay {
                 this.emitError(err);
                 throw err;
             }
+            // If this is an onramp flow, do NOT proceed with chain processing. Return onramp payload instead.
+            const onrampPayload = request.__onramp;
+            if (isOnrampFlow && onrampPayload) {
+                const early = {
+                    paymentIntentId,
+                    paymentIntentCode,
+                    onramp: onrampPayload,
+                    paymentIntent: intentResp?.paymentIntent || null,
+                };
+                this.emitMethodSuccess('createPayment', early);
+                return early;
+            }
             const amount = BigInt(resolvedAmountStr);
             // Build packed memo
             const acctIdNum = parseInt(accountCanisterId);
@@ -1212,7 +1539,7 @@ class Icpay {
     /**
      * Notify canister about ledger transaction using anonymous actor (no signature required)
      */
-    async notifyLedgerTransaction(canisterId, ledgerCanisterId, blockIndex) {
+    async notifyLedgerTransaction(canisterId, ledgerCanisterId, blockIndex, opts) {
         this.emitMethodStart('notifyLedgerTransaction', { canisterId, ledgerCanisterId, blockIndex: blockIndex.toString() });
         // Create anonymous actor for canister notifications (no signature required)
         // Retry on transient certificate TrustError (clock skew)
@@ -1222,11 +1549,45 @@ class Icpay {
             try {
                 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
-                });
+                // Prefer v2 when available and we have required inputs
+                const maybeV2 = actor?.notify_ledger_transaction_v2;
+                const haveAcct = typeof opts?.accountCanisterId === 'number' && Number.isFinite(opts.accountCanisterId);
+                if (maybeV2 && haveAcct) {
+                    try {
+                        (0, utils_1.debugLog)(this.config.debug || false, 'notify using v2', { ledgerCanisterId, blockIndex: blockIndex.toString(), accountCanisterId: opts?.accountCanisterId, hasExternalCost: opts?.externalCostAmount != null, hasRecipient: Boolean((opts?.recipientPrincipal || '').trim()) });
+                    }
+                    catch { }
+                    const externalCost = (() => {
+                        if (opts?.externalCostAmount == null)
+                            return [];
+                        try {
+                            const v = BigInt(String(opts.externalCostAmount));
+                            if (v < 0n)
+                                return [];
+                            return [v];
+                        }
+                        catch {
+                            return [];
+                        }
+                    })();
+                    const recipient = (() => {
+                        const s = (opts?.recipientPrincipal || '').trim();
+                        return s ? [s] : [];
+                    })();
+                    result = await actor.notify_ledger_transaction_v2({ ledger_canister_id: ledgerCanisterId, block_index: blockIndex }, BigInt(opts.accountCanisterId), externalCost, recipient);
+                }
+                else {
+                    try {
+                        (0, utils_1.debugLog)(this.config.debug || false, 'notify using v1 (fallback)', { ledgerCanisterId, blockIndex: blockIndex.toString(), haveAcct });
+                    }
+                    catch { }
+                    // Fallback to legacy notify
+                    result = await actor.notify_ledger_transaction({
+                        // Canister expects text for ledger_canister_id
+                        ledger_canister_id: ledgerCanisterId,
+                        block_index: blockIndex
+                    });
+                }
                 break;
             }
             catch (e) {
@@ -1583,7 +1944,8 @@ class Icpay {
             // If tokenShortcode provided, skip canister resolution; otherwise resolve from symbol if needed
             const tokenShortcode = request?.tokenShortcode;
             let ledgerCanisterId = request.ledgerCanisterId;
-            if (!ledgerCanisterId && !tokenShortcode && !request.symbol) {
+            const isOnrampFlow = request?.onrampPayment === true || this?.config?.onrampPayment === true;
+            if (!ledgerCanisterId && !tokenShortcode && !request.symbol && !isOnrampFlow) {
                 const err = new errors_1.IcpayError({
                     code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG,
                     message: 'Provide either tokenShortcode or ledgerCanisterId (symbol is deprecated).',
@@ -1603,6 +1965,8 @@ class Icpay {
                 onrampPayment: request.onrampPayment,
                 widgetParams: request.widgetParams,
                 chainId: tokenShortcode ? undefined : request.chainId,
+                recipientAddress: request?.recipientAddress || '0x0000000000000000000000000000000000000000',
+                recipientAddresses: request?.recipientAddresses,
             };
             const res = await this.createPayment(createTransactionRequest);
             this.emitMethodSuccess('createPaymentUsd', res);
@@ -1643,10 +2007,21 @@ class Icpay {
                 symbol: tokenShortcode ? undefined : request.symbol,
                 ledgerCanisterId: tokenShortcode ? undefined : ledgerCanisterId,
                 description: request.description,
-                metadata: request.metadata,
+                metadata: normalizeSdkMetadata(request.metadata || {}),
                 chainId: tokenShortcode ? undefined : request.chainId,
                 x402: true,
+                recipientAddress: request?.recipientAddress || '0x0000000000000000000000000000000000000000',
             };
+            // Include Solana payerPublicKey if available so server can build unsigned tx inline for Solana x402
+            try {
+                const w = globalThis?.window || globalThis;
+                const sol = this.config?.solanaProvider || w?.solana || w?.phantom?.solana;
+                const pk = sol?.publicKey?.toBase58?.() || sol?.publicKey || null;
+                if (pk && typeof pk === 'string') {
+                    body.payerPublicKey = pk;
+                }
+            }
+            catch { }
             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
@@ -1693,13 +2068,1316 @@ class Icpay {
                         const acceptsArr = Array.isArray(data?.accepts) ? data.accepts : [];
                         let requirement = acceptsArr.length > 0 ? acceptsArr[0] : null;
                         if (requirement) {
+                            // Determine network once for error handling policy
+                            const isSol = typeof requirement?.network === 'string' && String(requirement.network).toLowerCase().startsWith('solana:');
                             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
+                                const providerForHeader = isSol
+                                    ? (this.config?.solanaProvider || globalThis?.solana || globalThis?.phantom?.solana)
+                                    : (this.config?.evmProvider || globalThis?.ethereum);
+                                let paymentHeader = null;
+                                // IC x402: client-side settle via allowance + canister pull
+                                const isIc = typeof requirement?.network === 'string' && String(requirement.network).toLowerCase().startsWith('icp:');
+                                if (isIc) {
+                                    // IC x402: client ensures allowance; then call API settle so services (controller) pulls and notifies
+                                    if (!this.actorProvider) {
+                                        throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.WALLET_PROVIDER_NOT_AVAILABLE, message: 'actorProvider required for IC x402' });
+                                    }
+                                    // Ensure allowance first
+                                    const asset = String(requirement?.asset || requirement?.payTo || '').trim();
+                                    const amountStr = String(requirement?.maxAmountRequired || '0');
+                                    const amountBn = BigInt(amountStr);
+                                    if (!asset || amountBn <= 0n) {
+                                        throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.API_ERROR, message: 'Invalid x402 IC requirement (asset/amount)' });
+                                    }
+                                    // Approve spender (ICPay canister) for amount
+                                    if (!this.icpayCanisterId) {
+                                        // Prefer payTo from x402 requirement as ICPay canister id if present
+                                        try {
+                                            const maybe = String(requirement?.payTo || '');
+                                            if (maybe) {
+                                                // Validate shape by attempting to parse
+                                                principal_1.Principal.fromText(maybe);
+                                                this.icpayCanisterId = maybe;
+                                            }
+                                        }
+                                        catch { }
+                                    }
+                                    if (!this.icpayCanisterId) {
+                                        // Fallback to account lookup
+                                        const acctInfo = await this.fetchAccountInfo();
+                                        this.icpayCanisterId = acctInfo?.icpayCanisterId?.toString?.() || this.icpayCanisterId;
+                                    }
+                                    if (!this.icpayCanisterId) {
+                                        throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.INVALID_CONFIG, message: 'Missing ICPay canister id for IC x402' });
+                                    }
+                                    const ledgerActor = this.actorProvider(asset, ledger_did_js_1.idlFactory);
+                                    try {
+                                        // Fetch transfer fee and approve amount + fee to avoid InsufficientAllowance
+                                        let feeBn = 0n;
+                                        try {
+                                            const f = await ledgerActor.icrc1_fee();
+                                            feeBn = typeof f === 'bigint' ? f : BigInt(f);
+                                        }
+                                        catch { }
+                                        const approveAmount = amountBn + (feeBn > 0n ? feeBn : 0n);
+                                        await ledgerActor.icrc2_approve({
+                                            fee: [],
+                                            memo: [],
+                                            from_subaccount: [],
+                                            created_at_time: [],
+                                            amount: approveAmount,
+                                            expected_allowance: [],
+                                            expires_at: [],
+                                            spender: { owner: principal_1.Principal.fromText(this.icpayCanisterId), subaccount: [] },
+                                        });
+                                    }
+                                    catch (apprErr) {
+                                        throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.TRANSACTION_FAILED, message: 'ICRC-2 approve failed', details: apprErr });
+                                    }
+                                    // Obtain payer principal if available
+                                    let payerPrincipal = null;
+                                    try {
+                                        const p = this.wallet.getPrincipal();
+                                        if (p)
+                                            payerPrincipal = p.toText();
+                                        else if (this.connectedWallet && typeof this.connectedWallet.getPrincipal === 'function') {
+                                            const maybe = await this.connectedWallet.getPrincipal();
+                                            if (typeof maybe === 'string')
+                                                payerPrincipal = maybe;
+                                        }
+                                        else if (this.connectedWallet?.principal) {
+                                            payerPrincipal = String(this.connectedWallet.principal);
+                                        }
+                                    }
+                                    catch { }
+                                    // Build memo from accountCanisterId and intentCode for matching on services
+                                    let memoBytes = undefined;
+                                    try {
+                                        const extra = requirement?.extra || {};
+                                        const accIdStr = String(extra?.accountCanisterId || '');
+                                        const icIntentCodeStr = String(extra?.intentCode || '');
+                                        const accIdNum = accIdStr ? parseInt(accIdStr, 10) : 0;
+                                        const icIntentCodeNum = icIntentCodeStr ? parseInt(icIntentCodeStr, 10) : 0;
+                                        if (Number.isFinite(accIdNum) && accIdNum > 0 && Number.isFinite(icIntentCodeNum) && icIntentCodeNum > 0) {
+                                            const packed = this.createPackedMemo(accIdNum, icIntentCodeNum);
+                                            memoBytes = Array.from(packed);
+                                        }
+                                    }
+                                    catch { }
+                                    // Call API to settle IC x402 via services (controller will pull + notify)
+                                    const settleRespIc = await this.publicApiClient.post('/sdk/public/payments/x402/settle', {
+                                        paymentIntentId,
+                                        paymentHeader: null, // not used for IC allowance path
+                                        paymentRequirements: requirement,
+                                        payerPrincipal,
+                                        memoBytes: memoBytes || null,
+                                    });
+                                    const statusIc = (settleRespIc?.status || settleRespIc?.paymentIntent?.status || 'completed').toString().toLowerCase();
+                                    const amountIc = (settleRespIc?.paymentIntent?.amount && String(settleRespIc.paymentIntent.amount)) ||
+                                        (typeof usdAmount === 'number' ? String(usdAmount) : request?.amount?.toString?.() || '0');
+                                    const outIc = {
+                                        transactionId: Number(settleRespIc?.canisterTxId || 0),
+                                        status: statusIc === 'succeeded' ? 'completed' : statusIc,
+                                        amount: amountIc,
+                                        recipientCanister: this.icpayCanisterId,
+                                        timestamp: new Date(),
+                                        metadata: { ...(request.metadata || {}), icpay_x402: true, icpay_network: 'ic' },
+                                        payment: settleRespIc || null,
+                                    };
+                                    const isTerminalIc = (() => {
+                                        const s = String(outIc.status || '').toLowerCase();
+                                        return s === 'completed' || s === 'succeeded' || s === 'failed' || s === 'canceled' || s === 'cancelled' || s === 'mismatched';
+                                    })();
+                                    if (isTerminalIc) {
+                                        if (outIc.status === 'completed') {
+                                            this.emit('icpay-sdk-transaction-completed', outIc);
+                                        }
+                                        else if (outIc.status === 'failed') {
+                                            this.emit('icpay-sdk-transaction-failed', outIc);
+                                        }
+                                        else {
+                                            this.emit('icpay-sdk-transaction-updated', outIc);
+                                        }
+                                        this.emitMethodSuccess('createPaymentX402Usd', outIc);
+                                        return outIc;
+                                    }
+                                    try {
+                                        this.emit('icpay-sdk-transaction-updated', outIc);
+                                    }
+                                    catch { }
+                                    const waitedIc = await this.awaitIntentTerminal({
+                                        paymentIntentId,
+                                        ledgerCanisterId: asset,
+                                        amount: amountIc,
+                                        canisterTransactionId: String(settleRespIc?.canisterTxId || ''),
+                                        metadata: { ...(request.metadata || {}), icpay_x402: true, icpay_network: 'ic' },
+                                    });
+                                    this.emitMethodSuccess('createPaymentX402Usd', waitedIc);
+                                    return waitedIc;
+                                }
+                                if (!isSol) {
+                                    paymentHeader = await (0, builders_1.buildAndSignX402PaymentHeader)(requirement, {
+                                        x402Version: Number(data?.x402Version || 2),
+                                        debug: this.config?.debug || false,
+                                        provider: providerForHeader,
+                                    });
+                                }
+                                if (isSol) {
+                                    // Solana x402: prefer message-sign flow if server provided a signable message
+                                    const signableMsgB64 = requirement?.extra?.signableMessageBase64;
+                                    const signableFields = requirement?.extra?.signableFields || {};
+                                    const wSolCtx = globalThis?.window || globalThis;
+                                    const sol = providerForHeader;
+                                    if (!sol)
+                                        throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.WALLET_PROVIDER_NOT_AVAILABLE, message: 'Solana provider not available (window.solana)' });
+                                    // Get public key (already connected from widget)
+                                    let fromBase58 = null;
+                                    try {
+                                        fromBase58 = sol?.publicKey?.toBase58?.() || sol?.publicKey || null;
+                                    }
+                                    catch { }
+                                    if (!fromBase58 && typeof sol.connect === 'function') {
+                                        try {
+                                            const con = await sol.connect({ onlyIfTrusted: false });
+                                            fromBase58 = con?.publicKey?.toBase58?.() || con?.publicKey || null;
+                                        }
+                                        catch { }
+                                    }
+                                    if (!fromBase58)
+                                        throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.WALLET_NOT_CONNECTED, message: 'Solana wallet not connected' });
+                                    // No ICPay popups; only wallet UI should be shown for signing
+                                    if (signableMsgB64) {
+                                        // Sign the provided message and settle via header (services will submit)
+                                        // Ensure explicit connect prompt before signing
+                                        if (typeof sol?.connect === 'function') {
+                                            try {
+                                                await sol.connect({ onlyIfTrusted: false });
+                                            }
+                                            catch { }
+                                        }
+                                        let sigB64 = null;
+                                        const msgBytes = u8FromBase64(signableMsgB64);
+                                        const msgB58ForReq = base58Encode(msgBytes);
+                                        // Attempts in order (strict):
+                                        // 1) Wallet Standard: request colon form with Uint8Array
+                                        if (!sigB64 && sol?.request) {
+                                            try {
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(request) params', { method: 'solana:signMessage', shape: 'object{message:Uint8Array}', len: msgBytes.length });
+                                                }
+                                                catch { }
+                                                const r0 = await sol.request({ method: 'solana:signMessage', params: { message: msgBytes } });
+                                                if (typeof r0 === 'string') {
+                                                    try {
+                                                        const b = base58Decode(r0);
+                                                        sigB64 = b64FromBytes(b);
+                                                    }
+                                                    catch {
+                                                        sigB64 = r0;
+                                                    }
+                                                }
+                                                else if (r0 && typeof r0.signature === 'string') {
+                                                    try {
+                                                        const b = base58Decode(r0.signature);
+                                                        sigB64 = b64FromBytes(b);
+                                                    }
+                                                    catch {
+                                                        sigB64 = r0.signature;
+                                                    }
+                                                }
+                                                else if (r0 && (r0.byteLength != null || ArrayBuffer.isView(r0))) {
+                                                    const b = r0 instanceof Uint8Array ? r0 : new Uint8Array(r0);
+                                                    if (b && b.length === 64)
+                                                        sigB64 = b64FromBytes(b);
+                                                }
+                                                else if (r0 && typeof r0 === 'object' && Array.isArray(r0.data)) {
+                                                    const b = Uint8Array.from(r0.data);
+                                                    if (b && b.length === 64)
+                                                        sigB64 = b64FromBytes(b);
+                                                }
+                                            }
+                                            catch (e0) {
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol solana:signMessage failed', { error: String(e0) });
+                                                }
+                                                catch { }
+                                            }
+                                        }
+                                        // 2) Native: signMessage(Uint8Array)
+                                        if (!sigB64 && typeof sol?.signMessage === 'function') {
+                                            try {
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(fn) Uint8Array');
+                                                }
+                                                catch { }
+                                                const r2 = await sol.signMessage(msgBytes);
+                                                if (r2 && (r2.byteLength != null || ArrayBuffer.isView(r2))) {
+                                                    const b = r2 instanceof Uint8Array ? r2 : new Uint8Array(r2);
+                                                    if (b && b.length === 64)
+                                                        sigB64 = b64FromBytes(b);
+                                                }
+                                                else if (typeof r2 === 'string') {
+                                                    try {
+                                                        const b = base58Decode(r2);
+                                                        sigB64 = b64FromBytes(b);
+                                                    }
+                                                    catch {
+                                                        sigB64 = r2;
+                                                    }
+                                                }
+                                                else if (r2 && typeof r2 === 'object' && typeof r2.signature === 'string') {
+                                                    const s = r2.signature;
+                                                    try {
+                                                        const b = base58Decode(s);
+                                                        sigB64 = b64FromBytes(b);
+                                                    }
+                                                    catch {
+                                                        sigB64 = s;
+                                                    }
+                                                }
+                                            }
+                                            catch (e2) {
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(fn) failed', { error: String(e2) });
+                                                }
+                                                catch { }
+                                            }
+                                        }
+                                        // 3) Request: signMessage with Uint8Array payload (legacy method name)
+                                        if (!sigB64 && sol?.request) {
+                                            try {
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(request) params', { method: 'signMessage', shape: 'object{message:Uint8Array}', len: msgBytes.length });
+                                                }
+                                                catch { }
+                                                const r3 = await sol.request({ method: 'signMessage', params: { message: msgBytes } });
+                                                if (typeof r3 === 'string') {
+                                                    try {
+                                                        const b = base58Decode(r3);
+                                                        sigB64 = b64FromBytes(b);
+                                                    }
+                                                    catch {
+                                                        sigB64 = r3;
+                                                    }
+                                                }
+                                                else if (r3 && typeof r3.signature === 'string') {
+                                                    try {
+                                                        const b = base58Decode(r3.signature);
+                                                        sigB64 = b64FromBytes(b);
+                                                    }
+                                                    catch {
+                                                        sigB64 = r3.signature;
+                                                    }
+                                                }
+                                                else if (r3 && (r3.byteLength != null || ArrayBuffer.isView(r3))) {
+                                                    const b = r3 instanceof Uint8Array ? r3 : new Uint8Array(r3);
+                                                    if (b && b.length === 64)
+                                                        sigB64 = b64FromBytes(b);
+                                                }
+                                                else if (r3 && typeof r3 === 'object' && Array.isArray(r3.data)) {
+                                                    const b = Uint8Array.from(r3.data);
+                                                    if (b && b.length === 64)
+                                                        sigB64 = b64FromBytes(b);
+                                                }
+                                            }
+                                            catch (e3) {
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(request Uint8Array) failed', { error: String(e3) });
+                                                }
+                                                catch { }
+                                            }
+                                        }
+                                        // 4) Request: signMessage with base58
+                                        if (!sigB64 && sol?.request) {
+                                            try {
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(request) params', { method: 'signMessage', shape: 'object{message:base58}', len: msgB58ForReq.length });
+                                                }
+                                                catch { }
+                                                const r4 = await sol.request({ method: 'signMessage', params: { message: msgB58ForReq } });
+                                                if (typeof r4 === 'string') {
+                                                    try {
+                                                        const b = base58Decode(r4);
+                                                        sigB64 = b64FromBytes(b);
+                                                    }
+                                                    catch {
+                                                        sigB64 = r4;
+                                                    }
+                                                }
+                                                else if (r4 && typeof r4.signature === 'string') {
+                                                    try {
+                                                        const b = base58Decode(r4.signature);
+                                                        sigB64 = b64FromBytes(b);
+                                                    }
+                                                    catch {
+                                                        sigB64 = r4.signature;
+                                                    }
+                                                }
+                                                else if (r4 && (r4.byteLength != null || ArrayBuffer.isView(r4))) {
+                                                    const b = r4 instanceof Uint8Array ? r4 : new Uint8Array(r4);
+                                                    if (b && b.length === 64)
+                                                        sigB64 = b64FromBytes(b);
+                                                }
+                                                else if (r4 && typeof r4 === 'object' && Array.isArray(r4.data)) {
+                                                    const b = Uint8Array.from(r4.data);
+                                                    if (b && b.length === 64)
+                                                        sigB64 = b64FromBytes(b);
+                                                }
+                                            }
+                                            catch (e4) {
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(request legacy) failed', { error: String(e4) });
+                                                }
+                                                catch { }
+                                            }
+                                        }
+                                        if (sigB64) {
+                                            // Build x402 header and settle
+                                            const header = (0, builders_1.buildX402HeaderFromAuthorization)({
+                                                x402Version: Number(data?.x402Version || 2),
+                                                scheme: String(requirement?.scheme || 'exact'),
+                                                network: String(requirement?.network || ''),
+                                                from: String(fromBase58 || ''),
+                                                to: String(requirement?.payTo || ''),
+                                                value: String(requirement?.maxAmountRequired || '0'),
+                                                validAfter: String(signableFields?.validAfter || '0'),
+                                                validBefore: String(signableFields?.validBefore || '0'),
+                                                nonce: String(signableFields?.nonceHex || ''),
+                                                signature: String(sigB64),
+                                            });
+                                            const headerJson = JSON.stringify(header);
+                                            const headerB64 = (() => {
+                                                try {
+                                                    const Buf = globalThis.Buffer;
+                                                    return Buf ? Buf.from(headerJson, 'utf8').toString('base64') : globalThis?.btoa?.(headerJson) || '';
+                                                }
+                                                catch {
+                                                    return '';
+                                                }
+                                            })();
+                                            const settleRespSol = await this.publicApiClient.post('/sdk/public/payments/x402/settle', {
+                                                paymentIntentId,
+                                                paymentHeader: headerB64,
+                                                paymentRequirements: requirement,
+                                            });
+                                            try {
+                                                (0, utils_1.debugLog)(this.config?.debug || false, 'x402 (sol) settle via header response', {
+                                                    ok: settleRespSol?.ok,
+                                                    status: settleRespSol?.status,
+                                                    paymentIntentId: settleRespSol?.paymentIntent?.id,
+                                                    paymentId: settleRespSol?.payment?.id,
+                                                    rawKeys: Object.keys(settleRespSol || {}),
+                                                });
+                                            }
+                                            catch { }
+                                            const statusSolHdr = (settleRespSol?.status || settleRespSol?.paymentIntent?.status || 'completed').toString().toLowerCase();
+                                            const amountSolHdr = (settleRespSol?.paymentIntent?.amount && String(settleRespSol.paymentIntent.amount)) ||
+                                                (typeof usdAmount === 'number' ? String(usdAmount) : request?.amount?.toString?.() || '0');
+                                            const outSolHdr = {
+                                                transactionId: Number(settleRespSol?.canisterTxId || 0),
+                                                status: statusSolHdr === 'succeeded' ? 'completed' : statusSolHdr,
+                                                amount: amountSolHdr,
+                                                recipientCanister: ledgerCanisterId,
+                                                timestamp: new Date(),
+                                                metadata: { ...(request.metadata || {}), icpay_x402: true },
+                                                payment: settleRespSol || null,
+                                            };
+                                            const isTerminalSolHdr = (() => {
+                                                const s = String(outSolHdr.status || '').toLowerCase();
+                                                return s === 'completed' || s === 'succeeded' || s === 'failed' || s === 'canceled' || s === 'cancelled' || s === 'mismatched';
+                                            })();
+                                            if (isTerminalSolHdr) {
+                                                if (outSolHdr.status === 'completed') {
+                                                    this.emit('icpay-sdk-transaction-completed', outSolHdr);
+                                                }
+                                                else if (outSolHdr.status === 'failed') {
+                                                    this.emit('icpay-sdk-transaction-failed', outSolHdr);
+                                                }
+                                                else {
+                                                    this.emit('icpay-sdk-transaction-updated', outSolHdr);
+                                                }
+                                                this.emitMethodSuccess('createPaymentX402Usd', outSolHdr);
+                                                return outSolHdr;
+                                            }
+                                            // Non-terminal: wait until terminal via notify loop
+                                            try {
+                                                this.emit('icpay-sdk-transaction-updated', outSolHdr);
+                                            }
+                                            catch { }
+                                            const waitedSolHdr = await this.awaitIntentTerminal({
+                                                paymentIntentId,
+                                                ledgerCanisterId: ledgerCanisterId,
+                                                amount: amountSolHdr,
+                                                metadata: { ...(request.metadata || {}), icpay_x402: true },
+                                            });
+                                            this.emitMethodSuccess('createPaymentX402Usd', waitedSolHdr);
+                                            return waitedSolHdr;
+                                        }
+                                        else {
+                                            // Fallback: if API provided an unsigned transaction, try transaction-signing path
+                                            const fallbackTx = requirement?.extra?.transactionBase64;
+                                            if (!fallbackTx) {
+                                                throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.TRANSACTION_FAILED, message: 'Wallet did not sign message' });
+                                            }
+                                            // Inject for transaction-signing fallback below
+                                            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                                            const __fallbackTxBase64 = String(fallbackTx);
+                                            // Reassign txBase64 by creating a new block scope later; use a marker in metadata to indicate fallback used
+                                            try {
+                                                (0, utils_1.debugLog)(this.config?.debug || false, 'sol x402 fallback to transaction signing');
+                                            }
+                                            catch { }
+                                            // Use local variable for fallback path
+                                            let signedTxB64 = null;
+                                            let signerSigBase58 = null;
+                                            const inlineMsgB58Fallback = requirement?.extra?.messageBase58 || undefined;
+                                            // Ensure explicit connect to prompt wallet if needed
+                                            if (typeof sol?.connect === 'function') {
+                                                try {
+                                                    await sol.connect({ onlyIfTrusted: false });
+                                                }
+                                                catch { }
+                                            }
+                                            // Do NOT submit from wallet; only sign, then relay to backend
+                                            // Try signAllTransactions (array) then signTransaction with message:base58 (prefer) then transaction:base64
+                                            if (sol?.request) {
+                                                try {
+                                                    let r = null;
+                                                    // 0) Try Wallet Standard signAllTransactions with Uint8Array
+                                                    try {
+                                                        const txBytes = u8FromBase64(__fallbackTxBase64);
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signAllTransactions(request) params', { method: 'solana:signAllTransactions', shape: 'object{transactions:Uint8Array[]}', count: 1, txLen: txBytes.length });
+                                                        }
+                                                        catch { }
+                                                        r = await sol.request({ method: 'solana:signAllTransactions', params: { transactions: [txBytes] } });
+                                                    }
+                                                    catch { }
+                                                    // 0b) Legacy signAllTransactions with Uint8Array
+                                                    if (!r) {
+                                                        try {
+                                                            const txBytes = u8FromBase64(__fallbackTxBase64);
+                                                            try {
+                                                                (0, utils_1.debugLog)(this.config?.debug || false, 'sol signAllTransactions(request) params', { method: 'signAllTransactions', shape: 'object{transactions:Uint8Array[]}', count: 1, txLen: txBytes.length });
+                                                            }
+                                                            catch { }
+                                                            r = await sol.request({ method: 'signAllTransactions', params: { transactions: [txBytes] } });
+                                                        }
+                                                        catch { }
+                                                    }
+                                                    // 0c) signAllTransactions with base64 strings
+                                                    if (!r) {
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signAllTransactions(request) params', { method: 'solana:signAllTransactions', shape: 'object{transactions:base64[]}', count: 1, txLen: __fallbackTxBase64.length });
+                                                        }
+                                                        catch { }
+                                                        try {
+                                                            r = await sol.request({ method: 'solana:signAllTransactions', params: { transactions: [__fallbackTxBase64] } });
+                                                        }
+                                                        catch { }
+                                                    }
+                                                    if (!r) {
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signAllTransactions(request) params', { method: 'signAllTransactions', shape: 'object{transactions:base64[]}', count: 1, txLen: __fallbackTxBase64.length });
+                                                        }
+                                                        catch { }
+                                                        try {
+                                                            r = await sol.request({ method: 'signAllTransactions', params: { transactions: [__fallbackTxBase64] } });
+                                                        }
+                                                        catch { }
+                                                    }
+                                                    if (r) {
+                                                        // Normalize array responses
+                                                        const arr = Array.isArray(r) ? r : (Array.isArray(r?.transactions) ? r.transactions : null);
+                                                        if (arr && arr.length > 0) {
+                                                            const first = arr[0];
+                                                            if (typeof first === 'string') {
+                                                                const looksBase64 = /^[A-Za-z0-9+/=]+$/.test(first) && first.length % 4 === 0;
+                                                                if (looksBase64)
+                                                                    signedTxB64 = first;
+                                                            }
+                                                            else if (first && (first.byteLength != null || ArrayBuffer.isView(first))) {
+                                                                const b = first instanceof Uint8Array ? first : new Uint8Array(first);
+                                                                // If it's a raw signature (64 bytes) treat as signature; otherwise treat as signed tx bytes
+                                                                if (b.length === 64)
+                                                                    signerSigBase58 = base58Encode(b);
+                                                                else
+                                                                    signedTxB64 = b64FromBytes(b);
+                                                            }
+                                                        }
+                                                    }
+                                                    if (signedTxB64 || signerSigBase58) {
+                                                        // short-circuit to relay below
+                                                    }
+                                                    // 1) Try message: base58 (string form first)
+                                                    if (inlineMsgB58Fallback) {
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'message:string(base58)', msgLen: inlineMsgB58Fallback.length });
+                                                        }
+                                                        catch { }
+                                                        try {
+                                                            r = await sol.request({ method: 'signTransaction', params: inlineMsgB58Fallback });
+                                                        }
+                                                        catch { }
+                                                        let candidate = (r?.signedTransaction || r?.transaction || r?.signedMessage || r);
+                                                        if (!signedTxB64 && !signerSigBase58) {
+                                                            if (typeof candidate === 'string') {
+                                                                const looksBase64 = /^[A-Za-z0-9+/=]+$/.test(candidate) && candidate.length % 4 === 0;
+                                                                if (looksBase64)
+                                                                    signedTxB64 = candidate;
+                                                                else
+                                                                    signerSigBase58 = candidate;
+                                                            }
+                                                            else if (candidate && (candidate.byteLength != null || ArrayBuffer.isView(candidate))) {
+                                                                const b = candidate instanceof Uint8Array ? candidate : new Uint8Array(candidate);
+                                                                if (b.length === 64)
+                                                                    signerSigBase58 = base58Encode(b);
+                                                            }
+                                                        }
+                                                        // 1b) Try message: base58 (array form)
+                                                        if (!signedTxB64 && !signerSigBase58) {
+                                                            try {
+                                                                (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'message:[string]', msgLen: inlineMsgB58Fallback.length });
+                                                            }
+                                                            catch { }
+                                                            try {
+                                                                r = await sol.request({ method: 'signTransaction', params: [inlineMsgB58Fallback] });
+                                                            }
+                                                            catch { }
+                                                            candidate = (r?.signedTransaction || r?.transaction || r?.signedMessage || r);
+                                                            if (typeof candidate === 'string') {
+                                                                const looksBase64 = /^[A-Za-z0-9+/=]+$/.test(candidate) && candidate.length % 4 === 0;
+                                                                if (looksBase64)
+                                                                    signedTxB64 = candidate;
+                                                                else
+                                                                    signerSigBase58 = candidate;
+                                                            }
+                                                            else if (candidate && (candidate.byteLength != null || ArrayBuffer.isView(candidate))) {
+                                                                const b = candidate instanceof Uint8Array ? candidate : new Uint8Array(candidate);
+                                                                if (b.length === 64)
+                                                                    signerSigBase58 = base58Encode(b);
+                                                            }
+                                                        }
+                                                        // 1c) Try message: base58 (object form)
+                                                        if (!signedTxB64 && !signerSigBase58) {
+                                                            try {
+                                                                (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'message:object{message}', msgLen: inlineMsgB58Fallback.length });
+                                                            }
+                                                            catch { }
+                                                            try {
+                                                                r = await sol.request({ method: 'signTransaction', params: { message: inlineMsgB58Fallback } });
+                                                            }
+                                                            catch { }
+                                                            candidate = (r?.signedTransaction || r?.transaction || r?.signedMessage || r);
+                                                            if (typeof candidate === 'string') {
+                                                                const looksBase64 = /^[A-Za-z0-9+/=]+$/.test(candidate) && candidate.length % 4 === 0;
+                                                                if (looksBase64)
+                                                                    signedTxB64 = candidate;
+                                                                else
+                                                                    signerSigBase58 = candidate;
+                                                            }
+                                                            else if (candidate && (candidate.byteLength != null || ArrayBuffer.isView(candidate))) {
+                                                                const b = candidate instanceof Uint8Array ? candidate : new Uint8Array(candidate);
+                                                                if (b.length === 64)
+                                                                    signerSigBase58 = base58Encode(b);
+                                                            }
+                                                        }
+                                                    }
+                                                    // 2) If still nothing, try transaction: base64
+                                                    if (!signedTxB64 && !signerSigBase58) {
+                                                        // Wallet Standard first
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'solana:signTransaction', paramShape: 'object{transaction:base64}', txLen: __fallbackTxBase64.length });
+                                                        }
+                                                        catch { }
+                                                        try {
+                                                            r = await sol.request({ method: 'solana:signTransaction', params: { transaction: __fallbackTxBase64 } });
+                                                        }
+                                                        catch { }
+                                                        let candidate = (r?.signedTransaction || r?.transaction || r?.signedMessage || r);
+                                                        if (typeof candidate === 'string') {
+                                                            const looksBase64 = /^[A-Za-z0-9+/=]+$/.test(candidate) && candidate.length % 4 === 0;
+                                                            if (looksBase64)
+                                                                signedTxB64 = candidate;
+                                                            else
+                                                                signerSigBase58 = candidate;
+                                                        }
+                                                        else if (candidate && (candidate.byteLength != null || ArrayBuffer.isView(candidate))) {
+                                                            const b = candidate instanceof Uint8Array ? candidate : new Uint8Array(candidate);
+                                                            if (b.length === 64)
+                                                                signerSigBase58 = base58Encode(b);
+                                                        }
+                                                    }
+                                                    if (!signedTxB64 && !signerSigBase58) {
+                                                        // Legacy string form
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'transaction:string(base64)', txLen: __fallbackTxBase64.length });
+                                                        }
+                                                        catch { }
+                                                        try {
+                                                            r = await sol.request({ method: 'signTransaction', params: __fallbackTxBase64 });
+                                                        }
+                                                        catch { }
+                                                        let candidate = (r?.signedTransaction || r?.transaction || r?.signedMessage || r);
+                                                        if (typeof candidate === 'string') {
+                                                            const looksBase64 = /^[A-Za-z0-9+/=]+$/.test(candidate) && candidate.length % 4 === 0;
+                                                            if (looksBase64)
+                                                                signedTxB64 = candidate;
+                                                            else
+                                                                signerSigBase58 = candidate;
+                                                        }
+                                                        else if (candidate && (candidate.byteLength != null || ArrayBuffer.isView(candidate))) {
+                                                            const b = candidate instanceof Uint8Array ? candidate : new Uint8Array(candidate);
+                                                            if (b.length === 64)
+                                                                signerSigBase58 = base58Encode(b);
+                                                        }
+                                                    }
+                                                    if (!signedTxB64 && !signerSigBase58) {
+                                                        // Legacy array form
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'transaction:[string]', txLen: __fallbackTxBase64.length });
+                                                        }
+                                                        catch { }
+                                                        try {
+                                                            r = await sol.request({ method: 'signTransaction', params: [__fallbackTxBase64] });
+                                                        }
+                                                        catch { }
+                                                        const candidate = (r?.signedTransaction || r?.transaction || r?.signedMessage || r);
+                                                        if (typeof candidate === 'string') {
+                                                            const looksBase64 = /^[A-Za-z0-9+/=]+$/.test(candidate) && candidate.length % 4 === 0;
+                                                            if (looksBase64)
+                                                                signedTxB64 = candidate;
+                                                            else
+                                                                signerSigBase58 = candidate;
+                                                        }
+                                                        else if (candidate && (candidate.byteLength != null || ArrayBuffer.isView(candidate))) {
+                                                            const b = candidate instanceof Uint8Array ? candidate : new Uint8Array(candidate);
+                                                            if (b.length === 64)
+                                                                signerSigBase58 = base58Encode(b);
+                                                        }
+                                                    }
+                                                    if (!signedTxB64 && !signerSigBase58) {
+                                                        // Legacy object form
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'transaction:object{transaction}', txLen: __fallbackTxBase64.length });
+                                                        }
+                                                        catch { }
+                                                        try {
+                                                            r = await sol.request({ method: 'signTransaction', params: { transaction: __fallbackTxBase64 } });
+                                                        }
+                                                        catch { }
+                                                        const candidate = (r?.signedTransaction || r?.transaction || r?.signedMessage || r);
+                                                        if (typeof candidate === 'string') {
+                                                            const looksBase64 = /^[A-Za-z0-9+/=]+$/.test(candidate) && candidate.length % 4 === 0;
+                                                            if (looksBase64)
+                                                                signedTxB64 = candidate;
+                                                            else
+                                                                signerSigBase58 = candidate;
+                                                        }
+                                                        else if (candidate && (candidate.byteLength != null || ArrayBuffer.isView(candidate))) {
+                                                            const b = candidate instanceof Uint8Array ? candidate : new Uint8Array(candidate);
+                                                            if (b.length === 64)
+                                                                signerSigBase58 = base58Encode(b);
+                                                        }
+                                                    }
+                                                }
+                                                catch { }
+                                            }
+                                            let settleResp;
+                                            if (signedTxB64 && typeof signedTxB64 === 'string') {
+                                                settleResp = await this.publicApiClient.post('/sdk/public/payments/x402/relay', {
+                                                    paymentIntentId,
+                                                    signedTransactionBase64: signedTxB64,
+                                                    rpcUrlPublic: requirement?.extra?.rpcUrlPublic || null,
+                                                });
+                                            }
+                                            else if (signerSigBase58) {
+                                                settleResp = await this.publicApiClient.post('/sdk/public/payments/x402/relay', {
+                                                    paymentIntentId,
+                                                    signatureBase58: signerSigBase58,
+                                                    transactionBase64: __fallbackTxBase64,
+                                                    payerPublicKey: fromBase58,
+                                                    rpcUrlPublic: requirement?.extra?.rpcUrlPublic || null,
+                                                });
+                                            }
+                                            else {
+                                                throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.TRANSACTION_FAILED, message: 'Wallet did not return a signed transaction' });
+                                            }
+                                            const statusSol = (settleResp?.status || settleResp?.paymentIntent?.status || 'completed').toString().toLowerCase();
+                                            const amountSol = (settleResp?.paymentIntent?.amount && String(settleResp.paymentIntent.amount)) ||
+                                                (typeof usdAmount === 'number' ? String(usdAmount) : request?.amount?.toString?.() || '0');
+                                            const outSol = {
+                                                transactionId: Number(settleResp?.canisterTxId || 0),
+                                                status: statusSol === 'succeeded' ? 'completed' : statusSol,
+                                                amount: amountSol,
+                                                recipientCanister: ledgerCanisterId,
+                                                timestamp: new Date(),
+                                                metadata: { ...(request.metadata || {}), icpay_x402: true },
+                                                payment: settleResp || null,
+                                            };
+                                            this.emitMethodSuccess('createPaymentX402Usd', outSol);
+                                            return outSol;
+                                        }
+                                    }
+                                    // Otherwise fall back to unsigned transaction flow if provided
+                                    const inlineTx = requirement?.extra?.transactionBase64;
+                                    const wSolCtx2 = globalThis?.window || globalThis;
+                                    // fromBase58 already determined
+                                    // Build signer-based transaction, user signs it, and server relays
+                                    let txBase64;
+                                    if (inlineTx) {
+                                        txBase64 = String(inlineTx);
+                                    }
+                                    else {
+                                        throw new errors_1.IcpayError({
+                                            code: errors_1.ICPAY_ERROR_CODES.API_ERROR,
+                                            message: 'X402 missing transactionBase64 in 402 response for Solana',
+                                            details: { note: 'API must include extra.transactionBase64 to avoid prepare' }
+                                        });
+                                    }
+                                    // Sign-only with wallet, then relay server-side (fee payer = relayer)
+                                    // Prefer request-based signTransaction with base58 "message" (serialized tx bytes)
+                                    let signedTxB64 = null;
+                                    let signerSigBase58 = null;
+                                    const inlineMsgB58 = requirement?.extra?.messageBase58;
+                                    const msgB58 = inlineMsgB58 || undefined;
+                                    try {
+                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol x402 payload sizes', {
+                                            txBase64Len: txBase64?.length || 0,
+                                            hasInlineMsgB58: !!inlineMsgB58,
+                                            msgB58Len: msgB58?.length || 0,
+                                        });
+                                    }
+                                    catch { }
+                                    // Do NOT submit from wallet; only sign, then relay to backend
+                                    // For wallets that require request-based signing
+                                    const preferTransactionSigning = true;
+                                    // Try to sign using transaction MESSAGE first (wallets often expect base58 message)
+                                    if (!signedTxB64 && sol?.request) {
+                                        try {
+                                            let r = null;
+                                            // Some wallets expect bare string or array for message
+                                            if (msgB58) {
+                                                // Ensure a visible connect prompt if required by the wallet
+                                                if (typeof sol?.connect === 'function') {
+                                                    try {
+                                                        await sol.connect({ onlyIfTrusted: false });
+                                                    }
+                                                    catch { }
+                                                }
+                                                // Prefer object form with Uint8Array message first
+                                                try {
+                                                    const msgBytesU8 = (() => { try {
+                                                        return base58Decode(msgB58);
+                                                    }
+                                                    catch {
+                                                        return new Uint8Array();
+                                                    } })();
+                                                    if (msgBytesU8.length > 0) {
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'object{message:Uint8Array}', msgLen: msgBytesU8.length });
+                                                        }
+                                                        catch { }
+                                                        r = await sol.request({ method: 'signTransaction', params: { message: msgBytesU8 } });
+                                                    }
+                                                }
+                                                catch { }
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'message:string(base58)', msgLen: msgB58.length });
+                                                }
+                                                catch { }
+                                                try {
+                                                    r = await sol.request({ method: 'signTransaction', params: msgB58 });
+                                                }
+                                                catch (eM1) {
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(message:string) failed', { error: String(eM1) });
+                                                    }
+                                                    catch { }
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'message:[string]', msgLen: msgB58.length });
+                                                    }
+                                                    catch { }
+                                                    try {
+                                                        r = await sol.request({ method: 'signTransaction', params: [msgB58] });
+                                                    }
+                                                    catch (eM2) {
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(message:array) failed', { error: String(eM2) });
+                                                        }
+                                                        catch { }
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'message:object', msgLen: msgB58.length });
+                                                        }
+                                                        catch { }
+                                                        r = await sol.request({ method: 'signTransaction', params: { message: msgB58 } });
+                                                    }
+                                                }
+                                            }
+                                            let candidate = (r?.signedTransaction || r?.transaction || r?.signedMessage || r);
+                                            try {
+                                                const rawKeys = r && typeof r === 'object' ? Object.keys(r || {}) : [];
+                                                (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) raw result', { hasResult: !!r, rawKeys });
+                                            }
+                                            catch { }
+                                            if (typeof candidate === 'string') {
+                                                const looksBase64 = /^[A-Za-z0-9+/=]+$/.test(candidate) && candidate.length % 4 === 0;
+                                                if (looksBase64)
+                                                    signedTxB64 = candidate;
+                                                else
+                                                    signerSigBase58 = candidate;
+                                            }
+                                            else if (candidate && (candidate.byteLength != null || ArrayBuffer.isView(candidate))) {
+                                                try {
+                                                    const b = candidate instanceof Uint8Array ? candidate : new Uint8Array(candidate);
+                                                    if (b.length === 64)
+                                                        signerSigBase58 = base58Encode(b);
+                                                }
+                                                catch { }
+                                            }
+                                            else if (candidate && typeof candidate === 'object' && Array.isArray(candidate.data)) {
+                                                try {
+                                                    const b = Uint8Array.from(candidate.data);
+                                                    if (b.length === 64)
+                                                        signerSigBase58 = base58Encode(b);
+                                                }
+                                                catch { }
+                                            }
+                                            else if (r && typeof r === 'object') {
+                                                const obj = r;
+                                                if (typeof obj.signature === 'string') {
+                                                    signerSigBase58 = obj.signature;
+                                                }
+                                                else if (Array.isArray(obj.signatures) && typeof obj.signatures[0] === 'string') {
+                                                    signerSigBase58 = obj.signatures[0];
+                                                }
+                                            }
+                                        }
+                                        catch { }
+                                    }
+                                    // If message-based did not yield, try transaction (prefer Uint8Array), then base64 (some wallets accept this)
+                                    if (!signedTxB64 && !signerSigBase58 && sol?.request) {
+                                        try {
+                                            let r = null;
+                                            // Prefer Uint8Array object form first to trigger wallet UI
+                                            try {
+                                                const txBytesU8 = u8FromBase64(txBase64);
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'object{transaction:Uint8Array}', txLen: txBytesU8.length });
+                                                }
+                                                catch { }
+                                                r = await sol.request({ method: 'signTransaction', params: { transaction: txBytesU8 } });
+                                            }
+                                            catch { }
+                                            if (!r) {
+                                                try {
+                                                    const txBytesU8b = u8FromBase64(txBase64);
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'solana:signTransaction', paramShape: 'object{transaction:Uint8Array}', txLen: txBytesU8b.length });
+                                                    }
+                                                    catch { }
+                                                    r = await sol.request({ method: 'solana:signTransaction', params: { transaction: txBytesU8b } });
+                                                }
+                                                catch { }
+                                            }
+                                            // Try string param, then array, then object
+                                            try {
+                                                (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'transaction:string(base64)', txLen: txBase64.length });
+                                            }
+                                            catch { }
+                                            try {
+                                                r = await sol.request({ method: 'signTransaction', params: txBase64 });
+                                            }
+                                            catch (eT1) {
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(transaction:string) failed', { error: String(eT1) });
+                                                }
+                                                catch { }
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'transaction:[string]', txLen: txBase64.length });
+                                                }
+                                                catch { }
+                                                try {
+                                                    r = await sol.request({ method: 'signTransaction', params: [txBase64] });
+                                                }
+                                                catch (eT2) {
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(transaction:array) failed', { error: String(eT2) });
+                                                    }
+                                                    catch { }
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol signTransaction(request) params', { method: 'signTransaction', paramShape: 'transaction:object', txLen: txBase64.length });
+                                                    }
+                                                    catch { }
+                                                    r = await sol.request({ method: 'signTransaction', params: { transaction: txBase64 } });
+                                                }
+                                            }
+                                            let candidate = (r?.signedTransaction || r?.transaction || r?.signedMessage || r);
+                                            if (typeof candidate === 'string') {
+                                                const looksBase64 = /^[A-Za-z0-9+/=]+$/.test(candidate) && candidate.length % 4 === 0;
+                                                if (looksBase64)
+                                                    signedTxB64 = candidate;
+                                                else
+                                                    signerSigBase58 = candidate;
+                                            }
+                                            else if (candidate && (candidate.byteLength != null || ArrayBuffer.isView(candidate))) {
+                                                try {
+                                                    const b = candidate instanceof Uint8Array ? candidate : new Uint8Array(candidate);
+                                                    if (b.length === 64)
+                                                        signerSigBase58 = base58Encode(b);
+                                                }
+                                                catch { }
+                                            }
+                                            else if (candidate && typeof candidate === 'object' && Array.isArray(candidate.data)) {
+                                                try {
+                                                    const b = Uint8Array.from(candidate.data);
+                                                    if (b.length === 64)
+                                                        signerSigBase58 = base58Encode(b);
+                                                }
+                                                catch { }
+                                            }
+                                        }
+                                        catch { }
+                                    }
+                                    // No hosted signer fallback; rely on wallet API only
+                                    // Prefer signMessage path only if explicitly allowed (disabled by default)
+                                    try {
+                                        const signableMsgB64 = requirement?.extra?.signableMessageBase64;
+                                        if (!preferTransactionSigning && !signedTxB64 && !signerSigBase58 && signableMsgB64) {
+                                            const message = u8FromBase64(signableMsgB64);
+                                            let sigResp = null;
+                                            let signErr = null;
+                                            try {
+                                                (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage attempts begin', { hasBuffer: !!globalThis.Buffer, msgLen: message.length });
+                                            }
+                                            catch { }
+                                            // A) Direct signMessage with Buffer first (some wallets require Buffer)
+                                            if (typeof sol?.signMessage === 'function') {
+                                                try {
+                                                    const Buf = globalThis.Buffer;
+                                                    if (Buf) {
+                                                        try {
+                                                            (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(Buffer)');
+                                                        }
+                                                        catch { }
+                                                        sigResp = await sol.signMessage(Buf.from(message));
+                                                    }
+                                                }
+                                                catch (eA) {
+                                                    signErr = eA;
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(Buffer) failed', { error: String(eA) });
+                                                    }
+                                                    catch { }
+                                                }
+                                            }
+                                            // B) Direct signMessage with Uint8Array
+                                            if (!sigResp && typeof sol?.signMessage === 'function') {
+                                                try {
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(Uint8Array)');
+                                                    }
+                                                    catch { }
+                                                    ;
+                                                    sigResp = await sol.signMessage(message);
+                                                }
+                                                catch (eB) {
+                                                    signErr = eB;
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage(Uint8Array) failed', { error: String(eB) });
+                                                    }
+                                                    catch { }
+                                                }
+                                            }
+                                            // C) Direct signer.signMessage if present
+                                            if (!sigResp && sol?.signer && typeof sol.signer.signMessage === 'function') {
+                                                try {
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol signer.signMessage(Uint8Array)');
+                                                    }
+                                                    catch { }
+                                                    ;
+                                                    sigResp = await sol.signer.signMessage(message);
+                                                }
+                                                catch (eC) {
+                                                    signErr = eC;
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol signer.signMessage failed', { error: String(eC) });
+                                                    }
+                                                    catch { }
+                                                }
+                                            }
+                                            // D) Wallet-standard request with array-of-bytes
+                                            if (!sigResp && sol?.request) {
+                                                try {
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol request signMessage(array-of-bytes)');
+                                                    }
+                                                    catch { }
+                                                    ;
+                                                    const arr = Array.from(message);
+                                                    sigResp = await sol.request({ method: 'signMessage', params: { message: arr, display: 'hex' } });
+                                                }
+                                                catch (eD) {
+                                                    signErr = eD;
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol request signMessage(array-of-bytes) failed', { error: String(eD) });
+                                                    }
+                                                    catch { }
+                                                }
+                                            }
+                                            // E) Wallet-standard request with base58 message
+                                            if (!sigResp && sol?.request) {
+                                                try {
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol request signMessage(base58)');
+                                                    }
+                                                    catch { }
+                                                    ;
+                                                    const msgB58ForReq = base58Encode(message);
+                                                    sigResp = await sol.request({ method: 'signMessage', params: { message: msgB58ForReq, display: 'hex' } });
+                                                }
+                                                catch (eE) {
+                                                    signErr = eE;
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'sol request signMessage(base58) failed', { error: String(eE) });
+                                                    }
+                                                    catch { }
+                                                }
+                                            }
+                                            let messageSigB64 = null;
+                                            if (sigResp) {
+                                                // Normalize common shapes: Uint8Array, Buffer-like, base58/base64 string, or { signature }
+                                                if (typeof sigResp === 'string') {
+                                                    // Could be base58 or base64; try base58 first
+                                                    try {
+                                                        const asBytes = base58Decode(sigResp);
+                                                        messageSigB64 = b64FromBytes(asBytes);
+                                                    }
+                                                    catch {
+                                                        // assume base64 already
+                                                        messageSigB64 = sigResp;
+                                                    }
+                                                }
+                                                else if (sigResp && (sigResp.byteLength != null || ArrayBuffer.isView(sigResp))) {
+                                                    try {
+                                                        const bytes = sigResp instanceof Uint8Array ? sigResp : new Uint8Array(sigResp);
+                                                        if (bytes && bytes.length === 64) {
+                                                            messageSigB64 = b64FromBytes(bytes);
+                                                        }
+                                                    }
+                                                    catch { }
+                                                }
+                                                else if (sigResp && typeof sigResp === 'object') {
+                                                    const obj = sigResp;
+                                                    if (typeof obj.signature === 'string') {
+                                                        try {
+                                                            const asBytes = base58Decode(obj.signature);
+                                                            messageSigB64 = b64FromBytes(asBytes);
+                                                        }
+                                                        catch {
+                                                            messageSigB64 = obj.signature;
+                                                        }
+                                                    }
+                                                    else if (Array.isArray(obj.data)) {
+                                                        try {
+                                                            const bytes = Uint8Array.from(obj.data);
+                                                            if (bytes && bytes.length === 64) {
+                                                                messageSigB64 = b64FromBytes(bytes);
+                                                            }
+                                                        }
+                                                        catch { }
+                                                    }
+                                                }
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage result normalized (message signature)', {
+                                                        hasSignature: !!messageSigB64,
+                                                        signatureLen: messageSigB64 ? messageSigB64.length : null,
+                                                    });
+                                                }
+                                                catch { }
+                                            }
+                                            else if (signErr) {
+                                                try {
+                                                    (0, utils_1.debugLog)(this.config?.debug || false, 'sol signMessage failed (all attempts)', { error: String(signErr) });
+                                                }
+                                                catch { }
+                                            }
+                                            // If we obtained a message signature, construct x402 header and settle via API
+                                            if (messageSigB64) {
+                                                const fields = (requirement?.extra?.signableFields || {});
+                                                const header = (0, builders_1.buildX402HeaderFromAuthorization)({
+                                                    x402Version: Number(requirement?.x402Version || (data?.x402Version || 2)),
+                                                    scheme: String(requirement?.scheme || 'exact'),
+                                                    network: String(requirement?.network || ''),
+                                                    from: String(fromBase58 || ''),
+                                                    to: String(requirement?.payTo || ''),
+                                                    value: String(requirement?.maxAmountRequired || '0'),
+                                                    validAfter: String(fields?.validAfter || '0'),
+                                                    validBefore: String(fields?.validBefore || '0'),
+                                                    nonce: String(fields?.nonceHex || ''),
+                                                    signature: String(messageSigB64),
+                                                });
+                                                const headerJson = JSON.stringify(header);
+                                                let headerB64;
+                                                try {
+                                                    const Buf = globalThis.Buffer;
+                                                    headerB64 = Buf ? Buf.from(headerJson, 'utf8').toString('base64') : globalThis?.btoa?.(headerJson) || '';
+                                                }
+                                                catch {
+                                                    headerB64 = '';
+                                                }
+                                                if (headerB64) {
+                                                    try {
+                                                        this.emitMethodStart('notifyLedgerTransaction', { paymentIntentId });
+                                                    }
+                                                    catch { }
+                                                    const settleRespSol = await this.publicApiClient.post('/sdk/public/payments/x402/settle', {
+                                                        paymentIntentId,
+                                                        paymentHeader: headerB64,
+                                                        paymentRequirements: requirement,
+                                                    });
+                                                    try {
+                                                        (0, utils_1.debugLog)(this.config?.debug || false, 'x402 (sol) settle via header response', {
+                                                            ok: settleRespSol?.ok,
+                                                            status: settleRespSol?.status,
+                                                            paymentIntentId: settleRespSol?.paymentIntent?.id,
+                                                            paymentId: settleRespSol?.payment?.id,
+                                                            rawKeys: Object.keys(settleRespSol || {}),
+                                                        });
+                                                    }
+                                                    catch { }
+                                                    const statusSolHdr = (settleRespSol?.status || settleRespSol?.paymentIntent?.status || 'completed').toString().toLowerCase();
+                                                    const amountSolHdr = (settleRespSol?.paymentIntent?.amount && String(settleRespSol.paymentIntent.amount)) ||
+                                                        (typeof usdAmount === 'number' ? String(usdAmount) : request?.amount?.toString?.() || '0');
+                                                    const outSolHdr = {
+                                                        transactionId: Number(settleRespSol?.canisterTxId || 0),
+                                                        status: statusSolHdr === 'succeeded' ? 'completed' : statusSolHdr,
+                                                        amount: amountSolHdr,
+                                                        recipientCanister: ledgerCanisterId,
+                                                        timestamp: new Date(),
+                                                        metadata: { ...(request.metadata || {}), icpay_x402: true },
+                                                        payment: settleRespSol || null,
+                                                    };
+                                                    const isTerminalSolHdr = (() => {
+                                                        const s = String(outSolHdr.status || '').toLowerCase();
+                                                        return s === 'completed' || s === 'succeeded' || s === 'failed' || s === 'canceled' || s === 'cancelled' || s === 'mismatched';
+                                                    })();
+                                                    if (isTerminalSolHdr) {
+                                                        if (outSolHdr.status === 'completed') {
+                                                            this.emit('icpay-sdk-transaction-completed', outSolHdr);
+                                                        }
+                                                        else if (outSolHdr.status === 'failed') {
+                                                            this.emit('icpay-sdk-transaction-failed', outSolHdr);
+                                                        }
+                                                        else {
+                                                            this.emit('icpay-sdk-transaction-updated', outSolHdr);
+                                                        }
+                                                        this.emitMethodSuccess('createPaymentX402Usd', outSolHdr);
+                                                        return outSolHdr;
+                                                    }
+                                                    // Non-terminal: wait until terminal via notify loop
+                                                    try {
+                                                        this.emit('icpay-sdk-transaction-updated', outSolHdr);
+                                                    }
+                                                    catch { }
+                                                    const waitedSolHdr = await this.awaitIntentTerminal({
+                                                        paymentIntentId,
+                                                        ledgerCanisterId: ledgerCanisterId,
+                                                        amount: amountSolHdr,
+                                                        metadata: { ...(request.metadata || {}), icpay_x402: true },
+                                                    });
+                                                    this.emitMethodSuccess('createPaymentX402Usd', waitedSolHdr);
+                                                    return waitedSolHdr;
+                                                }
+                                            }
+                                        }
+                                    }
+                                    catch { }
+                                    if (!signedTxB64 && !signerSigBase58) {
+                                        throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.TRANSACTION_FAILED, message: 'Wallet did not return a signed transaction' });
+                                    }
+                                    let settleResp;
+                                    if (signedTxB64 && typeof signedTxB64 === 'string') {
+                                        settleResp = await this.publicApiClient.post('/sdk/public/payments/x402/relay', {
+                                            paymentIntentId,
+                                            signedTransactionBase64: signedTxB64,
+                                            rpcUrlPublic: requirement?.extra?.rpcUrlPublic || null,
+                                        });
+                                    }
+                                    else if (signerSigBase58) {
+                                        // Relay signature + unsigned tx; server will attach and co-sign
+                                        settleResp = await this.publicApiClient.post('/sdk/public/payments/x402/relay', {
+                                            paymentIntentId,
+                                            signatureBase58: signerSigBase58,
+                                            transactionBase64: txBase64,
+                                            payerPublicKey: fromBase58,
+                                            rpcUrlPublic: requirement?.extra?.rpcUrlPublic || null,
+                                        });
+                                    }
+                                    else {
+                                        throw new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.TRANSACTION_FAILED, message: 'Wallet did not return a signed transaction' });
+                                    }
+                                    try {
+                                        (0, utils_1.debugLog)(this.config?.debug || false, 'x402 (sol) settle response (relay via services)', {
+                                            ok: settleResp?.ok,
+                                            status: settleResp?.status,
+                                            paymentIntentId: settleResp?.paymentIntent?.id,
+                                            paymentId: settleResp?.payment?.id,
+                                            rawKeys: Object.keys(settleResp || {}),
+                                        });
+                                    }
+                                    catch { }
+                                    // Move to "Payment confirmation" stage (after relayer submission)
+                                    try {
+                                        this.emitMethodSuccess('notifyLedgerTransaction', { paymentIntentId });
+                                    }
+                                    catch { }
+                                    const statusSol = (settleResp?.status || settleResp?.paymentIntent?.status || 'completed').toString().toLowerCase();
+                                    const amountSol = (settleResp?.paymentIntent?.amount && String(settleResp.paymentIntent.amount)) ||
+                                        (typeof usdAmount === 'number' ? String(usdAmount) : request?.amount?.toString?.() || '0');
+                                    const outSol = {
+                                        transactionId: Number(settleResp?.canisterTxId || 0),
+                                        status: statusSol === 'succeeded' ? 'completed' : statusSol,
+                                        amount: amountSol,
+                                        recipientCanister: ledgerCanisterId,
+                                        timestamp: new Date(),
+                                        metadata: { ...(request.metadata || {}), icpay_x402: true },
+                                        payment: settleResp || null,
+                                    };
+                                    // Do not fallback to normal flow for Solana x402; surface failure
+                                    const isTerminalSol = (() => {
+                                        const s = String(outSol.status || '').toLowerCase();
+                                        return s === 'completed' || s === 'succeeded' || s === 'failed' || s === 'canceled' || s === 'cancelled' || s === 'mismatched';
+                                    })();
+                                    if (isTerminalSol) {
+                                        if (outSol.status === 'completed') {
+                                            this.emit('icpay-sdk-transaction-completed', outSol);
+                                        }
+                                        else if (outSol.status === 'failed') {
+                                            this.emit('icpay-sdk-transaction-failed', outSol);
+                                        }
+                                        else {
+                                            this.emit('icpay-sdk-transaction-updated', outSol);
+                                        }
+                                        this.emitMethodSuccess('createPaymentX402Usd', outSol);
+                                        return outSol;
+                                    }
+                                    // Non-terminal: wait until terminal via notify loop
+                                    try {
+                                        this.emit('icpay-sdk-transaction-updated', outSol);
+                                    }
+                                    catch { }
+                                    const waitedSol = await this.awaitIntentTerminal({
+                                        paymentIntentId,
+                                        ledgerCanisterId: ledgerCanisterId,
+                                        amount: amountSol,
+                                        metadata: { ...(request.metadata || {}), icpay_x402: true },
+                                    });
+                                    this.emitMethodSuccess('createPaymentX402Usd', waitedSol);
+                                    return waitedSol;
+                                }
+                                // EVM: server-side settlement
                                 try {
                                     this.emitMethodStart('notifyLedgerTransaction', { paymentIntentId });
                                 }
@@ -1744,7 +3422,6 @@ class Icpay {
                                         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;
@@ -1780,8 +3457,12 @@ class Icpay {
                                 this.emitMethodSuccess('createPaymentX402Usd', waited);
                                 return waited;
                             }
-                            catch {
-                                // Fall through to notify-based wait if settle endpoint not available
+                            catch (err) {
+                                // For Solana x402, do not silently fall back; surface the error so user can retry/sign
+                                if (isSol) {
+                                    throw (err instanceof errors_1.IcpayError) ? err : new errors_1.IcpayError({ code: errors_1.ICPAY_ERROR_CODES.TRANSACTION_FAILED, message: 'X402 Solana flow failed before signing', details: err });
+                                }
+                                // Non-Solana: fall through to notify-based wait if settle endpoint not available
                             }
                         }
                         // Fallback: wait until terminal via notify loop