> For the complete documentation index, see [llms.txt](https://docs.ethgas.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ethgas.com/get-started/traders/propamm/takers.md).

# Takers

Routing Against pAMM Liquidity

> Audience: searchers, solvers, and aggregators routing flow or arbitrage paths through pAMM liquidity in ETHGas blocks.

#### Multi-candidate bundle submission <a href="#multi-candidate-bundle-submission" id="multi-candidate-bundle-submission"></a>

Send us N candidate bundles for the same trade, each routing differently. At build time we evaluate every candidate against live state, including the freshest streamed quote from every pAMM, and include whichever gives the best outcome.

1. Construct your normal path through CFMM liquidity.
2. Construct additional variants where one or more hops route through pAMMs.
3. Submit all variants. We evaluate each against current state at build time and re-evaluate on every pAMM quote update until inclusion.

Use the same bundle submission path you already use.

#### pAMM state stream <a href="#pamm-state-stream" id="pamm-state-stream"></a>

Takers can consume a JSON stream of pAMM state overrides for makers that opt in to publishing their state. The stream is intended for searchers, solvers, and dex aggregators that want fresher routing inputs for pAMM liquidity before submitting candidate bundles.

The stream is maker opt-in. Makers choose whether to publish state, and configure the update thresholds and delay applied before state is emitted.

Some maker streams may require permissioned access. For example, a maker may only allow whitelisted takers such as dex aggregators to consume their stream. Please reach out if there are pAMM quotes you want access to that are not currently available.

#### **pAMM stream addresses**

| Maker    | Top-level stream address                                                                  | Price-level pamm address                     |
| -------- | ----------------------------------------------------------------------------------------- | -------------------------------------------- |
| Metric   | `0xe844701934d9c6085b292e428f41b911cc0b3872` `0x30a88bf894d1b806125a23ebf23d715496fd7102` | `0x99ab7c1c5eab47801f7937075998527a550fba8a` |
| Tempest  | `0x00000003f1ec2379e79f58e12ec6c4f51ee92149`                                              | `0x00000003f1ec2379e79f58e12ec6c4f51ee92149` |
| TaurusFi | `0x20861433d9119b866eeb398cb1ad46652a3cf953`                                              |                                              |

**Endpoints**

pAMM data is served from the regional data hosts.&#x20;

| Region                       | State stream (WebSocket)                                       | Price levels (WebSocket)                                        | JSON-RPC                                     |
| ---------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------- |
| `us-east-1`                  | wss\://us.propamm.data.ethgas.com/ws/pamm\_quote\_stream\_v2   | wss\://us.propamm.data.ethgas.com/ws/pamm\_price\_levels​\_v2   | <https://us.propamm.data.ethgas.com/data​>   |
| `eu-central-1`               | wss\://eu.propamm.data.ethgas.com/ws/pamm\_quote\_stream\_v2   | wss\://eu.propamm.data.ethgas.com/ws/pamm\_price\_levels​\_v2   | <https://eu.propamm.data.ethgas.com/data​>   |
| `ap-northeast-1 (Tokyo, 1a)` | wss\://ap.propamm.data.ethgas.com/ws/pamm\_quote\_stream\_v2   | wss\://ap.propamm.data.ethgas.com/ws/pamm\_price\_levels​\_v2   | <https://ap.propamm.data.ethgas.com/data​>   |
| `ap-northeast-1 (Tokyo, 1d)` | wss\://ap-2.propamm.data.ethgas.com/ws/pamm\_quote\_stream\_v2 | wss\://ap-2.propamm.data.ethgas.com/ws/pamm\_price\_levels​\_v2 | <https://ap-2.propamm.data.ethgas.com/data​> |

Hoodi staging (stable version):&#x20;

| Region     | State stream (WebSocket)                                            | Price levels (WebSocket)                                            | JSON-RPC                                         |
| ---------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------ |
| ap-east-1c | ​wss\://hoodi.propamm.data.ethgas.com/ws/pamm\_quote\_stream\_v2    | ​wss\://hoodi.propamm.data.ethgas.com/ws/pamm\_price\_levels​\_v2   | ​<https://hoodi.propamm.data.ethgas.com/data​>   |
| ap-east-1c | ​wss\://hoodi-2.propamm.data.ethgas.com/ws/pamm\_quote\_stream​\_v2 | ​wss\://hoodi-2.propamm.data.ethgas.com/ws/pamm\_price\_levels​\_v2 | ​<https://hoodi-2.propamm.data.ethgas.com/data​> |

Hoodi dev (active development version)

| Region     | State stream (WebSocket)                                                | Price levels (WebSocket)                                                | JSON-RPC                                             |
| ---------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- |
| ap-east-1c | ​wss\://hoodi-test.propamm.data.ethgas.com/ws/pamm\_quote\_stream\_v2   | ​wss\://hoodi-test.propamm.data.ethgas.com/ws/pamm\_price\_levels​\_v2  | ​<https://hoodi-test.propamm.data.ethgas.com/data​>  |
| ap-east-1c | ​wss\://hoodi-test2.propamm.data.ethgas.com/ws/pamm\_quote\_stream​\_v2 | ​wss\://hoodi-test2.propamm.data.ethgas.com/ws/pamm\_price\_levels\_2v​ | ​<https://hoodi-test2.propamm.data.ethgas.com/data​> |

**Format**

Each WebSocket message is JSON.

| Field             | Type      | Description                                                                                     |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------- |
| `maker`           | string    | Maker publishing the venue.                                                                     |
| `quoteAddress`    | string    | Address the maker publishes under (see pAMM stream addresses).                                  |
| `pricedAddresses` | string\[] | `quoteAddress` plus any pool addresses that price from this quote.                              |
| `assetPairs`      | object\[] | Pairs the quote covers, each as `token_1` and `token_2` ERC20 addresses.                        |
| `pairSequences`   | number\[] | Quote sequence for each entry in `assetPairs`.                                                  |
| `slot`            | number    | Beacon slot of the block being built. The block timestamp is `1606824023 + 12 * slot`           |
| `blockNumber`     | number    | Execution block number the state targets.                                                       |
| `timestamp`       | number    | ETHGas snapshot time in nanoseconds. This is not the block timestamp; use `slot` for block time |
| `stateOverride`   | object    | State override set for the venue.                                                               |

```json
{
  "venues": [
    {
      "maker": "Goliath",
      "quoteAddress": "0x4367985a63063fc970b009c6e599e9225181f551",
      "pricedAddresses": ["0x4367985a63063fc970b009c6e599e9225181f551"],
      "assetPairs": [
        {
          "token_1": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "token_2": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
        }
      ],
      "pairSequences": [284752574598007134814732506],
      "slot": 15436468,
      "blockNumber": 26197444,
      "timestamp": 1792061637827365465,
      "stateOverride": {
        "0x48165e588ec68e724315d3e0fe7b0f3b9b6c7a6d": {
          "balance": "0x1b67d6e14e25bd9f",
          "nonce": "0xd00"
        },
        "0xb261ef0a97bc7cf3af2025ab6b3792e6062d3d4a": {
          "balance": "0x0",
          "nonce": "0x1",
          "stateDiff": {
            "0x0000000000000000000000000000000000000000000000000000000000000000": "0x000000006ad0b0c800003c06d28e20000000000000000000000000008cd9ed84"
          }
        }
      }
    }
  ]
}
```

`stateOverride` uses the same structure as the Ethereum `eth_call` State Override Set. Its keys are account addresses, and each account override may include `balance`, `nonce`, `code`, `state`, and `stateDiff`. `stateDiff` maps storage slot keys to overridden storage values.

The `stateOverride` object can be passed directly as the third parameter to `eth_call`, or as `stateOverrides` in an `eth_simulateV1` block state call. To simulate against several pAMMs at once, merge their `stateOverride` objects into a single object keyed by account address.

**Latest state over JSON-RPC**

Takers that do not want to maintain a WebSocket connection can request the latest pAMM state over JSON-RPC on the regional data endpoint (see Endpoints).

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ethgas_getPammVenues",
  "params": []
}
```

The result is a snapshot of every pAMM venue you have access to. The result has the same shape as a WebSocket message.:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "slot": 14285824,
    "blockNumber": "0x17e4458",
    "0x5979458912f80b96d30d4220af8e2e4925a33320": { "stateOverride": { ... } },
    "0xb09aaa8933626d7e4c48d65dad2d77021cfbca9a": { "stateOverride": { ... } }
  }
}
```

