Python Scripting

Nest Scripts

Exact-input swaps and typed liquidity actions from Python V2.

Nest scripts can read live pool trades and execute swaps on HyperEVM and Elysium. HyperEVM also supports wallet-owned liquidity actions. Set up the execution wallet with mlab auth set nest for HyperEVM or mlab auth set elysium for Elysium. A read-only script needs no funded wallet. For the editor and deployment flow, see Nest Scripts in Furge.

Declare the pool

Use the displayed BASE/QUOTE pair from the Nest catalog. Matching is case-insensitive and follows the catalog’s base and quote order. A pair must match exactly one initialized pool. If several pools match, add :classic, :concentrated, or :v4 before @trades@nest. If the type still matches more than one pool, use the exact market key. Elysium keys use 99901:<hook>:<pool-id>.

script = {"name": "nest-watch", "version": "2", "lookback": 1}
SOURCE = "UBTC/USDC@trades@nest"


def on_data(ctx, history):
    trade = history.source(SOURCE, 0)
    if trade is not None:
        return {"metrics": {"price": trade["price"]}}

For example, UBTC/USDC:concentrated@trades@nest selects a unique initialized concentrated pool for that pair. UBTC/USDC is a Nest catalog alias. Standalone mlab script run resolves it when creating the job. Furge resolves it during deployment verification. The job retains the resolved pool through restarts and execution. A new job can resolve the current catalog again.

You can also call history.trades("nest", "UBTC/USDC", 0). For a trade read through the named source, ctx.source contains the normalized selector ubtc/usdc@trades@nest, and ctx.symbol contains the canonical pool key.

Use <pool-address>@trades@nest to identify one contract across runs. Existing 999:<pool-address> forms continue to work. The following address example declares a pool containing WHYPE and can be used with the native HYPE swap below.

script = {"name": "nest-watch", "version": "2", "lookback": 1}
MARKET = "0x20e6e73c91a29d21bde672562a4b16649d66623e"


def on_data(ctx, history):
    trade = history.trades("nest", MARKET, 0)
    if trade is not None:
        return {"metrics": {"price": trade["price"]}}

The runtime checks that execution targets a pool declared as a script source. For swaps and liquidity actions, market accepts the pool address or the declared BASE/QUOTE alias, including its type suffix when present.

In a multi-venue job, --testnet selects testnet for exchanges that support it. Each Nest market stays on the mainnet identified by its key. Use a mainnet workspace when comparing live Nest and Hyperliquid prices.

Use UBTC/USDC@volumes@nest:timeframe=60 for a live indexed volume profile. Registered pools also support historical candles and aggregate volumes within their stored coverage. See Data Sources.

Typed execution actions

These are API fragments to use inside an intentional execution condition. Calling one on every market update can repeatedly spend funds.

ctx.buy({
    "exchange": "nest",
    "market": MARKET,
    "amount": "0.001",
    "slippage_bps": 50,
    "max_gas": "0.001",
    "key": "swap-1",
})

amount and max_gas are decimal strings, not floating-point numbers. The gas value is an explicit per-transaction ceiling in HYPE; choose it deliberately. ctx.buy spends the selected pool’s quote asset. ctx.sell spends the base token. A pool quoted in WHYPE requires a WHYPE balance.

Pool typeHelpersRequired position fields
Classicctx.deposit, ctx.withdrawExact amount0/amount1 or shares strings
Concentratedctx.mint_rangeExact amount0/amount1, integer tick_lower/tick_upper
Concentratedctx.increase_rangeString token_id, exact amount0/amount1
Concentratedctx.decrease_rangeString token_id, integer-unit liquidity string
Concentratedctx.collect_range, ctx.close_rangeString token_id

Every request also carries exchange, market, a stable key and a gas cap. Tick bounds must match the pool's spacing and protocol limits. IDs and raw liquidity must remain strings, including values above 2^53. LP principal uses ERC-20 balances; native HYPE for gas is separate from wrapped HYPE.

A returned reference is queued work, not a confirmed position. Observe on_execution(ctx) and its contract.confirmed event before acting on a receipt-derived NFT ID, shares or token amounts. Reusing a key for the same request resolves the existing operation; reusing it for different intent is rejected. The daemon persists signed bytes before broadcast and reconciles uncertain submissions rather than signing a replacement blindly.

These are onchain actions, not perpetual orders. Nest has no resting order book, leverage, reduce-only orders or contract-transaction historical simulator through this integration.

Fees and reward claims

Range fee collection and liquidity withdrawal do not claim NEST or campaign tokens. Python's current helpers do not stake Classic LP tokens in gauges or submit signed concentrated-position or Elysium campaign reward claims.

On HyperEVM, Classic direct gauge emissions require a separate LP-token stake. Concentrated positions use Nest's signed wallet-position claim flow. Elysium V4 campaigns have a separate claim flow on Elysium. Whether a pool pays LP fees, token rewards or both follows its explicit catalog metadata; a pool APR is not a wallet's claimable balance.

Ordinary LP rewards do not require a veNEST lock. HEV/HYPE rewards require a separate optional locker/vault position and are not created by these helpers. See Nest reward mechanics and current support and the official Nest Dashboard.

On this page