EchoLedger

Analyze why a Uniswap V2 or V3 LP position is gaining or losing money. Decomposes PnL into impermanent loss, accumulated fees, and net result, with optional real APR if a holding period is supplied. Returns current value, hold value, IL percentage, fee income, net PnL, real APR, and a diagnosis label.

{
  "type": "object",
  "properties": {
    "lp_init_amt": {
      "type": "number",
      "description": "LP token amount held by the position (position size in human units)."
    },
    "entry_x_amt": {
      "type": "number",
      "description": "Amount of token0 originally deposited at position entry."
    },
    "entry_y_amt": {
      "type": "number",
      "description": "Amount of token1 originally deposited at position entry."
    },
    "lwr_tick": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Lower tick of the position (V3 positions only; null for V2)."
    },
    "upr_tick": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Upper tick of the position (V3 positions only; null for V2)."
    },
    "holding_period_days": {
      "type": [
        "number",
        "null"
      ],
      "description": "Optional holding period in days. If supplied, real_apr is annualized from net_pnl."
    },
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to analyze (Uniswap V2/V3 pair, Balancer weighted pool, or Curve stableswap pool). Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "uniswap_v2",
        "uniswap_v3"
      ],
      "description": "Which protocol the pool at pool_address belongs to. This tool accepts uniswap_v2 | uniswap_v3."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Defaults to 1 (Ethereum mainnet) conceptually; omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    }
  },
  "required": [
    "lp_init_amt",
    "entry_x_amt",
    "entry_y_amt",
    "pool_address",
    "rpc_url",
    "pool_type"
  ]
}

Analyze a 2-asset Balancer weighted-pool LP position's PnL. Decomposes impermanent loss using the weighted-pool formula where the base token's weight affects IL magnitude. Values are denominated in opp-token units per BalancerImpLoss's convention; fee income is not attributed in v1 because Balancer pools only expose vault-level fees with no per-LP attribution.

{
  "type": "object",
  "properties": {
    "lp_init_amt": {
      "type": "number",
      "description": "Pool shares held by this position, in human units."
    },
    "entry_base_amt": {
      "type": "number",
      "description": "Amount of base (first) token originally deposited."
    },
    "entry_opp_amt": {
      "type": "number",
      "description": "Amount of opp (second) token originally deposited."
    },
    "holding_period_days": {
      "type": [
        "number",
        "null"
      ],
      "description": "Optional holding period in days. If supplied, real_apr is annualized from net_pnl."
    },
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to analyze (Uniswap V2/V3 pair, Balancer weighted pool, or Curve stableswap pool). Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "balancer"
      ],
      "description": "Which protocol the pool at pool_address belongs to. This tool accepts only balancer (2-asset weighted pool)."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Defaults to 1 (Ethereum mainnet) conceptually; omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    }
  },
  "required": [
    "lp_init_amt",
    "entry_base_amt",
    "entry_opp_amt",
    "pool_address",
    "rpc_url",
    "pool_type"
  ]
}

Analyze a 2-asset Curve-style Stableswap LP position's PnL using the amplified-invariant IL formula where small depegs can produce surprisingly large IL at high A. Values are in peg-numeraire (tokens valued 1:1); fee income is not attributed in v1 (pool-global only); positions whose implied alpha is in the unreachable regime return None on il_percentage, net_pnl, and real_apr.

{
  "type": "object",
  "properties": {
    "lp_init_amt": {
      "type": "number",
      "description": "LP tokens held by this position, in human units."
    },
    "entry_amounts": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "minItems": 2,
      "maxItems": 2,
      "description": "Per-token entry amounts in pool insertion order. Exactly 2 entries (2-asset pools only in v1)."
    },
    "holding_period_days": {
      "type": [
        "number",
        "null"
      ],
      "description": "Optional holding period in days. If supplied, real_apr is annualized from net_pnl."
    },
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to analyze (Uniswap V2/V3 pair, Balancer weighted pool, or Curve stableswap pool). Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "stableswap"
      ],
      "description": "Which protocol the pool at pool_address belongs to. This tool accepts only stableswap (2-asset plain Curve pool)."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Defaults to 1 (Ethereum mainnet) conceptually; omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    }
  },
  "required": [
    "lp_init_amt",
    "entry_amounts",
    "pool_address",
    "rpc_url",
    "pool_type"
  ]
}

