lifi.top_up

Documentation for eth_defi.lifi.top_up Python module.

Cross-chain gas top-up orchestration using LI.FI.

High-level functions for checking gas balances across multiple EVM chains and bridging native tokens from a source chain to any target chain that is running low.

This module provides perform_top_up() which orchestrates the full flow: read configuration, check balances, prepare and execute bridge swaps, verify delivery, and display final balances.

Environment variables:

  • PRIVATE_KEY — hot wallet private key (0x-prefixed hex)

  • SOURCE_CHAIN — source chain name (e.g. arbitrum, base)

  • TARGET_CHAINS — comma-separated target chain names

  • MIN_GAS_USD — minimum gas balance in USD (default: 5)

  • TOP_UP_GAS_USD — amount to bridge when topping up in USD (default: 20)

  • DRY_RUN — set to true to only display quotes without executing

  • SOURCE_TOKEN — source token: native (default) or usdc

  • LIFI_API_KEY — optional LI.FI API key for higher rate limits

  • JSON_RPC_* — RPC URLs for each chain

  • LOG_LEVEL — logging level (default: warning)

Example:

from eth_defi.lifi.top_up import perform_top_up

perform_top_up()

Functions

create_connections(config)

Create Web3 connections and wallet from configuration.

display_balances(source_web3, target_web3s, ...)

Fetch and display gas balances across all chains.

display_proposed_swaps(swaps)

Display a table of proposed cross-chain swaps.

display_results(results)

Display a table of executed swap results.

perform_top_up()

Orchestrate the full cross-chain gas top-up flow.

read_top_up_config()

Read and validate top-up configuration from environment variables.

verify_and_display_final(results, ...)

Wait for bridge transfers, display verification status, and show final balances.

Classes

TopUpConfig

Configuration for cross-chain gas top-up.
class TopUpConfig

Bases: object

Configuration for cross-chain gas top-up.

Read from environment variables via read_top_up_config().

private_key: str

Hot wallet private key

source_chain_id: int

Source chain numeric ID

source_chain_name: str

Source chain human name

target_chain_ids: list[int]

Target chain numeric IDs

min_gas_usd: decimal.Decimal

Minimum gas balance in USD before triggering a top-up

top_up_usd: decimal.Decimal

Amount to bridge in USD when topping up

dry_run: bool

Whether to only display quotes without executing

source_token_choice: str

Source token: “native” or “usdc”

source_token_address: str

Resolved source token address

__init__(private_key, source_chain_id, source_chain_name, target_chain_ids, min_gas_usd, top_up_usd, dry_run, source_token_choice, source_token_address)
Parameters
Return type

None

read_top_up_config()

Read and validate top-up configuration from environment variables.

Returns

Validated configuration

Raises

ValueError – If required environment variables are missing or invalid

Return type

eth_defi.lifi.top_up.TopUpConfig

create_connections(config)

Create Web3 connections and wallet from configuration.

Parameters

config (eth_defi.lifi.top_up.TopUpConfig) – Top-up configuration

Returns

Tuple of (source_web3, target_web3s, wallet)

Return type

tuple[web3.main.Web3, dict[int, web3.main.Web3], eth_defi.hotwallet.HotWallet]

display_balances(source_web3, target_web3s, wallet, config)

Fetch and display gas balances across all chains.

Shows a table with native token balance, USD value, USDC balance (for source chain), and status (OK/LOW) for each chain.

Parameters
display_proposed_swaps(swaps)

Display a table of proposed cross-chain swaps.

Parameters

swaps (list[eth_defi.lifi.crosschain.CrossChainSwap]) – List of prepared swaps

display_results(results)

Display a table of executed swap results.

Parameters

results (list[eth_defi.lifi.crosschain.CrossChainSwapResult]) – List of swap execution results

verify_and_display_final(results, source_web3, target_web3s, wallet, config)

Wait for bridge transfers, display verification status, and show final balances.

  1. Polls LI.FI /v1/status for each swap until delivery or timeout

  2. Displays a verification table with transfer statuses

  3. Fetches and displays updated gas balances on all chains

Parameters
perform_top_up()

Orchestrate the full cross-chain gas top-up flow.

Reads configuration from environment variables, checks gas balances, prepares and executes bridge swaps, verifies delivery, and displays final balances.

See module docstring for environment variable reference.