# Elysium Scripts (/scripting-v2/elysium)



Write Python scripts that react to trades in Market Lab pools and bonding markets on Elysium testnet. No wallet is needed to read trades. External markets and backtesting are not supported yet.

## Read Trades [#read-trades]

Create `watch-market.py`. Use the **pool or bonding contract address**, not the token address, before `@trades@elysium`:

```python
script = {"name": "watch-market", "version": "2", "lookback": 100}
SOURCE = "0x59675174f1700677e608f86016f1cea764e1abfa@trades@elysium"


def on_data(ctx, history):
    trade = history.source(SOURCE, 0)
    market = trade["onchain"]
    print(market["current_price"], market["volume"]["quote"])
```

`on_data` runs when a trade arrives. `lookback` keeps up to 100 trades for your script.

```bash
mlab script run watch-market.py
```

The market is validated on-chain when the script starts. No market refresh is needed.

### Latest Trade or List [#latest-trade-or-list]

Inside `on_data`, choose which records to read:

```python
latest = history.source(SOURCE, 0)    # Latest trade
previous = history.source(SOURCE, 1)  # One trade before the latest
earlier = history.source(SOURCE, 2)   # Two trades before the latest
trades = history.source(SOURCE)      # List, oldest to newest
```

An index returns one trade, or `None` if it is not available yet. No index returns the retained list, or `[]` when empty, not the market's entire trading history.

## What a Trade Returns [#what-a-trade-returns]

Example bonding trade (sample values; block metadata and `state` omitted):

```json
{
  "price": 0.0001,
  "size": 10,
  "onchain": {
    "kind": "bonding",
    "market": "0x59675174f1700677e608f86016f1cea764e1abfa",
    "side": "buy",
    "base": {
      "symbol": "gurt",
      "address": "0x1171daed16376968bdd3d865318a9a4f3687f328",
      "decimals": 18
    },
    "quote": {
      "symbol": "HYPE",
      "address": null,
      "decimals": 18
    },
    "base_amount": "10",
    "quote_amount": "0.001",
    "current_price": 0.000100004,
    "fee": {
      "amount": "0.000003",
      "asset": {
        "symbol": "HYPE",
        "address": null,
        "decimals": 18
      }
    },
    "volume": {
      "base": "10",
      "quote": "0.001",
      "trades": 1,
      "from_block": 3000000,
      "through_log_index": 0
    }
  }
}
```

Read these fields from `trade`:

| Field                                              | Meaning                                                                            |
| -------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `price`, `size`                                    | Trade execution price and base-token quantity                                      |
| `onchain.side`                                     | `buy` or `sell` of the base token                                                  |
| `onchain.base`, `onchain.quote`                    | Each asset's `symbol`, `address`, and `decimals`; native HYPE has no token address |
| `onchain.base_amount`, `onchain.quote_amount`      | Exact traded amounts as decimal strings                                            |
| `onchain.current_price`                            | Price per base token at the end of the confirmed block, or `None` if undefined     |
| `onchain.fee`                                      | Fee `amount` and `asset`                                                           |
| `onchain.volume`                                   | Observed `base` and `quote` totals and number of `trades`, not 24-hour volume      |
| `onchain.state`                                    | Pool reserves or bonding market state                                              |
| `onchain.kind`, `onchain.market`                   | Market type and contract address                                                   |
| `onchain.transaction_hash`, `onchain.timestamp_ms` | Transaction and trade time in milliseconds                                         |

For example, `trade["onchain"]["fee"]["amount"]` reads the fee paid. Trades arrive after 12 block confirmations; the current market price can differ from the trade's execution price.

## Trade From Your Script [#trade-from-your-script]

```bash
mlab auth set elysium
```

This creates a trading wallet and prints its address. Fund it with HYPE for gas and the assets you want to trade.

Use `ctx.swap` inside `on_data` to buy or sell, after reading that market with `history.source`. This example buys with `0.01` HYPE:

```python
ctx.swap({
    "exchange": "elysium",
    "market": "0x59675174f1700677e608f86016f1cea764e1abfa",
    "token_in": "native",
    "amount": "0.01",
    "key": "first-buy",
})
```

For bonding, `"native"` buys with HYPE; the token's contract address sells it. For pools, use the address of the token you are paying with, such as WHYPE.

### Add or Remove Liquidity [#add-or-remove-liquidity]

For pools only, set `POOL` to your pool's contract address and read its trades with `history.source` before calling these helpers:

```python
ctx.deposit({
    "exchange": "elysium", "market": POOL,
    "amount0": "1", "amount1": "2", "key": "deposit-1",
})

ctx.withdraw({
    "exchange": "elysium", "market": POOL,
    "shares": "0.1", "key": "withdraw-1",
})
```

`amount0` and `amount1` follow the pool's token order. `shares` is the number of LP tokens to redeem, not a percentage. Pass amounts as **decimal strings**, such as `"0.01"`, not base-unit integers.

All three helpers accept `slippage_bps` (default `50`, or 0.5%) and `max_gas` (default `"0.0001"` HYPE per transaction).

## Follow Execution [#follow-execution]

```python
def on_execution(ctx):
    event = ctx.execution
    if event["type"] == "contract.confirmed":
        print(event["key"], event["data"]["result"]["receipts"])
    elif event["type"] == "contract.failed":
        print(event["data"]["result"]["error"])
```

An action is complete when `contract.confirmed` arrives, not when the helper returns. Use a new `key` for each intended action; the same key and request will not trade again within that job.