payment-kit 1.24.3 → 1.25.0

package/api/src/libs/slippage.ts

@@ -0,0 +1,135 @@
+import { BN, fromTokenToUnit, fromUnitToToken } from '@ocap/util';
+
+import { trimDecimals } from './math-utils';
+
+export const SLIPPAGE_BPS_BASE = new BN(10000);
+export const DEFAULT_SLIPPAGE_PERCENT = 0.5;
+
+export type SlippageConfig = {
+  mode: 'percent' | 'rate';
+  percent: number;
+  min_acceptable_rate?: string;
+  base_currency?: string;
+  updated_at_ms?: number;
+};
+
+type SlippageSource = {
+  slippage_percent?: number | string | null;
+  metadata?: any;
+};
+
+export function normalizeSlippagePercent(value: unknown, fallback = DEFAULT_SLIPPAGE_PERCENT): number {
+  const normalized = typeof value === 'string' ? Number(value) : Number(value);
+  if (!Number.isFinite(normalized) || normalized < 0) {
+    return fallback;
+  }
+  return normalized;
+}
+
+export function normalizeSlippageConfigFromMetadata(
+  metadata: any,
+  fallbackPercent: number = DEFAULT_SLIPPAGE_PERCENT
+): SlippageConfig | null {
+  const fromMeta = metadata?.slippage;
+  if (!fromMeta || typeof fromMeta !== 'object') {
+    return null;
+  }
+  const mode = fromMeta.mode === 'rate' ? 'rate' : 'percent';
+  const percent = normalizeSlippagePercent(fromMeta.percent, fallbackPercent);
+  return {
+    mode,
+    percent,
+    min_acceptable_rate: fromMeta.min_acceptable_rate,
+    base_currency: fromMeta.base_currency,
+    updated_at_ms: fromMeta.updated_at_ms,
+  };
+}
+
+export function resolveSlippagePercent(
+  quote: SlippageSource,
+  checkoutSession?: SlippageSource,
+  fallbackPercent: number = DEFAULT_SLIPPAGE_PERCENT
+): number {
+  const fromQuote = quote.slippage_percent ?? quote.metadata?.slippage?.percent;
+  const fromSessionMeta = normalizeSlippageConfigFromMetadata(checkoutSession?.metadata, fallbackPercent)?.percent;
+  const fromSession = checkoutSession?.slippage_percent;
+  const value = fromQuote ?? fromSessionMeta ?? fromSession ?? fallbackPercent;
+  return normalizeSlippagePercent(value, fallbackPercent);
+}
+
+export function buildSlippageSnapshot(params: {
+  quote: SlippageSource & { quoted_amount?: string | null; exchange_rate?: string | null };
+  checkoutSession?: SlippageSource;
+  nowMs?: number;
+}): { percent: number; max_payable_token: string; min_acceptable_rate: string; derived_at_ms: number } | null {
+  const { quote, checkoutSession, nowMs = Date.now() } = params;
+  if (!quote.quoted_amount || !quote.exchange_rate) {
+    return null;
+  }
+
+  // Check if user is using rate mode with a specific min_acceptable_rate
+  // In this case, preserve user's precise rate value instead of recalculating from percent
+  const sessionSlippage = checkoutSession?.metadata?.slippage;
+  const userSetMinRate = sessionSlippage?.mode === 'rate' && sessionSlippage?.min_acceptable_rate;
+
+  const slippagePercent = resolveSlippagePercent(quote, checkoutSession);
+  const slippageBps = Math.round(slippagePercent * 100);
+  const multiplier = SLIPPAGE_BPS_BASE.add(new BN(slippageBps));
+  const quotedAmountUnit = new BN(quote.quoted_amount);
+  const maxPayableToken = quotedAmountUnit
+    .mul(multiplier)
+    .add(SLIPPAGE_BPS_BASE.sub(new BN(1)))
+    .div(SLIPPAGE_BPS_BASE);
+
+  let minAcceptableRate: string;
+  if (userSetMinRate) {
+    // Rate mode: preserve user's precise min_acceptable_rate value
+    minAcceptableRate = sessionSlippage.min_acceptable_rate;
+  } else {
+    // Percent mode: calculate min_acceptable_rate from percent
+    const USD_DECIMALS = 8;
+    const rateBN = fromTokenToUnit(trimDecimals(quote.exchange_rate, USD_DECIMALS), USD_DECIMALS);
+    const minRateBN = rateBN.mul(SLIPPAGE_BPS_BASE).div(multiplier);
+    minAcceptableRate = fromUnitToToken(minRateBN.toString(), USD_DECIMALS);
+  }
+
+  return {
+    percent: slippagePercent,
+    max_payable_token: maxPayableToken.toString(),
+    min_acceptable_rate: minAcceptableRate,
+    derived_at_ms: nowMs,
+  };
+}
+
+export function isRateBelowMinAcceptableRate(
+  currentRate?: string | number | null,
+  minAcceptableRate?: string | number | null
+): boolean {
+  const current = Number(currentRate);
+  const min = Number(minAcceptableRate);
+  if (!Number.isFinite(current) || !Number.isFinite(min)) {
+    return false;
+  }
+  return current < min;
+}
+
+/**
+ * Apply slippage to an amount to get the maximum payable amount
+ * This is used for delegation authorization to ensure sufficient buffer
+ *
+ * @param amount - Base amount in smallest unit (e.g., wei)
+ * @param slippagePercent - Slippage percentage (e.g., 15 for 15%)
+ * @returns Maximum amount with slippage applied (rounded up)
+ */
+export function applySlippageToAmount(amount: BN, slippagePercent: number): BN {
+  if (!slippagePercent || slippagePercent <= 0) {
+    return amount;
+  }
+  const slippageBps = Math.round(slippagePercent * 100);
+  const multiplier = SLIPPAGE_BPS_BASE.add(new BN(slippageBps));
+  // Round up: (amount * multiplier + BASE - 1) / BASE
+  return amount
+    .mul(multiplier)
+    .add(SLIPPAGE_BPS_BASE.sub(new BN(1)))
+    .div(SLIPPAGE_BPS_BASE);
+}

