defimind 0.1.2

StateTwins — DeFiMind's Uniswap position monitor over the MCP endpoint. Analysis only.

defimind

DeFiMind's monitoring agent — StateTwins. It observes your Uniswap liquidity positions, consults DeFiMind's hosted analytics, and reports its findings so you can make informed decisions.

It watches and reports. It does not trade, rebalance, or move funds — you make every decision. Think of it as an automated monitor over your positions, not a bot that manages your money.

Powered by DeFiMind · mcp.defimind.ai · built on the open-source DeFiPy State Twins substrate.

StateTwins runs on — and is named for — the State Twins substrate: an off-chain replica of on-chain pool state.

---

What this is

defimind is an installable Python agent. StateTwins, the agent it ships, runs a loop: it reads the pools you configure, asks the hosted DeFiMind MCP endpoint to inspect them, and reports what comes back — pool health and rug signals on a schedule, with the full analysis printed every cycle.

The work is split deliberately:

• The agent (this package) holds the loop: read config, call the endpoint, report, repeat. It's a thin client — a few hundred readable lines.
• The DeFiMind endpoint does the chain reads (through your RPC) and the AMM math. The agent sends a pool address and your RPC URL; the server does the rest.
• Nothing here imports DeFiPy or does DeFi math locally. By design — the math lives behind the endpoint, open-source and verifiable at defipy.org.

Analysis only. StateTwins surfaces information; it never decides or executes. The decision is always yours.

Install

pip install .                      # from a clone of this repo
# or, for development:
pip install -e ".[dev]"

This installs the defimind console command.

Quickstart (the 10-minute path)

# 1. Configure: copy the example and fill in your RPC + pools
cp config.example.toml config.toml
#    edit config.toml — add your RPC URL and the pools you want watched

# 2. Run
defimind

On each cycle, StateTwins prints a health + rug-signal read on every pool in your watchlist: watch, analyze, report, wait, repeat.

Heads up: you supply your own RPC URL (it may contain an API key). It goes in config.toml, which is git-ignored. Never commit it.

What you'll see

A real cycle against the hosted endpoint (USDC/WETH 0.05% V3, mainnet). When a rug signal trips, StateTwins prints the full payload and adds an ⚠ ALERT line:

StateTwins is watching 1 pool(s) via https://mcp.defimind.ai/mcp
Cycle every 60s. Analysis only — StateTwins reports, you decide.
Ctrl-C to stop.

[2026-06-15 19:40:25Z] USDC/WETH 0.05% (V3) — CheckPoolHealth
{
  "version": "V3",
  "token0_name": "USDC",
  "token1_name": "WETH",
  "spot_price": 0.0005474970758436177,
  "reserve0": 257715436.32933998,
  "reserve1": 141098.44779007568,
  "total_liquidity": 6030194.693176328,
  "tvl_in_token0": 515430872.65867996,
  "num_lps": 1,
  "top_lp_share_pct": 1.0,
  "has_activity": false,
  "fee_pips": 500,
  "tvl_in_token1": 282196.89558015135,
  "tick_current": -75106
}

[2026-06-15 19:40:26Z] USDC/WETH 0.05% (V3) — DetectRugSignals
{
  "tvl_suspiciously_low": false,
  "single_sided_concentration": true,
  "inactive_with_liquidity": false,
  "signals_detected": 1,
  "risk_level": "medium",
  "details": [
    "single_sided_concentration: top LP holds 100.0% of supply (threshold 90.0%)",
    "inactive_with_liquidity: unavailable for V3 (no per-swap history)"
  ]
}
  ⚠ ALERT: rug signal tripped: single_sided_concentration

(Trimmed for length — CheckPoolHealth also returns total_fee0/1, num_swaps, fee_accrual_rate_recent; DetectRugSignals nests the full pool_health block.)

How it works

  defimind (this package)             DeFiMind endpoint                 substrate
  ───────────────────────             ─────────────────                 ─────────
  read config.toml
  for each pool, each cycle:
    call a tool  ───────────────────▶ mcp.defimind.ai/mcp
                                      reads chain via your RPC  ──────▶  DeFiPy
                                      runs the analysis                 State Twins
    receive result  ◀───────────────  returns a typed result
    report / alert
  sleep, repeat

The agent is a client. The value — chain reads, AMM math, State Twins — lives on the DeFiMind server. The agent stays thin and readable; every analysis is a call to DeFiMind's hosted infrastructure. The math is open; the reports are paid.

The tools it calls

The hosted endpoint exposes five tools over Uniswap V2/V3. The default monitoring mode uses the two suited to continuous watching:

• CheckPoolHealth — TVL, reserves, LP concentration, recent activity.
• DetectRugSignals — threshold-based rug flags on a pool's on-chain state.

The other three — AnalyzePosition, SimulatePriceMove, CalculateSlippage — are available at the same endpoint.

Configuration

Everything the agent needs is in config.toml (copy from config.example.toml):

• rpc_url — your own RPC endpoint (the server reads chain state through it)
• endpoint — the DeFiMind MCP URL (defaults to the hosted server)
• poll_interval_seconds — how often to run a cycle
• a [[pools]] block per pool — address, pool_type (uniswap_v2 / uniswap_v3), an optional chain_id guard, and a friendly label

Scope boundary (please read)

StateTwins produces analysis, not advice and not action. It does not tell you to enter, exit, or rebalance a position, and it does not transact. It reports the current state and risk of your positions; the decision is always yours. This is intentional and permanent.

Develop

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Tests (offline by default):

pytest tests/

Optional live gate (hits the real endpoint with a real pool; needs your own RPC):

DEFIMIND_TEST_RPC_URL="https://eth-mainnet.example/v2/<key>" pytest tests/test_live.py -v

Roadmap

defimind v0.1 is the free monitoring agent. StateTwins is built around modes (one question-shape each); monitoring ships first, with screening, ensemble, comparative, and treasury modes as the package grows. Heavier paid-compute analyses may later be offered as a metered tier — a future, opt-in addition, not part of the free agent.

License

Apache-2.0. See LICENSE. Free to fork, modify, and build on.

See also

• DeFiMind MCP endpoint: mcp.defimind.ai · defimind-mcp
• DeFiPy (open-source substrate): https://defipy.org
• DeFiMind: https://defimind.ai
• State Twins paper: https://arxiv.org/abs/2605.11522