poollens-mcp
README.md
# poollens-mcp
MCP server for the BABA Labs PoolLens API. It gives an AI agent three tools for
concentrated-liquidity pools and LP positions on Base (Aerodrome Slipstream,
Uniswap v3-style) and HyperEVM. Every answer is read from chain in one call at
one block and carries a `proof`: the block number and the exact `eth_call` that
reproduces it. Data only: no advice, no signals, no custody.
| Tool | What it answers | Cost |
|---|---|---|
| `get_pool` | Tokens, fee, tick, price, liquidity, staked liquidity, gauge | Free |
| `get_position` | One position: in range or not, distance to each edge, amounts, uncollected fees | 0.005 USDC |
| `list_positions` | All unstaked positions of an address (20 per call) and how many are out of range | 0.005 USDC |
`get_pool` is free. `get_position` and `list_positions` cost 0.005 USDC per call,
paid with x402 in USDC on Base at `https://x402.babacapital.app/lens`. No account
and no API key.
## Install and run
Node 20 or newer. No install step is needed with npx:
npx -y github:babaanalytix-commits/poollens-mcp
MCP client config (Claude Desktop, Cursor, and others that take this shape):
{
"mcpServers": {
"poollens": {
"command": "npx",
"args": ["-y", "github:babaanalytix-commits/poollens-mcp"],
"env": { "POOLLENS_PRIVATE_KEY": "0x..." }
}
}
}
Leave out `env` to use the free tool only; the paid tools then return the
payment offer instead of data.
From a clone:
npm install
npm test # no money is spent; OFFLINE=1 skips the live checks
node src/server.js
## Paying
Without `POOLLENS_PRIVATE_KEY` the paid tools return the x402 offer (price,
asset, payTo, URL) instead of data, so an agent that already has an x402 wallet
tool can pay the URL itself.
With `POOLLENS_PRIVATE_KEY` the server pays for you. Use a small dedicated
wallet holding a little USDC on Base; no ETH is needed (the facilitator pays
gas). Before it signs anything the server checks the offer and refuses unless
all of these hold:
- scheme `exact`, network Base (`eip155:8453`), asset USDC `0x8335...2913`
- payTo is the PoolLens address `0x6C831dc0abc1aAbd9491969f72832C949b620D71`
- the price is at or below the per-call cap
- the session budget is not used up
The payee is pinned in the code. One payment per call, capped per call and per
session. A failed paid call is reported and never retried. The key is read from
the environment variable only and is never logged or written to disk.
| Variable | Default | Meaning |
|---|---|---|
| `POOLLENS_PRIVATE_KEY` | none | Payer wallet key. Read from the environment only; never logged. |
| `POOLLENS_MAX_USDC_PER_CALL` | `0.005` | Highest price the server will sign for one call |
| `POOLLENS_SESSION_BUDGET_USDC` | `0.25` | Total the server will sign until it is restarted |
| `POOLLENS_PAYTO` | pinned address | Only change if PoolLens announces a new payTo |
| `POOLLENS_PAID_URL` | `https://x402.babacapital.app/lens` | Paid route |
| `POOLLENS_FREE_URL` | `https://labs.babacapital.app` | Free pool sample |
## Answers
Tools return the API JSON unchanged (`data`, `proof`), plus `payment` on paid
calls (price, payer, transaction hash, session spend) and `warnings` when the
proof block was not honoured, a decimals read came back empty, or an item has
a status other than `OK`. `NO_DATA` means a read failed; it is never a zero.
## Check a payment
`paid-test/` makes one real paid `get_position` call and then checks the USDC
transfer on Base. `node paid-test/verify.mjs <txHash> <payerAddress>` checks any
payment without a key.
## License
MIT, see `LICENSE`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data