**Example (Python)**

```python
import asyncio
import json
import urllib.request

import websockets

WS_URI = "wss://ap.propamm.data.ethgas.com/ws/pamm_quote_stream_v2"
RPC_URL = "https://ap.propamm.data.ethgas.com/data​"


def get_pamm_venues():
    body = json.dumps({
        "jsonrpc": "2.0",
        "id": 1,
        "method": "ethgas
        _getPammVenues",
        "params": [],
    }).encode()
    req = urllib.request.Request(
        RPC_URL, data=body, headers={"Content-Type": "application/json"}
    )
    with urllib.request.urlopen(req, timeout=10) as resp:
        return json.loads(resp.read())["result"]


def state_overrides(message):
    return {v["quoteAddress"]: v["stateOverride"] for v in message["venues"]}


async def main():
    # One-shot snapshot.
    snapshot = get_pamm_venues()
    print(list(state_overrides(snapshot)))

    # Live updates.
    async with websockets.connect(WS_URI) as ws:
        async for message in ws:
            update = json.loads(message)
            print(list(state_overrides(update)))


asyncio.run(main())
```

#### pAMM price levels <a href="#pamm-price-levels" id="pamm-price-levels"></a>

Takers can also consume a live pAMM price level stream. Unlike the state stream, this stream is already quoted by ETHGas, with one book per maker and market.

