# IL Observer

> A free, read-only on-chain LP impermanent-loss tracker. Drop in a wallet
> address, get a per-position breakdown comparing current LP value against
> a HODL benchmark, with fees and rewards reported separately. The core UI
> and scan/share API stay free; an optional x402 endpoint can return a paid
> deep multi-position JSON export.

IL Observer scans EVM and Solana wallets, identifies open LP positions
across nine protocols, replays each position's lifecycle on-chain, and
returns a canonical impermanent-loss number plus single-asset HODL
references for both tokens. The site is deployed at https://il.helmfinance.xyz.

Supported protocols: Uniswap V3, Uniswap V4, SushiSwap V3, PancakeSwap V3,
Aerodrome Slipstream, Ekubo, Orca Whirlpool, Raydium CLMM, ProjectX (HyperEVM),
Nest (HyperEVM).

## Public API

The core API is HTTP/JSON with no auth required. Live scans are rate-limited;
cache hits do not spend the live-scan budget. The full machine-readable spec
is at https://il.helmfinance.xyz/api/openapi.json.

- `GET  /api/health` — service status, configured RPC providers, demo count
- `GET  /api/protocols` — verified-demo registry plus protocol coverage status
- `POST /api/scan` — body `{address, demoProtocolId?, refresh?}`; returns the
  matched position, IL, fees, rewards, lifecycle events, and a snapshot ID
- `GET  /api/x402/positions?address=<wallet>` and `POST /api/x402/positions`
  — x402-protected deep scan returning all strictly renderable open positions
  plus per-candidate unavailable reasons as JSON
- `GET  /api/snapshot/<id>` — fetch a cached snapshot by 10-character hex id
- `POST /mcp` — stateless MCP JSON-RPC endpoint exposing read-only protocol
  and scan tools
- `GET  /.well-known/api-catalog` — RFC 9727 linkset for API discovery
- `GET  /.well-known/x402` — x402 payment discovery metadata
- `GET  /.well-known/agent-card.json` — A2A-style agent card for agent discovery
- `GET  /.well-known/mcp/server-card.json` — MCP server card for agent discovery
- `GET  /.well-known/agent-skills/index.json` — Agent Skills discovery index
- `GET  /.well-known/oauth-protected-resource` — OAuth protected-resource
  metadata; OAuth access tokens are not required or issued
- `GET  /sitemap.xml` — sitemap including the homepage, OpenAPI spec, and
  every verified-demo share page
- `GET  /robots.txt` — crawl rules (everything is allowed)
- `GET  /llms.txt` — this file
- `GET  /` — HTML by default; send `Accept: text/markdown` for a concise
  agent-readable Markdown summary

## Share pages

Every successful scan produces a static share page at `/s/<id>.html`. Pages
are pure server-rendered HTML — no JavaScript required to read them — and
carry both OpenGraph tags and JSON-LD structured data. Markdown content
negotiation is supported: send `Accept: text/markdown` to receive a
plaintext breakdown instead of HTML.

OG card image: `/og/<id>.png` (1200×630).

## Verified demo addresses

Each entry below is a real wallet that holds a real, currently-open LP
position. They're the canonical examples for testing the API or browsing
the share-page format.

- Uniswap V3 (Ethereum, WETH / USDT): `/api/scan` body
  `{"address":"0x924d7bcfd62596220ba7841f238a3b416e521254"}`
- Uniswap V4 Vanilla (Ethereum, ETH / TRAC): `/api/scan` body
  `{"address":"0x2828bfc9bcc2670316827cbffcb49e8e5604d741"}`
- SushiSwap V3 (Ethereum, WETH / USDT): `/api/scan` body
  `{"address":"0x12ee177db3ceafedc639d023a29cc8588db3a4b9"}`
- PancakeSwap V3 (BSC, ETH / BTCB): `/api/scan` body
  `{"address":"0x3a7701e5a2c067647b920d9dbdfe4e62550e662e"}`
- Ekubo (Ethereum, ETH / WBTC): `/api/scan` body
  `{"address":"0x3d45b65859d9d2f8baa635317abfe73b14a9cf39"}`
- Orca Whirlpool (Solana, SOL / RENDER): `/api/scan` body
  `{"address":"B5cYjddYUh6S4K7zo8nL4LLHYh48Ta4x6FM9Cvz6L7Pp"}`
- Raydium CLMM (Solana, SOL / CRCLX): `/api/scan` body
  `{"address":"CcrknJyMF6AtAtr8xaV7a4BW6NiLNP5H9vo4SqhWHpE4"}`
- ProjectX (HyperEVM, WHYPE / USDC): `/api/scan` body
  `{"address":"0xc6614a87a89aff917584dea369e6890cdc8ca8bb"}`
- Nest (HyperEVM, WHYPE / USDC): `/api/scan` body
  `{"address":"0x4489E91a8A23AE1bdfd1F0B4a8F142acAFe95eE2"}`

## Methodology

- Open positions only — closed positions are excluded by design
- HODL reference uses pool-price-consistent current marks, anchored to
  external USD prices (DefiLlama)
- Impermanent loss is reported separately from fees and from staking
  rewards; we never fold them together
- For staked Aerodrome positions, pool fees accrue to voters via
  FeesVotingReward (not the LP), and AERO emissions are reported as rewards
- Solana CLMM positions use exact-remaining-lot replay so partial
  withdrawals don't pollute the entry basis

## Source

GitHub: https://github.com/ZaK3939/il-observer

## Contact

The site exposes `POST /api/support-request` for protocol coverage requests.