• the problem with headline APYs
• what you need
• install
• call the tool
• why each field is computed the way it is
• extending the recipe
• free tier limits
• one common failure mode

a recipe. the goal: when your coding agent asks “what is the actual yield on a curve pool”, it returns the underlying-protocol yield with token-emission components separated, plus an impermanent-loss risk score on the side. not the headline APY a yield aggregator screen shows.

this is what top_yield_farms does inside the falsifylab alpha MCP. it lives on the free tier. 5 results per query, no signup.

§the problem with headline APYs

a yield aggregator UI shows an APY number. that number stacks the underlying protocol yield (lending fees, swap fees) with token emissions (governance token rewards) and sometimes a points multiplier for an upcoming airdrop. all three components are real, but they have different decay curves.

protocol yield is durable. it lasts as long as borrowing demand or swap volume holds. it scales linearly with TVL change.

token emissions are not durable. they are a function of the emissions schedule. when the schedule cuts in half, the headline APY cuts roughly in half too. backtest a yield strategy against an emissions-heavy pool using last week’s headline APY and the math will not survive the next emission cliff.

points multipliers are even less durable. they end on a fixed date when the airdrop ships. anyone holding the position for the yield-without-the-airdrop after that date is holding a worse position than the screen advertised.

filtering matters. an MCP tool that returns the headline APY is the same data your agent could screen-scrape from a dashboard. an MCP tool that returns the components separately is a different surface.

§what you need

• an MCP-compatible coding agent (any client that supports the protocol)

• python 3.10+

• 5 minutes

§install

pip install falsifylab-alpha-mcp==0.3.2add this to your agent’s MCP config. config path varies by client; the shape is the same:

{ "mcpServers": { "falsifylab-alpha": { "command": "python", "args": ["-m", "falsifylab_alpha_mcp"] } } }restart your client. the MCP loads. no key needed for free tier.

§call the tool

in your coding agent, type a question:

show me the top stablecoin pools right now with the actual protocol yield, separate from emissions, only USD-pegged assets, on chains with more than 10b TVL

the agent calls top_yield_farms with the right filters. a free-tier response returns up to 5 results.

example shape:

{ "pools": [ { "protocol": "curve", "pool": "3pool", "chain": "ethereum", "tvl_usd": 81200000, "apy_protocol": 0.041, "apy_emissions": 0.027, "apy_total_displayed": 0.068, "il_risk_score": "low", "assets": ["USDC", "DAI", "USDT"] } ], "as_of": "2026-05-22T20:00:00Z", "tier": "free" }the protocol yield and emissions yield are returned as separate fields. an agent comparing two pools can rank by apy_protocol for durability and use apy_emissions as a separate dimension. the IL risk score is a categorical bucket (low / medium / high) derived from the asset pair and the historical price spread.

§why each field is computed the way it is

apy_protocol is computed from on-chain trade volume or borrow volume against TVL over a 30-day rolling window. it is not pulled from the protocol’s own reported APY because protocols sometimes annualize a 1-day or 7-day window which gives a biased reading on quiet weeks.

apy_emissions is the dollar value of governance token rewards distributed to the pool over the 30-day window, divided by average TVL, annualized. token price uses a time-weighted average price over the same window so a one-off pump does not skew the result.

il_risk_score is bucketed: stablecoin-only pools at the same peg are low, correlated-stable pairs (e.g. stETH-ETH) are low-medium, uncorrelated pairs are medium or high depending on the historical spread distribution. it is not a precise IL number. the categorical version is more useful inside an agent loop than a single percentage.

§extending the recipe

once the tool is live, your agent can combine it with:

• active_airdrop_farms (free tier) returns DefiLlama yield gaps that correlate with active airdrop campaigns. pair an emissions-heavy pool with an active airdrop flag and you have a more honest picture of why the headline yield is high.

• confluence_today (Pro $19/mo) stacks signals across sources. a yield position that also shows up on a polymarket whale move or an on-chain smart-wallet rotation is a different posture than a yield position alone.

• hl_vault_leaderboard (free) ranks Hyperliquid vaults by NAV, 30d return, max drawdown, follower count. the comparison surface for off-chain venues against on-chain yield is useful when your agent is choosing between deploying capital to a DEX pool vs a perp vault.

§free tier limits

• 5 results per query

• 60 requests per hour

• 24h cache lag

the 24h cache lag is the main free-tier cost for yield work specifically. emissions schedules and TVL change daily; a stale snapshot can hide a cliff. for research workflows where the answer is “what was true yesterday” the free tier is enough. for an agent loop that decides position-size live, the Pro plan 5-minute refresh is the minimum.

§one common failure mode

agents that rank pools strictly by apy_total_displayed will overweight emissions-heavy positions. the fix is to rank by apy_protocol first and use apy_emissions as a tie-breaker with a confidence discount tied to days-until-next-emission-cut. that ordering matches what survives across the emission cycle.

pip install falsifylab-alpha-mcp==0.3.2falsifylab.com/pro

research and educational content only. not investment, legal, or tax advice. do your own research.

#OnchainAlpha #DeFiYield #StablecoinYield

Originally published on FalsifyLab Substack.