Each message is a complete snapshot. Keep the newest message and treat older ones as superseded.

Use the `/ws/pamm_price_levels_v2` path on the regional data hosts (see Endpoints).

**Latest price levels over WebSocket**

Each WebSocket message is JSON. The `books` array contains one book per maker and market.

```json
{
  "slot": 15436468,
  "block": 26197444,
  "ts": 1792061637434840374,
  "books": [
    {
      "maker": "Tempest",
      "quoteAddress": "0x00000003f1ec2379e79f58e12ec6c4f51ee92149",
      "token1": "WETH",
      "token2": "USDT",
      "token1Address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "token2Address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "calculated_from": 284752574598007134814732441,
      "bids": [
        { "price": 2365.0436, "cumVolume": 0.005 },
        { "price": 2365.0437325014946, "cumVolume": 0.008118883695943609 }
      ],
      "asks": [
        { "price": 2365.526259, "cumVolume": 0.004227389132525372 },
        { "price": 2365.526259, "cumVolume": 0.007203486723163025 }
      ]
    }
  ]
}
```

**Latest price levels over JSON-RPC**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ethgas_getPammBooks",
  "params": []
}
```

The `result` has the same shape as a WebSocket message.

#### pAMM quote helpers <a href="#pamm-quote-helpers" id="pamm-quote-helpers"></a>

ETHGas exposes two JSON-RPC quote helpers on the regional data endpoints, backed by the latest price level snapshot.

`ethgas_getPammQuoteVenue` quotes one pAMM. It mirrors the LambdaClass router `quoteVenueV1` / `quoteV1` flow.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ethgas_getPammQuoteVenue",
  "params": ["0xVenue", "0xTokenIn", "0xTokenOut", "0xAmountIn"]
}
```

`ethgas_getPammQuote` scans all pAMMs in the latest snapshot and returns the best quote plus the pAMM that produced it.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "ethgas_getPammQuote",
  "params": ["0xTokenIn", "0xTokenOut", "0xAmountIn"]
}
```

Both methods return the same response shape:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tokenIn": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "tokenOut": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "amountIn": "0xde0b6b3a7640000",
    "amountOut": "0x9fb79b90",
    "pamm": "0x00000003f1ec2379e79f58e12ec6c4f51ee92149",
    "router": "0x4ddf368080cd7946db5b459ad591c350158175e1",
    "blockNumber": 26078723,
    "slot": 15317324,
    "timestamp": 1790631904288995296
  }
}
```

#### On-chain routing <a href="#on-chain-routing" id="on-chain-routing"></a>

On-chain routing is another integration path for pAMM liquidity. It is not a separate ETHGas endpoint, but a router- or solver-side pattern that can be used alongside the bundle flow above.

The idea is to move route selection into the execution transaction. Instead of submitting a single pre-selected path, the transaction carries multiple candidates per hop. For a route from asset A to asset B to asset C, the A → B hop could have several candidate venues, and the B → C hop could have several candidate venues. Some candidates may route through standard AMM liquidity, others through pAMMs.

Because execution happens on-chain, the router evaluates the candidate set against the exact execution state and selects the best valid combination. This suits pAMM routing well because quote state can change between path construction and inclusion: if a maker update lands earlier in the same block, the router sees the updated state when the taker transaction executes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ethgas.com/get-started/traders/propamm/takers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
