# Nest Scripts (/scripting-v2/nest)



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](/scripting-v2/furge/nest).

## Declare the pool [#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>`.

```python
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.

```python
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](/scripting-v2/sources).

## Typed execution actions [#typed-execution-actions]

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

```python
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 type    | Helpers                                | Required position fields                                     |
| ------------ | -------------------------------------- | ------------------------------------------------------------ |
| Classic      | `ctx.deposit`, `ctx.withdraw`          | Exact `amount0`/`amount1` or `shares` strings                |
| Concentrated | `ctx.mint_range`                       | Exact `amount0`/`amount1`, integer `tick_lower`/`tick_upper` |
| Concentrated | `ctx.increase_range`                   | String `token_id`, exact `amount0`/`amount1`                 |
| Concentrated | `ctx.decrease_range`                   | String `token_id`, integer-unit `liquidity` string           |
| Concentrated | `ctx.collect_range`, `ctx.close_range` | String `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 [#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](/providers-execution/nest#rewards-and-current-claim-support) and the [official Nest Dashboard](https://app.usenest.xyz/dashboard).
