StateTwins.
StateTwins watches your Uniswap liquidity positions, consults EchoLedger’s hosted analytics, and reports its findings so you can make informed decisions. It does not trade, rebalance, or move funds — you make every decision.
Named for the State Twins substrate it runs on — an off-chain replica of on-chain pool state.
Watch. Analyze. Report.
On a schedule you set, StateTwins cycles through every pool in your watchlist, asks EchoLedger’s hosted tools to inspect each one, and prints the result. Two tools run by default — CheckPoolHealth and DetectRugSignals — chosen because they suit continuous watching. Three more are available at the same endpoint and one line of code away.
A real cycle against the hosted endpoint, watching a Uniswap V3 USDC/WETH pool on mainnet:
StateTwins is watching 1 pool(s) via https://mcp.echoledger.ai/mcp
Cycle every 60s. Analysis only — StateTwins reports, you decide.
[2026-06-15 19:40:25Z] USDC/WETH 0.05% (V3) — CheckPoolHealth
{
"version": "V3",
"spot_price": 0.000547,
"tvl_in_token0": 515430872.65,
"num_lps": 1,
"top_lp_share_pct": 1.0,
"has_activity": false,
"fee_pips": 500
}
[2026-06-15 19:40:26Z] USDC/WETH 0.05% (V3) — DetectRugSignals
{
"single_sided_concentration": true,
"signals_detected": 1,
"risk_level": "medium",
"details": [
"single_sided_concentration: top LP holds 100.0% of supply (threshold 90.0%)"
]
}
⚠ ALERT: rug signal tripped: single_sided_concentrationStateTwins prints the full payload every cycle and emits an ⚠ ALERT line when a signal trips. When nothing changes, you see steady output; when something changes, the change is loud.
The 10-minute path.
StateTwins ships as the echoledger Python package. Install, point it at your pools, run. The hosted endpoint is authless — no account, no API key, no wallet signature. You supply your own RPC URL per call (bring-your-own-RPC); it’s never stored or logged.
1. Install the package
git clone https://github.com/echoledger-ai/echoledger.git
cd echoledger
python -m venv .venv && source .venv/bin/activate
pip install .Requires Python 3.11+. Installing the package puts a echoledger command on your PATH.
2. Configure your watchlist
cp config.example.toml config.toml
# edit config.toml — set rpc_url and add [[pools]] blocksA pool block looks like:
rpc_url = "https://your-rpc-provider.example/v2/<key>"
endpoint = "https://mcp.echoledger.ai/mcp"
poll_interval_seconds = 60
[[pools]]
label = "USDC/WETH 0.05% (V3)"
address = "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
pool_type = "uniswap_v3"
chain_id = 1config.toml is git-ignored. Your RPC URL stays local; the server reads chain state through it but never persists it.
3. Run it
echoledgerStateTwins prints its intro line, runs a cycle, sleeps for poll_interval_seconds, and repeats. Ctrl-C to stop.
A thin client. Open math underneath.
The echoledger package holds the loop. The hosted MCP endpoint does the chain reads and the AMM math. The math itself is open-source. Three layers, each one stateless, each one verifiable.
StateTwins (echoledger package) EchoLedger endpoint substrate
───────────────────────────── ───────────────── ─────────
read config.toml
for each pool, each cycle:
call a tool ──────────────────▶ mcp.echoledger.ai/mcp
reads chain via your RPC ────▶ defipy
runs the analysis State Twins
receive result ◀────────────── returns a typed result
report / alert
sleep, repeatAuthless, BYO-RPC
The endpoint requires no API key and no account. You supply your own RPC URL per call — it carries any keys you hold, it stays in your config, the server reads through it once and redacts it from every receipt.
Stateless by construction
Each call builds a fresh State Twin, runs an AMM primitive, returns a typed result. Nothing is cached between calls. Nothing is logged except a redacted JSON receipt per invocation.
Powered by open-source defipy
The AMM math behind every StateTwins report lives in the defipy library — open, peer-style researched, verifiable. The math is open; the reports are paid.
The State Twin.
StateTwins’ reasoning runs against a typed, in-memory replica of on-chain pool state — a State Twin. Without it, every “what if?” question would cost an RPC read or a real transaction. With it, an agent can fork, replay, and explore counterfactuals at memory speed.
Agentic DeFi reasoning today couples to chain time. Every analytical question — will this position survive a 30% drop?, what’s the slippage at twice the size?, how would this position have done if we’d entered last week?— incurs either a fresh RPC read or, worse, a real transaction. The agent’s effective action space is bounded by block confirmation latency and gas. That’s a structural problem, not a performance one.
The State Twin is the missing layer: a typed, in-memory replica of an on-chain AMM pool that preserves the protocol’s exact mathematics while admitting the operations on-chain state cannot. Forking. Replay. Branching. Counterfactual rollout. A single live RPC read can seed N independent twins under distinct scenarios, all evaluated in sub-second wall-clock time. The math is identical to the chain; the questions are unbounded.
This is the substrate StateTwins runs on. Every CheckPoolHealth report, every DetectRugSignals trip, every counterfactual it’ll eventually run as new modes ship — all of it happens against State Twin replicas of the pools you care about. The formal definition, fidelity bound, and reference implementation are in the paper.
Analysis only. You decide.
StateTwins produces analysis, not advice and not action. It does not tell you to enter, exit, or rebalance a position. It does not transact. It does not hold keys.
What it reports is information about your positions’ current state and risk; the decision is always yours. This is intentional and it is where the line stays. The agentic stack StateTwins runs in is observation-only by design — the State Twins paper formalizes why the boundary belongs there.
It’s always StateTwins, in modes.
Today StateTwins runs one mode: monitoring. New capabilities arrive as new modes — each one a question-shape StateTwins can carry, each one composed from the same hosted tools and the same open-source substrate.
Monitoring
Watch a list of pools on a schedule. Pool health and rug signals, every cycle.
Screening
Filter a candidate set of pools against thresholds; surface the ones worth a closer look.
Treasury
Multi-position view for DAOs and funds — concentration, correlation, aggregate IL trajectory.
v0.1 is the free AI agent. Heavier paid-compute analyses may later be offered as a metered tier — opt-in, not part of the free agent.