Project a Uniswap V2 or V3 LP position's value at a hypothetical price change from the CURRENT pool state (not from entry). A price_change_pct of -0.30 asks 'what if price drops 30% from here'. Returns new value, IL at the simulated price, and percentage change in position value. Fee projection is not modeled (always null).

{
  "type": "object",
  "properties": {
    "price_change_pct": {
      "type": "number",
      "description": "Fractional price change from current price. Must be > -1.0. Example: -0.30 models a 30% drop."
    },
    "position_size_lp": {
      "type": "number",
      "description": "LP tokens held by the position, in human units. Must be > 0."
    },
    "lwr_tick": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Lower tick of the position (V3 only; null for V2)."
    },
    "upr_tick": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Upper tick of the position (V3 only; null for V2)."
    },
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to analyze (Uniswap V2/V3 pair, Balancer weighted pool, or Curve stableswap pool). Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "uniswap_v2",
        "uniswap_v3"
      ],
      "description": "Which protocol the pool at pool_address belongs to. This tool accepts uniswap_v2 | uniswap_v3."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Defaults to 1 (Ethereum mainnet) conceptually; omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    },
    "price_change_pcts": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "maxItems": 256,
      "description": "Optional batch form of 'price_change_pct': an array of values to evaluate in a single call. The pool is read once and the result is an array with one entry per element, in input order. Supply EITHER 'price_change_pct' (single) OR 'price_change_pcts' (batch), not both. Max 256 entries."
    }
  },
  "required": [
    "position_size_lp",
    "pool_address",
    "rpc_url",
    "pool_type"
  ]
}

Project a 2-asset Balancer weighted-pool LP position's value at a hypothetical price change from the CURRENT pool state. The shock is applied to the base-token price in opp units; IL depends on both the shock magnitude and the pool's weights. Returns new value in opp-numeraire, IL at the simulated price, and percentage change.

{
  "type": "object",
  "properties": {
    "price_change_pct": {
      "type": "number",
      "description": "Fractional price change from current spot. Must be > -1.0. Example: -0.30 models a 30% drop in base-in-opp terms."
    },
    "lp_init_amt": {
      "type": "number",
      "description": "Pool shares held by this position, in human units. Must be > 0."
    },
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to analyze (Uniswap V2/V3 pair, Balancer weighted pool, or Curve stableswap pool). Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "balancer"
      ],
      "description": "Which protocol the pool at pool_address belongs to. This tool accepts only balancer (2-asset weighted pool)."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Defaults to 1 (Ethereum mainnet) conceptually; omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    },
    "price_change_pcts": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "maxItems": 256,
      "description": "Optional batch form of 'price_change_pct': an array of values to evaluate in a single call. The pool is read once and the result is an array with one entry per element, in input order. Supply EITHER 'price_change_pct' (single) OR 'price_change_pcts' (batch), not both. Max 256 entries."
    }
  },
  "required": [
    "lp_init_amt",
    "pool_address",
    "rpc_url",
    "pool_type"
  ]
}

Project a 2-asset Curve-style Stableswap LP position's value at a hypothetical depeg from the CURRENT pool state. The shock multiplies the pool's current alpha by (1 + price_change_pct); at high A, large shocks may be physically unreachable and in that case new_value, il_at_new_price, and value_change_pct are returned as null. Values are in peg-numeraire.

{
  "type": "object",
  "properties": {
    "price_change_pct": {
      "type": "number",
      "description": "Fractional shock applied to current alpha. Must be > -1.0. Simulated alpha = current_alpha * (1 + price_change_pct)."
    },
    "lp_init_amt": {
      "type": "number",
      "description": "LP tokens held by this position, in human units. Must be > 0."
    },
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to analyze (Uniswap V2/V3 pair, Balancer weighted pool, or Curve stableswap pool). Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "stableswap"
      ],
      "description": "Which protocol the pool at pool_address belongs to. This tool accepts only stableswap (2-asset plain Curve pool)."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Defaults to 1 (Ethereum mainnet) conceptually; omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    },
    "price_change_pcts": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "maxItems": 256,
      "description": "Optional batch form of 'price_change_pct': an array of values to evaluate in a single call. The pool is read once and the result is an array with one entry per element, in input order. Supply EITHER 'price_change_pct' (single) OR 'price_change_pcts' (batch), not both. Max 256 entries."
    }
  },
  "required": [
    "lp_init_amt",
    "pool_address",
    "rpc_url",
    "pool_type"
  ]
}

