Gas on Receive 可帮助用户在跨链兑换过程中，于目标链上获得原生 Gas 代币。这可以避免用户因缺少后续交易所需的 Gas，而拿到无法使用的资产后“卡住”。
Widget: 自动检测是否需要，用户可手动开启/关闭（v3.14.0+）
Client Library: 需要手动配置（v1.5.0+）
工作原理
启用 Gas on Receive 后，Widget 会自动：
- 检测目标链上的 Gas 余额是否不足
- 将兑换拆分为两部分：
- 主路由：你的主要兑换交易
- Gas 路由：一笔专门用于获取 Gas 代币的小额兑换
- 提供原生代币，用于支付目标链上的 Gas 费用
- 向用户显示 Gas 补充的金额和状态
支持的目标链
- Cosmos 链（例如 Osmosis、Juno、Stargaze）
- EVM L2 链（例如 Arbitrum、Polygon、Base）
不支持
- Ethereum 主网（因 Gas 成本过高而禁用）
- Solana（当前不支持）
默认 Gas 金额
该功能会自动提供以下等值金额的 Gas 代币：
- Cosmos 链：0.10 美元等值
- EVM L2 链：2.00 美元等值
这些金额旨在覆盖对应链类型上的多次交易。
自动启用
当满足以下条件时，Gas on Receive 会自动启用：
- 目标链受支持
- 用户的目标地址 Gas 余额不足（< 当前 Gas 价格的 3 倍）
- 目标资产与该链的原生 Gas 代币不同
用户也可以通过 Widget 界面手动开启或关闭该功能。
成本影响：Gas 路由会使用你兑换金额中的一小部分（例如 0.10 至 2.00 美元），因此会略微减少主兑换的最终输出。
用户界面
该功能在 Widget 中会显示为：
- 开关：允许用户启用或禁用该功能
- Gas 金额显示：展示将收到多少 Gas（例如“启用 Gas 补充 - 你将收到价值 $2.00 的 ETH”）
- 交易状态：执行过程中显示“正在接收价值 $2.00 的 ETH 作为 Gas 补充”
- 完成状态：成功后显示“已收到价值 $2.00 的 ETH 作为 Gas 补充”
Gas on Receive 无需配置，Widget 会自动检测何时需要，并显示开关：
import { Widget } from "@skip-go/widget";
function MyApp() {
return (
<Widget
defaultRoute={{
srcChainId: "osmosis-1",
destChainId: "42161", // Arbitrum
srcAssetDenom: "uosmo",
destAssetDenom: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1" // WETH
}}
// Widget automatically:
// 1. Detects when user lacks gas on destination chain
// 2. Shows "Enable gas top up" toggle for supported chains
// 3. User manually enables/disables the feature
/>
);
}
Client Library 用法
Client Library 需要使用 executeMultipleRoutes 手动配置（v1.5.0+）。当你在构建自定义界面，或需要比 Widget 提供的更多控制能力时，可以使用这种方式：
import { executeMultipleRoutes, route } from "@skip-go/client";
// Create your main route and a smaller gas route
const mainRoute = await route({
amountIn: "1000000", // 1 OSMO
sourceAssetChainId: "osmosis-1",
sourceAssetDenom: "uosmo",
destAssetChainId: "42161", // Arbitrum
destAssetDenom: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1" // WETH
});
const gasRoute = await route({
amountIn: "50000", // ~$2 worth for gas
sourceAssetChainId: "osmosis-1",
sourceAssetDenom: "uosmo",
destAssetChainId: "42161",
destAssetDenom: "0x0000000000000000000000000000000000000000" // Native ETH
});
// Execute both routes together
await executeMultipleRoutes({
route: { mainRoute, gasRoute },
userAddresses: {
mainRoute: [
{ chainId: "osmosis-1", address: "osmo1..." },
{ chainId: "42161", address: "0x..." }
],
gasRoute: [
{ chainId: "osmosis-1", address: "osmo1..." },
{ chainId: "42161", address: "0x..." }
]
},
slippageTolerancePercent: {
mainRoute: "1",
gasRoute: "10",
},
// Required signing functions
getCosmosSigningClient: async (chainId) => {
// Return your cosmos signing client for the chain
return yourCosmosWallet.getSigningClient(chainId);
},
getEVMSigningClient: async (chainId) => {
// Return your EVM signing client for the chain
return yourEvmWallet.getSigningClient(chainId);
},
onRouteStatusUpdated: (status) => console.log(status)
});
提示：大多数开发者都应使用 Widget 来自动管理 Gas。只有在你需要自定义 Gas 金额，或正在构建自定义界面时，才应使用 Client Library 方案。
手动配置 Gas 路由
如需更多控制，你可以根据用户余额手动判断何时包含 Gas 路由：
import { balances } from "@skip-go/client";
// Check if user has sufficient gas balance
const userBalances = await balances({
chains: {
"42161": { address: "0x..." } // User's Arbitrum address
}
});
const chainBalances = userBalances.chains?.["42161"]?.denoms;
const nativeTokenBalance = chainBalances?.["0x0000000000000000000000000000000000000000"];
// Simple check: does user have any native token balance?
const hasEnoughGas = nativeTokenBalance?.amount && nativeTokenBalance.amount !== "0";
if (!hasEnoughGas) {
// Include gas route in executeMultipleRoutes
console.log("User needs gas - including gas route");
} else {
// Execute only main route
console.log("User has sufficient gas");
}
自定义 Gas 金额（高级）
对于高级用例，你可以在创建 Gas 路由时调整 amountIn 来自定义 Gas 金额。默认等值金额如下：
- Cosmos 链：0.10 美元
- EVM L2 链：2.00 美元
错误处理
如果 Gas 路由失败：你的主兑换会照常继续，只是不会收到 Gas 代币。不会有资金丢失。
如果主兑换失败：你会收到已支付对应金额的 Gas 代币，以及以原始源代币形式返还的任何剩余资金。
故障排查
功能没有出现？
- 确保你使用的是 Widget v3.14.0+ 或 Client Library v1.5.0+
- 检查目标链是否受支持（Cosmos 链、EVM L2）
- 如果用户已经有足够的 Gas，或目标资产就是原生 Gas 代币，该功能会自动禁用
交易有问题？
- Gas 补充失败不会影响主兑换，资产会安全返还
- 即使 Gas 路由失败，主兑换仍可能成功
如需了解高级路由配置，请参阅配置。
Gas on Receive helps users get native gas tokens on destination chains during cross-chain swaps. This prevents users from getting “stuck” with assets they can’t use due to lacking gas for future transactions.
Widget: Auto-detects need, user toggles on/off (v3.14.0+)
Client Library: Manual setup required (v1.5.0+)
How It Works
When Gas on Receive is enabled, the widget automatically:
- Detects insufficient gas balance on the destination chain
- Splits the swap into two parts:
- Main route: Your primary swap transaction
- Fee route: A smaller swap specifically for obtaining gas tokens
- Provides native tokens for gas fees on the destination chain
- Displays the gas top-up amount and status to users
Supported Destination Chains
Supported
- Cosmos chains (e.g., Osmosis, Juno, Stargaze)
- EVM L2 chains (e.g., Arbitrum, Polygon, Base)
Not Supported
- Ethereum mainnet (disabled due to high gas costs)
- Solana (not currently supported)
Default Gas Amounts
The feature automatically provides gas tokens worth:
- Cosmos chains: $0.10 USD equivalent
- EVM L2 chains: $2.00 USD equivalent
These amounts are designed to cover multiple transactions on the respective chain types.
Automatic Activation
Gas on Receive automatically activates when:
- The destination chain is supported
- The user’s destination address has insufficient gas balance (< 3x current gas price)
- The destination asset is different from the chain’s native gas token
Users can manually toggle the feature on/off via the widget interface.
Cost Impact: The gas route uses a small portion of your swap amount (e.g., 0.10−2.00) which slightly reduces your main swap output.
User Interface
The feature appears in the widget as:
- Toggle switch: Allows users to enable/disable the feature
- Gas amount display: Shows how much gas will be received (e.g., “Enable gas top up - You’ll get $2.00 in ETH”)
- Transaction status: During execution, shows “Receiving $2.00 in ETH as gas top-up”
- Completion status: After success, displays “Received $2.00 in ETH as gas top-up”
Configuration
Gas on Receive requires no configuration - the widget auto-detects when it’s needed and shows a toggle switch:
import { Widget } from "@skip-go/widget";
function MyApp() {
return (
<Widget
defaultRoute={{
srcChainId: "osmosis-1",
destChainId: "42161", // Arbitrum
srcAssetDenom: "uosmo",
destAssetDenom: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1" // WETH
}}
// Widget automatically:
// 1. Detects when user lacks gas on destination chain
// 2. Shows "Enable gas top up" toggle for supported chains
// 3. User manually enables/disables the feature
/>
);
}
Client Library Usage
The client library requires manual setup using executeMultipleRoutes (v1.5.0+). Use this when building custom interfaces or need more control than the widget provides:
import { executeMultipleRoutes, route } from "@skip-go/client";
// Create your main route and a smaller gas route
const mainRoute = await route({
amountIn: "1000000", // 1 OSMO
sourceAssetChainId: "osmosis-1",
sourceAssetDenom: "uosmo",
destAssetChainId: "42161", // Arbitrum
destAssetDenom: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1" // WETH
});
const gasRoute = await route({
amountIn: "50000", // ~$2 worth for gas
sourceAssetChainId: "osmosis-1",
sourceAssetDenom: "uosmo",
destAssetChainId: "42161",
destAssetDenom: "0x0000000000000000000000000000000000000000" // Native ETH
});
// Execute both routes together
await executeMultipleRoutes({
route: { mainRoute, gasRoute },
userAddresses: {
mainRoute: [
{ chainId: "osmosis-1", address: "osmo1..." },
{ chainId: "42161", address: "0x..." }
],
gasRoute: [
{ chainId: "osmosis-1", address: "osmo1..." },
{ chainId: "42161", address: "0x..." }
]
},
slippageTolerancePercent: {
mainRoute: "1",
gasRoute: "10",
},
// Required signing functions
getCosmosSigningClient: async (chainId) => {
// Return your cosmos signing client for the chain
return yourCosmosWallet.getSigningClient(chainId);
},
getEVMSigningClient: async (chainId) => {
// Return your EVM signing client for the chain
return yourEvmWallet.getSigningClient(chainId);
},
onRouteStatusUpdated: (status) => console.log(status)
});
Tip: Most developers should use the widget for automatic gas management. Only use the client library approach if you need custom gas amounts or are building a custom interface.
Manual Gas Route Setup
For more control, you can manually determine when to include gas routes based on user balances:
import { balances } from "@skip-go/client";
// Check if user has sufficient gas balance
const userBalances = await balances({
chains: {
"42161": { address: "0x..." } // User's Arbitrum address
}
});
const chainBalances = userBalances.chains?.["42161"]?.denoms;
const nativeTokenBalance = chainBalances?.["0x0000000000000000000000000000000000000000"];
// Simple check: does user have any native token balance?
const hasEnoughGas = nativeTokenBalance?.amount && nativeTokenBalance.amount !== "0";
if (!hasEnoughGas) {
// Include gas route in executeMultipleRoutes
console.log("User needs gas - including gas route");
} else {
// Execute only main route
console.log("User has sufficient gas");
}
Custom Gas Amounts (Advanced)
For advanced use cases, you can customize gas amounts by adjusting the amountIn when creating gas routes. The default equivalent amounts are:
- Cosmos chains: $0.10 USD
- EVM L2 chains: $2.00 USD
Error Handling
If gas route fails: Your main swap continues normally, you just won’t receive the gas tokens. No funds are lost.
If main swap fails: You receive the gas tokens you paid for, plus any remaining funds in your original source token.
Troubleshooting
Feature not appearing?
- Ensure you’re using Widget v3.14.0+ or Client Library v1.5.0+
- Check that the destination chain is supported (Cosmos chains, EVM L2s)
- Feature auto-disables if user already has sufficient gas or destination asset is the native gas token
Transaction issues?
- Gas top-up failures don’t affect your main swap - assets are safely returned
- Main swap may succeed even if gas route fails
For advanced routing configuration, see Configuration. 