package/api/src/libs/subscription.ts

@@ -1,6 +1,6 @@
 /* eslint-disable no-await-in-loop */
 import component from '@blocklet/sdk/lib/component';
-import { BN, fromUnitToToken } from '@ocap/util';
+import { BN, fromTokenToUnit, fromUnitToToken } from '@ocap/util';
 import isEmpty from 'lodash/isEmpty';
 import trim from 'lodash/trim';
 import pick from 'lodash/pick';
@@ -9,6 +9,7 @@ import { withQuery } from 'ufo';
 
 import { Op } from 'sequelize';
 import {
+  ChainType,
   Customer,
   Invoice,
   InvoiceItem,
@@ -30,13 +31,17 @@ import { createEvent } from './audit';
 import dayjs from './dayjs';
 import env from './env';
 import logger from './logger';
+import { getExchangeRateService } from './exchange-rate';
+import { getExchangeRateSymbol } from './exchange-rate/token-address-mapping';
+import { trimDecimals, limitTokenPrecision } from './math-utils';
 import { getPriceCurrencyOptions, getPriceUintAmountByCurrency } from './price';
-import { getRecurringPeriod, getSubscriptionCreateSetup } from './session';
+import { getRecurringPeriod, getSubscriptionCreateSetup, SlippageOptions } from './session';
 import { getConnectQueryParam, getCustomerStakeAddress } from './util';
 import { wallet } from './auth';
 import { getGasPayerExtra } from './payment';
 import { getLock } from './lock';
 import { emitAsync } from './event';
+import { getSubscriptionItemPrice } from './credit-utils';
 
 export function getCustomerSubscriptionPageUrl({
   subscriptionId,
@@ -263,9 +268,16 @@ export function getSubscriptionCycleAmount(items: TLineItemExpanded[], currencyI
   let amount = new BN(0);
 
   items.forEach((x) => {
-    amount = amount.add(
-      new BN(getPriceUintAmountByCurrency(getSubscriptionItemPrice(x) as any, currencyId)).mul(new BN(x.quantity))
-    );
+    const price = getSubscriptionItemPrice(x) as any;
+    const dynamicAmount =
+      price?.pricing_type === 'dynamic' ? (x as any).custom_amount || (x as any).quoted_amount : null;
+
+    if (dynamicAmount) {
+      amount = amount.add(new BN(dynamicAmount));
+      return;
+    }
+
+    amount = amount.add(new BN(getPriceUintAmountByCurrency(price, currencyId)).mul(new BN(x.quantity)));
   });
 
   return {
@@ -273,9 +285,8 @@ export function getSubscriptionCycleAmount(items: TLineItemExpanded[], currencyI
   };
 }
 
-export function getSubscriptionItemPrice(item: TLineItemExpanded) {
-  return item.upsell_price || item.price;
-}
+// Re-exported from credit-utils.ts to maintain backward compatibility
+export { getSubscriptionItemPrice } from './credit-utils';
 
 export async function createProration(
   subscription: Subscription,
@@ -330,17 +341,29 @@ export async function createProration(
   const prorations = await Promise.all(
     prorationItems.map((x: TLineItemExpanded & { [key: string]: any }) => {
       const price = getSubscriptionItemPrice(x);
-      const unitAmount = getPriceUintAmountByCurrency(price, lastInvoice.currency_id);
-      const amount = new BN(unitAmount)
-        .mul(new BN(x.quantity))
-        .mul(new BN(prorationRate))
-        .div(new BN(precision))
-        .toString();
+      // For dynamic pricing, use the actual paid amount from invoice item
+      // For fixed pricing, use the standard unit_amount calculation
+      let baseAmount: string;
+      if (price.pricing_type === 'dynamic') {
+        // Use invoice item's actual amount (from Quote)
+        baseAmount = x.amount || '0';
+        logger.info('Using dynamic pricing amount for proration', {
+          subscriptionId: subscription.id,
+          priceId: price.id,
+          actualAmount: baseAmount,
+        });
+      } else {
+        const unitAmount = getPriceUintAmountByCurrency(price, lastInvoice.currency_id);
+        baseAmount = new BN(unitAmount).mul(new BN(x.quantity)).toString();
+      }
+
+      const amount = new BN(baseAmount).mul(new BN(prorationRate)).div(new BN(precision)).toString();
       logger.info('subscription proration item', {
         subscription: subscription.id,
         invoice: x.invoice_id,
         invoiceItem: x.id,
         amount,
+        isDynamic: price.pricing_type === 'dynamic',
       });
       unused = unused.add(new BN(amount));
 
@@ -362,6 +385,10 @@ export async function createProration(
             invoice_line_items: [x.id],
           },
         },
+        // Additional info for frontend to recalculate with current exchange rate
+        pricing_type: price.pricing_type,
+        base_amount_usd: price.pricing_type === 'dynamic' ? price.base_amount : null,
+        proration_rate: prorationRate / precision, // e.g., 0.85 means 85% unused time
       };
     })
   );
@@ -437,7 +464,17 @@ export async function createProration(
 export async function getSubscriptionRefundSetup(subscription: Subscription, anchor: number, currencyId?: string) {
   const items = await SubscriptionItem.findAll({ where: { subscription_id: subscription.id } });
   const expanded = await Price.expand(items.map((x) => x.toJSON()));
-  const setup = getSubscriptionCreateSetup(expanded, currencyId || subscription.currency_id, 0);
+  const targetCurrencyId = currencyId || subscription.currency_id;
+
+  // Build slippage options with min_acceptable_rate for precise authorization calculation
+  const slippageConfig = subscription.slippage_config;
+  const currency = await PaymentCurrency.findByPk(targetCurrencyId);
+  const slippageOptions: SlippageOptions = {
+    percent: slippageConfig?.percent ?? 0.5,
+    minAcceptableRate: slippageConfig?.min_acceptable_rate,
+    currencyDecimal: currency?.decimal,
+  };
+  const setup = getSubscriptionCreateSetup(expanded, targetCurrencyId, 0, 0, slippageOptions);
   return createProration(subscription, setup, anchor);
 }
 
@@ -488,8 +525,13 @@ export async function getUpcomingInvoiceAmount(subscriptionId: string) {
 
   let amount = new BN(0);
   let minExpectedAmount = new BN(0);
+  let hasDynamicPricing = false;
+
   for (const item of expanded) {
     const price = getSubscriptionItemPrice(item);
+    if (price.pricing_type === 'dynamic') {
+      hasDynamicPricing = true;
+    }
     if (price.type === 'recurring') {
       const unit = getPriceUintAmountByCurrency(price, subscription.currency_id);
       if (price.recurring?.usage_type === 'licensed') {
@@ -513,12 +555,43 @@ export async function getUpcomingInvoiceAmount(subscriptionId: string) {
     }
   }
 
+  // Get exchange rate info for dynamic pricing subscriptions
+  let quoteInfo: {
+    exchange_rate: string;
+    rate_timestamp_ms: number;
+    providers: Array<{ provider_name: string; rate?: string }>;
+  } | null = null;
+
+  if (hasDynamicPricing && currency) {
+    try {
+      const paymentMethod = await PaymentMethod.findByPk(currency.payment_method_id);
+      const exchangeRateService = getExchangeRateService();
+      const rateSymbol = getExchangeRateSymbol(currency.symbol, paymentMethod?.type as ChainType);
+      if (rateSymbol) {
+        const rateResult = await exchangeRateService.getRate(rateSymbol);
+        if (rateResult?.rate) {
+          quoteInfo = {
+            exchange_rate: rateResult.rate,
+            rate_timestamp_ms: rateResult.timestamp_ms || Date.now(),
+            providers: rateResult.providers || [],
+          };
+        }
+      }
+    } catch (err) {
+      logger.warn('Failed to fetch exchange rate for upcoming invoice', {
+        subscriptionId,
+        error: err,
+      });
+    }
+  }
+
   return {
     amount: amount.toString(),
     minExpectedAmount: minExpectedAmount.toString(),
     start: subscription.current_period_start,
     end: subscription.current_period_end,
     currency,
+    quoteInfo,
   };
 }
 
@@ -1153,6 +1226,103 @@ export async function getPaymentAmountForCycleSubscription(
   return 0;
 }
 
+export async function getEstimatedPaymentAmountForCycleSubscription(
+  subscription: Subscription,
+  paymentCurrency: PaymentCurrency
+): Promise<{ amount: number; estimatedByRate: boolean }> {
+  const subscriptionItems = await SubscriptionItem.findAll({ where: { subscription_id: subscription.id } });
+  if (subscriptionItems.length === 0) {
+    logger.info('subscription items not found in getEstimatedPaymentAmountForCycleSubscription', {
+      subscription: subscription.id,
+    });
+    return { amount: 0, estimatedByRate: false };
+  }
+  let expandedItems = await Price.expand(
+    subscriptionItems.map((x) => ({ id: x.id, price_id: x.price_id, quantity: x.quantity })),
+    { product: true }
+  );
+  if (expandedItems.length === 0) {
+    logger.info('expanded items not found in getEstimatedPaymentAmountForCycleSubscription', {
+      subscription: subscription.id,
+    });
+    return { amount: 0, estimatedByRate: false };
+  }
+  const previousPeriodEnd =
+    subscription.status === 'trialing' ? subscription.trial_end : subscription.current_period_end;
+  const setup = getSubscriptionCycleSetup(subscription.pending_invoice_item_interval, previousPeriodEnd as number);
+  expandedItems = await Promise.all(
+    expandedItems.map(async (x: any) => {
+      if (x.price.recurring?.usage_type === 'metered') {
+        const rawQuantity = await UsageRecord.getSummary({
+          id: x.id,
+          start: setup.period.start - setup.cycle / 1000,
+          end: setup.period.end - setup.cycle / 1000,
+          method: x.price.recurring?.aggregate_usage,
+          dryRun: true,
+        });
+        x.quantity = x.price.transformQuantity(rawQuantity);
+        x.metadata = x.metadata || {};
+        x.metadata.quantity = rawQuantity;
+      }
+      return x;
+    })
+  );
+  if (expandedItems.length === 0) {
+    return { amount: 0, estimatedByRate: false };
+  }
+
+  let estimatedByRate = false;
+  const hasDynamicItems = expandedItems.some((item: any) => item.price?.pricing_type === 'dynamic');
+  if (hasDynamicItems) {
+    try {
+      const paymentMethod = await PaymentMethod.findByPk(paymentCurrency.payment_method_id);
+      if (!paymentMethod) {
+        throw new Error(`PaymentMethod not found in ${subscription.id}`);
+      }
+      const exchangeRateService = getExchangeRateService();
+      const rateSymbol = getExchangeRateSymbol(paymentCurrency.symbol, paymentMethod.type as any);
+      const rateResult = await exchangeRateService.getRate(rateSymbol);
+      const USD_DECIMALS = 8;
+      const rateBN = fromTokenToUnit(trimDecimals(rateResult.rate, USD_DECIMALS), USD_DECIMALS);
+
+      expandedItems = expandedItems.map((item: any) => {
+        const { price } = item;
+        if (price?.pricing_type !== 'dynamic') {
+          return item;
+        }
+        if (!price.base_amount) {
+          logger.warn('Dynamic price missing base_amount for estimate', {
+            subscriptionId: subscription.id,
+            priceId: price.id,
+          });
+          return item;
+        }
+
+        const baseAmountBN = fromTokenToUnit(trimDecimals(price.base_amount, USD_DECIMALS), USD_DECIMALS);
+        const quantityBN = new BN(item.quantity || 0);
+        const totalBaseAmountBN = baseAmountBN.mul(quantityBN);
+        const numerator = totalBaseAmountBN.mul(new BN(10).pow(new BN(paymentCurrency.decimal)));
+        const quotedAmountRaw = numerator.add(rateBN).sub(new BN(1)).div(rateBN);
+        const quotedAmount = limitTokenPrecision(quotedAmountRaw, paymentCurrency.decimal, 10);
+        estimatedByRate = true;
+        return {
+          ...item,
+          custom_amount: quotedAmount.toString(),
+          quoted_amount: quotedAmount.toString(),
+        };
+      });
+    } catch (error: any) {
+      logger.warn('Failed to estimate dynamic pricing amount for subscription', {
+        subscriptionId: subscription.id,
+        error: error?.message || error,
+      });
+    }
+  }
+
+  const amount = getSubscriptionCycleAmount(expandedItems, paymentCurrency.id);
+  return { amount: +fromUnitToToken(amount?.total || '0', paymentCurrency.decimal), estimatedByRate };
+}
+
 // check if subscription overdraft protection is enabled
 export async function isSubscriptionOverdraftProtectionEnabled(subscription: Subscription, paymentCurrencyId?: string) {
   try {

package/api/src/libs/util.ts

@@ -521,6 +521,26 @@ export function getCustomerIndexUrl({ locale, userDid }: { locale: string; userD
   return getUrl(withQuery('customer', { locale, ...getConnectQueryParam({ userDid }) }));
 }
 
+export function getCustomerAutoRechargeSettingsUrl({
+  locale,
+  userDid,
+  currencyId,
+}: {
+  locale: string;
+  userDid: string;
+  currencyId?: string;
+}) {
+  const query: Record<string, string> = {
+    locale,
+    action: 'auto-recharge',
+    ...getConnectQueryParam({ userDid }),
+  };
+  if (currencyId) {
+    query.currencyId = currencyId;
+  }
+  return getUrl(withQuery('customer', query));
+}
+
 // Check if user is in blocklist
 export async function isUserInBlocklist(did: string, paymentMethod: PaymentMethod): Promise<boolean> {
   try {
@@ -584,20 +604,61 @@ export function formatCurrencyInfo(
   paymentMethod?: PaymentMethod | null,
   isToken?: boolean
 ) {
-  let amountStr = '';
   const defaultPaymentCurrency = {
     symbol: '',
     decimal: 18,
   };
 
+  const decimal = paymentCurrency.decimal ?? defaultPaymentCurrency.decimal;
+  const symbol = paymentCurrency.symbol ?? defaultPaymentCurrency.symbol;
+
+  let formattedAmount: string;
   if (isToken) {
-    amountStr = `${amount || '0'} ${paymentCurrency.symbol ?? defaultPaymentCurrency.symbol}`;
+    // Already in token format, apply precision formatting
+    const numericValue = Number(amount || '0');
+    if (!Number.isFinite(numericValue)) {
+      formattedAmount = String(amount || '0');
+    } else {
+      const abs = Math.abs(numericValue);
+      // If amount > 0.01, show 2 decimal places; otherwise show full precision
+      const targetPrecision = abs > 0 && abs < 0.01 ? decimal : 2;
+      formattedAmount = formatNumber(numericValue, targetPrecision, true, false) || '0';
+    }
   } else {
-    amountStr = `${fromUnitToToken(amount || '0', paymentCurrency.decimal ?? defaultPaymentCurrency.decimal)} ${paymentCurrency.symbol ?? defaultPaymentCurrency.symbol}`;
+    // Convert from unit to token format, then apply precision formatting
+    const tokenAmount = fromUnitToToken(amount || '0', decimal);
+    const numericValue = Number(tokenAmount);
+    if (!Number.isFinite(numericValue)) {
+      formattedAmount = tokenAmount;
+    } else {
+      const abs = Math.abs(numericValue);
+      // If amount > 0.01, show 2 decimal places; otherwise show full precision
+      const targetPrecision = abs > 0 && abs < 0.01 ? decimal : 2;
+      formattedAmount = formatNumber(numericValue, targetPrecision, true, false) || '0';
+    }
   }
+
+  const amountStr = `${formattedAmount} ${symbol}`;
   return paymentMethod && paymentMethod.type !== 'arcblock' ? `${amountStr} (${paymentMethod.name})` : amountStr;
 }
 
+/**
+ * Format amount from unit to token with consistent precision
+ * - If amount > 0.01, show 2 decimal places
+ * - If 0 < amount <= 0.01, show full precision
+ * - Returns formatted string without symbol
+ */
+export function formatTokenAmount(amount: string | number, decimal: number): string {
+  const tokenAmount = fromUnitToToken(amount || '0', decimal);
+  const numericValue = Number(tokenAmount);
+  if (!Number.isFinite(numericValue)) {
+    return tokenAmount;
+  }
+  const abs = Math.abs(numericValue);
+  const targetPrecision = abs > 0 && abs < 0.01 ? decimal : 2;
+  return formatNumber(numericValue, targetPrecision, true, false) || '0';
+}
+
 export function getExplorerTxUrl({
   explorerHost,
   txHash,

package/api/src/locales/en.ts

@@ -159,6 +159,8 @@ export default flat({
         'The estimated payment amount is {price}, but your current balance is insufficient ({balance}). Please ensure your account has enough balance to avoid payment failure.',
       renewAmount: 'Payment amount',
       estimatedAmountNote: 'Estimate {amount}, billed based on final usage',
+      estimatedAmountNoteRate: 'Estimate {amount}, based on the exchange rate at billing time',
+      estimatedAmountNoteRateAndUsage: 'Estimate {amount}, based on final usage and the exchange rate at billing time',
     },
 
     subscriptionRenewed: {
@@ -204,7 +206,21 @@ export default flat({
         noEnoughToken: 'Your account token balance is {balance}, which is insufficient for {price}. Please add funds',
         noSupported: 'Automatic payment with tokens is not supported. Please check your package',
         txSendFailed: 'Failed to send automatic payment transaction',
+        // Skipped reasons (dynamic pricing)
+        slippageExceeded:
+          'Current {paymentCurrency} rate is {currentRate}, below your limit of {minAcceptableRate}. System will auto-retry when rate recovers.',
+        exchangeRateNotSupported:
+          '{paymentCurrency} rate is not available for your payment method. Please check your payment method configuration.',
+        exchangeRateFetchFailed:
+          'Unable to retrieve {paymentCurrency} rate at this time. System will auto-retry shortly.',
       },
+      // For skipped scenarios (no invoice)
+      titleSkipped: 'Auto Top-Up Skipped',
+      titleSkippedSlippageExceeded: 'Auto Top-Up Skipped: Rate Below Your Limit',
+      titleSkippedExchangeRateNotSupported: 'Auto Top-Up Skipped: Currency Not Supported',
+      titleSkippedExchangeRateFetchFailed: 'Auto Top-Up Skipped: Rate Unavailable',
+      bodySkipped: 'Your {creditCurrencyName} auto top-up scheduled for {at} was skipped. Details:',
+      adjustSettings: 'Adjust Settings',
     },
 
     autoRechargeDailyLimitExceeded: {
@@ -332,5 +348,39 @@ export default flat({
       status: 'Status',
       lessThanOnePercent: 'less than 1%',
     },
+
+    subscriptionSlippageWarning: {
+      title: 'Rate Alert: {productName} Renewal',
+      body: 'Your {productName} subscription will renew in {timeUntilRenewal}. The current exchange rate ({currentRate}) is below your minimum acceptable rate ({minAcceptableRate}). If the rate does not recover before renewal, automatic payment may fail.',
+      currentRate: 'Current Rate',
+      minAcceptableRate: 'Minimum Acceptable Rate',
+      renewalTime: 'Renewal Time',
+      adjustSlippage: 'Adjust Slippage Settings',
+    },
+
+    subscriptionSlippageExceeded: {
+      title: 'Payment Paused: {productName}',
+      body: 'Your {productName} subscription renewal has been paused because the current exchange rate ({currentRate}) is below your minimum acceptable rate ({minAcceptableRate}). The system will not auto-retry. Please pay manually to restore your subscription.',
+      currentRate: 'Current Rate',
+      minAcceptableRate: 'Minimum Acceptable Rate',
+      payNow: 'Pay Now',
+      adjustSlippage: 'Adjust Slippage Settings',
+    },
+
+    exchangeRateAlert: {
+      spread_exceeded: {
+        title: 'Exchange Rate Alert: High Spread Detected ({symbol})',
+        body: 'The exchange rate spread for {symbol} has reached {spreadPercent}%, exceeding the threshold of {threshold}%. This may indicate rate source instability.',
+      },
+      providers_unavailable: {
+        title: 'Exchange Rate Alert: All Providers Unavailable ({symbol})',
+        body: 'All exchange rate providers for {symbol} are currently unavailable. Exchange rate queries will fail until providers recover.',
+      },
+      timestamp: 'Time',
+      symbol: 'Symbol',
+      spread: 'Spread',
+      providers: 'Provider Rates',
+      viewProviders: 'View Provider Settings',
+    },
   },
 });

package/api/src/locales/zh.ts

@@ -157,6 +157,8 @@ export default flat({
         '预计扣款金额为 {price}，但当前余额不足(余额为 {balance})，请确保您的账户余额充足，避免扣费失败。',
       renewAmount: '扣费金额',
       estimatedAmountNote: '预估 {amount}，按最终用量计费',
+      estimatedAmountNoteRate: '预估 {amount}，按扣费时汇率计算',
+      estimatedAmountNoteRateAndUsage: '预估 {amount}，按最终用量与扣费时汇率计算',
     },
 
     subscriptionRenewed: {
@@ -195,7 +197,19 @@ export default flat({
         noEnoughToken: '您的账户代币余额为 {balance}，不足 {price}，请充值代币。',
         noSupported: '不支持使用代币扣费，请检查您的套餐。',
         txSendFailed: '扣费交易发送失败。',
+        // 跳过原因（动态定价）
+        slippageExceeded:
+          '当前 {paymentCurrency} 汇率为 {currentRate}，低于您设置的下限 {minAcceptableRate}。汇率恢复后系统将自动重试。',
+        exchangeRateNotSupported: '您的支付方式暂不支持 {paymentCurrency} 汇率查询，请检查支付方式配置。',
+        exchangeRateFetchFailed: '暂时无法获取 {paymentCurrency} 汇率，系统将稍后自动重试。',
       },
+      // 跳过场景（无 invoice）
+      titleSkipped: '自动充值跳过',
+      titleSkippedSlippageExceeded: '自动充值跳过：汇率低于您设置的下限',
+      titleSkippedExchangeRateNotSupported: '自动充值跳过：货币暂不支持',
+      titleSkippedExchangeRateFetchFailed: '自动充值跳过：暂无法获取汇率',
+      bodySkipped: '您的 {creditCurrencyName} 自动充值（原定于 {at}）已跳过。详情：',
+      adjustSettings: '调整设置',
     },
 
     autoRechargeDailyLimitExceeded: {
@@ -320,5 +334,39 @@ export default flat({
       status: '状态',
       lessThanOnePercent: '低于 1%',
     },
+
+    subscriptionSlippageWarning: {
+      title: '汇率提醒：{productName} 续费',
+      body: '您的 {productName} 订阅将在 {timeUntilRenewal} 后续费。当前汇率（{currentRate}）低于您设置的最低可接受汇率（{minAcceptableRate}）。如果续费前汇率未恢复，自动付款可能会失败。',
+      currentRate: '当前汇率',
+      minAcceptableRate: '最低可接受汇率',
+      renewalTime: '续费时间',
+      adjustSlippage: '调整滑点设置',
+    },
+
+    subscriptionSlippageExceeded: {
+      title: '支付已暂停：{productName}',
+      body: '您的 {productName} 订阅续费已暂停，因为当前汇率（{currentRate}）低于您设置的最低可接受汇率（{minAcceptableRate}）。系统不会自动重试，请手动付款以恢复订阅。',
+      currentRate: '当前汇率',
+      minAcceptableRate: '最低可接受汇率',
+      payNow: '立即付款',
+      adjustSlippage: '调整滑点设置',
+    },
+
+    exchangeRateAlert: {
+      spread_exceeded: {
+        title: '汇率警报：检测到高价差 ({symbol})',
+        body: '{symbol} 的汇率价差已达到 {spreadPercent}%，超过阈值 {threshold}%。这可能表明汇率数据源不稳定。',
+      },
+      providers_unavailable: {
+        title: '汇率警报：所有提供商不可用 ({symbol})',
+        body: '{symbol} 的所有汇率提供商当前不可用。在提供商恢复之前，汇率查询将失败。',
+      },
+      timestamp: '时间',
+      symbol: '货币对',
+      spread: '价差',
+      providers: '提供商汇率',
+      viewProviders: '查看提供商设置',
+    },
   },
 });