Snapshot pool-level health metrics for a Uniswap V2 or V3 pool: TVL in token0 numeraire, reserves, accumulated fees, LP concentration, and swap activity. Answers 'is this a pool I would deposit into?' at the pool level (not position level). num_swaps and fee_accrual_rate_recent are V2-only; V3 returns null for these because V3 has no per-swap history array. A single-block live snapshot also returns null for the LP-concentration and swap metrics (unrecoverable from state alone).

{
  "type": "object",
  "properties": {
    "recent_window": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Rolling window size for fee_accrual_rate_recent, in swap counts. Default 20. V2-only; ignored for V3."
    },
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to analyze (Uniswap V2/V3 pair, Balancer weighted pool, or Curve stableswap pool). Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "uniswap_v2",
        "uniswap_v3"
      ],
      "description": "Which protocol the pool at pool_address belongs to. This tool accepts uniswap_v2 | uniswap_v3."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Defaults to 1 (Ethereum mainnet) conceptually; omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    }
  },
  "required": [
    "pool_address",
    "rpc_url",
    "pool_type"
  ]
}

Detect rug-pull signals on a Uniswap V2 or V3 pool via three threshold checks: suspiciously low TVL, top-LP concentration above a limit, and inactive-pool-with-liquidity. Composes over CheckPoolHealth and returns per-signal booleans plus a count-based risk level (low/medium/high/critical). The inactive-with-liquidity signal is V2-only; V3 pools report False for it with a note in details.

{
  "type": "object",
  "properties": {
    "lp_concentration_threshold": {
      "type": [
        "number",
        "null"
      ],
      "description": "Top-LP share (strict-greater-than) that triggers the concentration signal. In (0, 1]; default 0.90; pass 1.0 to disable."
    },
    "tvl_floor": {
      "type": [
        "number",
        "null"
      ],
      "description": "Minimum acceptable TVL in token0 numeraire. Values at or below fire the tvl_suspiciously_low signal. Default 10.0 is nominal; override for your pair."
    },
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to analyze (Uniswap V2/V3 pair, Balancer weighted pool, or Curve stableswap pool). Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "uniswap_v2",
        "uniswap_v3"
      ],
      "description": "Which protocol the pool at pool_address belongs to. This tool accepts uniswap_v2 | uniswap_v3."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Defaults to 1 (Ethereum mainnet) conceptually; omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    }
  },
  "required": [
    "pool_address",
    "rpc_url",
    "pool_type"
  ]
}

Calculate slippage and price-impact decomposition for a proposed swap on a Uniswap V2 or V3 pool. Returns spot vs execution price, slippage percentage, slippage cost in output-token units, and price impact. Also returns the maximum trade size that stays within 1% slippage for V2 pools; V3 returns null for that field because tick-crossing math has not yet been inverted.

{
  "type": "object",
  "properties": {
    "amount_in": {
      "type": "number",
      "description": "Amount of token_in to trade, in human units. Must be > 0."
    },
    "lwr_tick": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Lower tick of the position (V3 only; null for V2)."
    },
    "upr_tick": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Upper tick of the position (V3 only; null for V2)."
    },
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to analyze (Uniswap V2/V3 pair, Balancer weighted pool, or Curve stableswap pool). Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "uniswap_v2",
        "uniswap_v3"
      ],
      "description": "Which protocol the pool at pool_address belongs to. This tool accepts uniswap_v2 | uniswap_v3."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Defaults to 1 (Ethereum mainnet) conceptually; omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    },
    "token_in_name": {
      "type": "string",
      "description": "Symbol of the input token for the trade (e.g. 'USDC', 'WETH'). Must be one of the two tokens in the pool."
    },
    "amounts_in": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "maxItems": 256,
      "description": "Optional batch form of 'amount_in': an array of values to evaluate in a single call. The pool is read once and the result is an array with one entry per element, in input order. Supply EITHER 'amount_in' (single) OR 'amounts_in' (batch), not both. Max 256 entries."
    }
  },
  "required": [
    "pool_address",
    "rpc_url",
    "pool_type",
    "token_in_name"
  ]
}

Quantify a 2-asset Curve-style Stableswap LP position's exposure to a stablecoin depeg. Computes IL at multiple depeg levels (default 2%, 5%, 10%, 20%, 50%) via the closed-form stableswap-invariant expansion, with an optional V2 constant-product benchmark at each level. Some depeg levels are physically unreachable at high A — unreachable scenarios return null on il_pct, lp_value_at_depeg, and hold_value_at_depeg; the V2 benchmark stays populated.

{
  "type": "object",
  "properties": {
    "lp_init_amt": {
      "type": "number",
      "description": "LP tokens held, in human units. Must be > 0."
    },
    "depeg_levels": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "number"
      },
      "description": "Depeg magnitudes as fractions in (0, 1). Default [0.02, 0.05, 0.10, 0.20, 0.50]."
    },
    "compare_v2": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "If true (default), each scenario reports the equivalent V2 constant-product IL at the same price deviation."
    },
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to analyze (Uniswap V2/V3 pair, Balancer weighted pool, or Curve stableswap pool). Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "stableswap"
      ],
      "description": "Which protocol the pool at pool_address belongs to. This tool accepts only stableswap (2-asset plain Curve pool)."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Defaults to 1 (Ethereum mainnet) conceptually; omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    },
    "depeg_token_name": {
      "type": "string",
      "description": "Optional. Symbol of the asset assumed to depeg (e.g. 'USDC', 'DAI'). Must be one of the two tokens in the pool. If omitted, the pool's first token is used."
    }
  },
  "required": [
    "lp_init_amt",
    "pool_address",
    "rpc_url",
    "pool_type"
  ]
}

Read a pool's on-chain state once and return it as a serialized State Twin (JSON): the protocol-specific snapshot plus a content_hash, in the wire form a client rehydrates locally. Use this to pull a single managed-RPC twin, then run any number of counterfactuals (price moves, IL, slippage) client-side, off this server. Covers Uniswap V2/V3, Balancer 2-asset weighted, and Curve 2-asset plain stableswap pools. The endpoint stores and logs nothing — your rpc_url is never persisted.

{
  "type": "object",
  "properties": {
    "pool_address": {
      "type": "string",
      "description": "On-chain address of the pool/pair to snapshot. Required. Lowercase, uppercase, or checksum casing all work."
    },
    "rpc_url": {
      "type": "string",
      "description": "An Ethereum (or L2) JSON-RPC URL used to read live pool state. Required; supplied by you per call (BYO-RPC) and may carry your provider key. The endpoint stores and logs nothing — the URL is never persisted or written to logs."
    },
    "pool_type": {
      "type": "string",
      "enum": [
        "uniswap_v2",
        "uniswap_v3",
        "balancer",
        "stableswap"
      ],
      "description": "Which protocol the pool at pool_address belongs to: 'uniswap_v2' | 'uniswap_v3' | 'balancer' (2-asset weighted) | 'stableswap' (2-asset plain Curve). All four are supported — this tool spans every snapshot type."
    },
    "chain_id": {
      "type": "integer",
      "description": "Optional guard. If supplied and the RPC reports a different chain id, the call is rejected. Omit to skip the check."
    },
    "block_number": {
      "type": "integer",
      "description": "Optional block number to pin the read to a historical block. Omit to read the latest block."
    },
    "lwr_tick": {
      "type": "integer",
      "description": "uniswap_v3 only — lower tick of the position range to snapshot. Omit for the pool's full active-liquidity range. Ignored for other pool types."
    },
    "upr_tick": {
      "type": "integer",
      "description": "uniswap_v3 only — upper tick of the position range to snapshot. Omit for the pool's full active-liquidity range. Ignored for other pool types."
    }
  },
  "required": [
    "pool_address",
    "rpc_url",
    "pool_type"
  ]
}