Back to Browse

Ekubo MCP Server

Developer ToolsLow Risk8.2MCP RegistryRemote
Free

Server data from the Official MCP Registry

Token and pool data, swap quotes, and unsigned transaction plans for Ekubo and other DeFi protocols.

About

Token and pool data, swap quotes, and unsigned transaction plans for Ekubo and other DeFi protocols.

Remote endpoints: streamable-http: https://mcp.ekubo.org/mcp

Security Report

8.2
Low Risk8.2Low Risk

The Ekubo MCP server is a Cloudflare Workers-hosted, public, stateless server that prepares unsigned DeFi transaction calldata across Ekubo, Uniswap, Aave, Morpho, Lido, and other protocols, with no signing keys evident in the reviewed code. The reviewed portions (catalog compaction, schema definitions, input validation via zod) show careful input validation and no shell execution, hardcoded secrets, or exfiltration; the truncated files prevent a full review of network calls and dependencies. Public unauthenticated access is by design for read tools, but write-capable tools only return unsigned calldata, so the main residual risk is the unreviewed remainder of the codebase.

4 files analyzed · 4 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Found in Source Code

Found by scanning the linked source code. This listing connects to a hosted endpoint, so none of this runs on your machine: it describes what the server software does where it is hosted.

HTTP Network Access

Connects to external APIs or services over the internet.

database

Applies to the server that hosts this plugin, not to your machine.

How to Connect

Remote Plugin

No local installation needed. Your AI client connects to the remote endpoint directly.

Add this to your MCP configuration to connect:

{
  "mcpServers": {
    "io-github-ekuboprotocol-ekubo": {
      "url": "https://mcp.ekubo.org/mcp"
    }
  }
}

Documentation

View on GitHub

From the project's GitHub README.

Ekubo MCP server

The official agent interface for Ekubo Protocol transactions. This repository deploys a stateless, public MCP server on Cloudflare Workers. It discovers tokens, compares Ekubo and 0x liquidity for same-chain EVM swaps, prepares and tracks Across, LayerZero, and LI.FI any-to-any bridges, and constructs unsigned VeToken calls for ve(3,3) vote and fee workflows. It also publishes provider-neutral STONX allocation recommendations resolved to initialized Robinhood Ve33 pools, enumerates indexed LP positions by owner, reproduces the interface's indexed/API/USD/RPC position-data pipeline, discovers pair-level position candidates, prepares unsigned LP deposits, withdrawals, and earnings claims, and exposes exact pool state and liquidity data. It prepares interface-equivalent TokenDataFetcher reads across each chain's canonical token list for wallet balances and selected contract allowances. It also publishes the same ranked boosted-fee, incentive, and ve(3,3)-emission liquidity opportunities shown by the interface. It additionally exposes fixed, locally maintained Aave V3, Morpho Vault V2, Sky Savings, Lido, Merkl, and Aerodrome deployments with signer-neutral action plans, prepares proof-verified Merkl reward claims for campaigns on any protocol, and prepares Aerodrome v2 liquidity, gauge, veAERO lock, vote, and reward-claim actions on Base alongside the Sugar lens reads that feed them. Agents discover live protocol data from official public APIs or the user's wallet/RPC directly for those protocols. Uniswap V2/V3/V4 support additionally fetches indexed pool discovery, price/volume charts, and liquidity-depth ticks from the official Uniswap interface API, and prepares pool/position reads and liquidity transactions on six EVM chains. See Uniswap coverage.

The MCP server owns agent-facing transaction construction. prod-api remains a data API and the quoter remains a route-data service.

Public endpoints

  • POST/GET /mcp — MCP Streamable HTTP endpoint serving bundled protocols (excludes Safe)
  • POST/GET /mcp/{ekubo,aave,aerodrome,lido,merkl,morpho,sky,uniswap} — the same MCP contract narrowed to one protocol
  • POST/GET /mcp/ekubo-advanced — Ekubo's operator tools, kept off /mcp/ekubo (see below)
  • POST/GET /mcp?protocols=<slug>+<slug> — one connection serving the named protocols (any of the above except Safe); see below
  • POST/GET /mcp/safe — dedicated Safe signer preparation; see Safe coverage
  • GET / — service metadata, per-protocol endpoints, and canonical documentation links
  • GET /tools — deterministic tool catalog for non-MCP discovery, filterable with ?protocol=<slug> or ?protocols=<slug>+<slug>; catalog_digest changes whenever that endpoint's tools or instructions do (not its resources)
  • GET /openapi.json — OpenAPI 3.1 discovery contract
  • GET /llms.txt — concise agent workflow
  • GET /skills/{use-morpho,use-sky,use-lido,use-merkl,use-aerodrome}/SKILL.md — reusable direct-data agent instructions, with each skill's discovery reference beneath references/discovery.md

One endpoint per protocol

src/protocols.ts partitions the catalog: every tool belongs to exactly one protocol, /mcp/<slug> registers that protocol's tools and its own skill resources, and /mcp registers the bundled protocols only. Safe is explicitly excluded from that bundle. The partition is checked against hostedToolCatalog in test/protocols.test.ts, so a tool added to the catalog without a protocol fails the build rather than quietly appearing on no per-protocol endpoint.

/mcp remains the endpoint for the bundled catalog. Safe clients must add /mcp/safe.

Ekubo itself is split in two. /mcp/ekubo carries the core tools most sessions use: tokens, quotes and swaps, pools, LP positions and deposits, withdrawals and claims, liquidity opportunities, transfers, wrap/unwrap, rewards, and ve(3,3)/STONX. /mcp/ekubo-advanced carries the rarely used operator tools: auctions, TWAMM orders, pool initialization and price fixes, oracle capacity, manual boosts, revenue buybacks, approval revocations, and pool-key enumeration and derivation. Each one's instructions name the other, so an agent that needs a tool from the other half tells the user which server to add. /mcp serves both halves. /tools?protocol=safe publishes the Safe catalog; unfiltered /tools describes /mcp.

Combined endpoints

/mcp?protocols=ekubo+ekubo-advanced serves the union of the named protocols' tools and resources on one connection. The shared paragraphs (catalog revision, scope, jurisdiction notice, handoff) are stated once rather than once per connection, and an endpoint-scope paragraph names the protocols served. Slugs may be separated by +, , or repeated parameters and appear in any order, but facetMcpUrl() writes them in PROTOCOL_SLUGS order: a client or MCP gateway treats every distinct URL as a separate server with its own cached catalog, so one selection should have one URL. A facet naming every bundled protocol is /mcp, and one naming a single protocol is /mcp/<slug>. An unknown slug, an empty list or safe gets HTTP 400 before any MCP handling; Safe stays standalone.

Filtering happens at the two registration choke points in createEkuboServer rather than at the call sites, and the instructions are composed from protocol-scoped paragraphs, so a single-protocol server never tells an agent to call a tool it does not serve.

/ and /llms.txt link the two public documentation pages: the server and protocol coverage and the wallet producer contract. The latter is where a third party building its own wallet-compatible MCP server is sent, so keep it in sync when the protocol list or the handoff contract mirrored in src/wallet-compatibility.ts changes.

MCP-native discovery remains authoritative: clients use tools/list and resources/list/resources/templates/list. The HTTP discovery endpoints are additive and help crawlers, OpenAPI clients, and humans find the same capabilities. GET /tools is deliberately uncached and includes both the server version and a tool-catalog revision so integrations can detect stale schemas after a Git-triggered deployment.

MCP 2026-07-28 clients can use server/discover and standalone requests without an initialization handshake. Browser preflights allow Mcp-Method and Mcp-Name alongside the protocol-version header. Discovery and catalogs carry a five-minute public cache hint; bundled documentation and ABI resource reads carry a one-hour hint. Cache entries belong to the exact endpoint and resource URI (the protocol-specific endpoints have different catalogs). The externally fetched API OpenAPI document remains uncached. HTTP RPC envelopes remain no-store: clients cache MCP result payloads, not another request's ID. Legacy clients retain their existing result shapes. All tools publish output schemas; informational schemas describe stable envelopes while preserving additional upstream fields.

Tools

  • list_tokens — list the canonical token list, ordered by descending visibility_priority, with optional symbol search, chain_id, min_visibility_priority, page_size, and after_token filters
  • export_tokens — hand a wallet the canonical list without reading it: returns only a token_list_reference envelope and a count, never entries. Scoped by chain_id, capped by max_tokens (default 1,000, the wallet's per-import limit), fixed at the interface's visibility threshold, and stored with only the five fields a wallet acts on
  • get_token — fetch token metadata by chain and address
  • get_tokens — fetch metadata for 1–1,000 exact token identifiers, across chains, through one prod-api batch request
  • get_quotes_with_plans — compare Ekubo and 0x for same-chain exact-input or exact-output swaps, or compare Across, LayerZero, and LI.FI when destination_chain_id differs, and return each option's firm unsigned approval and execution calldata alongside its quote; an Ekubo or 0x failure marks the comparison incomplete and tells the user to retry
  • get_value_transfer_status — track an executed LayerZero or LI.FI cross-chain transfer from origin submission to destination delivery, by the provider_quote_id its quote carried for LayerZero and by the origin transaction hash for LI.FI; a bridge is the one plan whose successful origin receipt does not mean the user has their funds
  • prepare_ve33_vote — compile one active NFT's vote changes and deterministic splits into one multicall that always claims its current pool first; prefer the portfolio workflow below for complete state validation
  • prepare_ve33_extend — extend an unvoted token directly, or provide its active pool key to claim pending voter fees atomically before extension
  • prepare_ve33_stake — create a new VeToken with an exact token approval; max duration is the default when no duration is supplied
  • prepare_ve33_split — construct a split and predict the child token ID
  • prepare_ve33_claim_fees — claim one or many VeToken voter-fee balances
  • prepare_ve33_reinvest — automatically discover and claim all active fees, construct one exact-input swap per claimed non-stake token, and increase one VeToken or every existing active allocation
  • prepare_ve33_claim_all_fees — discover every active vote owned by a sender and prepare one native VeToken claim multicall, including ownerOf and voteState validation calldata
  • prepare_ve33_clear_vote — remove the active vote from one or more VeTokens, claiming each stake's current pool immediately before its clearVote in one atomic batch. current_pool_key is required per stake: Ve33 discards pending voter fees when a stake's weight goes to zero, and a key that is not that stake's active pool reverts the batch before anything clears. The stake, its lock end, and its ownership are unchanged; the pool loses that weight, and a pool with no vote weight charges a zero extension fee
  • get_ve33_allocations — handle “show all my Ekubo STONX allocations” with only the connected wallet address because the production Ve33 deployment is the STONX voting system; defaults to Robinhood Chain 4663 and its canonical VeToken, then returns the complete portfolio and onchain_validation request, explicitly marked not_executed until its eth_call is run. An explicit chain and VeToken pair remains available for another deployment such as testnet.
  • get_stonx_allocation_recommendation — return the current provider-neutral recommendation plus an exact 10,000-bps executable target list capped at 25 initialized canonical Ve33 pools. Snapshots older than one day trigger a refresh that is awaited for up to 20 seconds; stale, failed, or timed-out refreshes fail closed instead of returning an executable plan. Each recommendation reports an emissions_efficiency KPI: emissions per dollar of voter fees the pool still generates one epoch (7 days) later, plus the rate-free emission_share_per_retained_fee_share; pools above the threshold (default 3) or with votes but no retained fees are prune candidates, and prune_low_efficiency=true withholds them. Passing voter (vote weight and LP share per pool) with the locally decoded ve33_emission_state returns voter-optimal targets that also value the emissions redirected to the voter's own pools (Mazett 2024), with the neutral plan kept as provider_targets. The 25-target, 10,000-bps contract is unchanged
  • prepare_ve33_reallocation — resolve target pool_key_id values and compile up to 25 basis-point targets into one fee-preserving atomic VeToken multicall. preserve_existing_locks apportions each expiry cohort across every target; compact_max_lock consolidates and extends stake before creating exactly one voting NFT per target.
  • get_positions_by_owner — enumerate indexed position NFTs with their pool keys, bounds, liquidity, current pool state, rewards, pagination, canonical token USD metadata, and exact pending position-state eth_call
  • get_position — hydrate one owner position with NFT metadata, history, campaigns, earned rewards, token USD prices, and an atomic Multicall3 query for current principal, fees or Ve33 rewards, and ownership
  • get_position_pool_candidates — list existing pools for a pair with verified exact PoolKeys, v2/v3 Core generation, extension classification, token prices, pool statistics, and the correct position manager
  • get_liquidity_opportunities — rank the interface's current boosted-fee, active-incentive, and projected STONX-emission opportunities; returns canonical tokens, exact actionable pools or a pair-level candidate lookup, APR components and denominators, freshness, and risk context. The Ve33 emission input is read and decoded by the user's wallet, then passed back for the final interface-equivalent ranking. Starknet incentives remain visible but are marked discovery-only because the current pool-candidate and deposit preparation tools are EVM-specific.
  • prepare_lp_position_deposit — prepare a new v3 position mint or add liquidity, including exact PoolKey derivation and maybeInitializePool for a new pool atomically before the deployed mintAndDeposit call in one multicall, shared-SDK liquidity math, a nonzero slippage floor, exact approvals/refunds/cleanup, decoded intent, wallet-policy requirements, and a signer-neutral execution plan; no Cast encoding is required
  • prepare_pool_initialization — prepare a standalone, idempotent maybeInitializePool transaction for an exact v3 PoolKey and initial tick when initialization should not be bundled with the first position mint
  • prepare_lp_position_earnings_claim — resolve an owned position and prepare collection of standard LP fees or Ve33 LP rewards without removing liquidity or touching the NFT, including pending ownership/earnings reads, decoded calldata, wallet-policy requirements, and a wallet execution plan
  • prepare_lp_position_withdraw — prepare a partial or full position withdrawal from an exact liquidity amount, or pass up to 100 withdrawals for one atomic wallet-batch-capable plan; each withdrawal automatically collects ordinary fees or Ve33 rewards and includes its own pending validation
  • get_pool — resolve an exact chain/core/pool ID to a verified PoolKey, decoded config, the latest indexed state snapshot, and a current_state_query read bundle whose read_calls_reference the wallet executes for fresh on-chain sqrtRatio, tick, and liquidity
  • get_pool_liquidity — return tick-level net liquidity deltas for one exact pool
  • list_pool_keys — enumerate a Core deployment's initialized pools with keyset pagination (after_pool_id, ascending pool_id) and token/pair/extension filters; every pool_id is re-derived locally from its PoolKey before it is reported
  • derive_pool_id — pack a PoolKey and derive its exact Keccak pool ID
  • decode_pool_config — decode the extension, exact uint64 Q64 fee, v3 discriminator, and concentrated, stableswap or full-range parameters. Returns { "decoded_config": { ... } }, matching derive_pool_id's decoded_config; fee is a decimal string and fee_hex is exact uint64 hex.

Aave V3

  • get_aave_v3_markets — return a local, versioned catalog of fixed Aave V3 Pools and major reserves on Ethereum, Base, Arbitrum, Optimism, Polygon, and Avalanche
  • prepare_aave_v3_supply, prepare_aave_v3_withdraw, prepare_aave_v3_borrow, and prepare_aave_v3_repay — prepare complete signer-neutral Pool calls, including temporary exact ERC-20 approvals and allowance cleanup where needed
  • prepare_aave_v3_collateral and prepare_aave_v3_emode — prepare collateral-toggle and eMode-category calls against a fixed Pool

The agent—not this MCP—queries Aave's public GraphQL endpoint at https://api.v3.aave.com/graphql for live market/user data. API results select explicit fixed identifiers for the preparation tools; wallet simulation remains authoritative.

Morpho Vault V2

  • get_morpho_vaults returns a local, pinned catalog and direct-discovery guidance.
  • prepare_morpho_vault_deposit uses the official Morpho SDK's guarded VaultBundlesV1 route with a caller-supplied fresh max_share_price_ray, exact asset approval, and atomic cleanup. Shares are minted to the sender only.
  • prepare_morpho_vault_withdraw and prepare_morpho_vault_redeem construct direct fixed-vault exits.

Read ekubo://skills/use-morpho. The agent queries https://api.morpho.org/graphql itself, then uses fresh wallet/RPC state and the official SDK to derive the share-price bound. The server never proxies the API or RPC.

Sky Savings

  • get_sky_savings_deployment returns fixed Ethereum USDS/sUSDS addresses.
  • prepare_sky_savings_deposit, prepare_sky_savings_withdraw, and prepare_sky_savings_redeem construct canonical ERC-4626 calls.

Read ekubo://skills/use-sky. Current previews, conversions, limits, balances, and allowances come directly from the user's wallet/RPC. The direct ERC-4626 methods have no deadline or minimum-output argument, so fresh preview and exact wallet simulation are required.

Lido

  • get_lido_deployment returns fixed Ethereum stETH, wstETH, and withdrawal queue addresses.
  • prepare_lido_stake, prepare_lido_wrap, and prepare_lido_unwrap build liquid-staking and token-conversion plans.
  • prepare_lido_withdrawal_request creates bounded asynchronous unstETH NFT requests; prepare_lido_withdrawal_claim claims one finalized request.

Read ekubo://skills/use-lido. Pause/limit, conversion, balance, ownership, queue, and finalization state is read directly through the user's wallet/RPC. Withdrawal requests are irreversible, stop rewards while queued, and may settle below 1:1 after extraordinary protocol losses.

Merkl

  • get_merkl_deployment returns the reward Distributor address and the chains it was verified on.
  • prepare_merkl_claim builds one claim() covering every reward token the sender holds on a chain.

Read ekubo://skills/use-merkl. Amounts and Merkle proofs come from https://api.merkl.xyz/v4/users/{address}/rewards/summary, which the agent queries directly — it is public and needs no key.

This is the one preparation whose inputs arrive from an outside API and still need not be trusted. Every proof is folded here into the root it implies, a batch spanning two roots is refused, and the returned read bundle asks the wallet for the root the chain is enforcing. A mismatch means the tree rotated or is inside its dispute period, so the plan simply fails simulation instead of being signed. The Distributor is pinned per chain rather than assumed: ZKsync Era has no code at the address the other chains share.

Merkl's amount is cumulative and the contract transfers it minus what was already claimed, so the claimable figure is amount - claimed; its pending field is not claimable at all. prepare_merkl_claim covers Merkl campaigns on any protocol, while prepare_rewards_claim covers Ekubo's own incentive drops.

Aerodrome

  • get_aerodrome_deployment returns the Base contracts and the protocol behaviour that decides what an action can do.
  • prepare_aerodrome_sugar_reads builds the eth_call bundle for one Sugar dataset: pools, an account's positions, veNFTs, epochs, or a veNFT's claimable rewards.
  • prepare_aerodrome_liquidity_deposit / _withdraw — v2 add and remove through the Router, with per-side approvals and allowance cleanup.
  • prepare_aerodrome_gauge_deposit / _withdraw / _claim — stake, unstake, and collect AERO emissions.
  • prepare_aerodrome_lock — create, add to, extend, permanently lock, unlock, or withdraw a veAERO position.
  • prepare_aerodrome_vote — cast or reset one veNFT's gauge vote.
  • prepare_aerodrome_incentive_claim — a voter's fees, bribes, and rebase.

Read ekubo://skills/use-aerodrome. Aerodrome is Base-only and publishes no data API: the Sugar lens contracts are its data pipeline and answer eth_call, so discovery is a read against the user's own RPC and the no-proxy boundary costs nothing. Each prepared read ships a decode plan matching the deployed struct layout.

Every address was derived on chain from the Voter outward rather than copied from Velodrome's SDKs, which is not pedantry: sdk.js publishes Optimism addresses, and its Position struct has drifted from the deployed Base lens by two fields, so decoding a live response with it silently misreads everything after sqrt_ratio_upper instead of failing.

The fee and bribe contracts a claim needs are per pool and come only from a Sugar rewards read; a claim naming the wrong one succeeds and transfers nothing, so a green simulation is not by itself evidence the inputs were right. Swaps are deliberately absent — get_quotes_with_plans remains the single swap path — and Slipstream positions are readable but not yet mintable here.

The remaining EVM interface transaction paths also have first-class tools:

  • prepare_transfers — prepare 1–4,096 ordered native, ERC-20, ERC-721, and ERC-1155 transfers on one chain; kinds may be mixed in one atomic batch;
  • wrap/unwrap and LP NFT transfer;
  • standalone pool initialization and phased pool price correction, including exact reads, quote, approval, and execution route;
  • TWAMM/DCA creation, collection, stop, and virtual-order execution;
  • auction creation, completion/graduation initialization, and creator proceeds;
  • manual boosts, oracle capacity, and ERC-20 revocations;
  • incentive rewards, Recovery Fund claims, and revenue buyback maintenance;
  • VeToken increase-stake, fee-safe merge, and expired withdrawal.

Each prepare_* result supplies the exact ordered transaction list. The wallet validates, signs, and submits it; it does not encode calls, select overloads, build multicalls, append approvals, or determine ordering.

Resources

  • ekubo://skills/use-morpho, ekubo://skills/use-sky, ekubo://skills/use-lido, ekubo://skills/use-merkl, and ekubo://skills/use-aerodrome — reusable no-proxy protocol workflows, with a references/discovery.md child resource for official endpoints and reads
  • ekubo://docs/lp-position-workflow — interface-equivalent indexed/API/USD/ RPC joins, atomic TWAMM/Ve33 read semantics, decoding, and APR inputs
  • ekubo://contracts/evm — supported chain IDs and contract-resource links
  • ekubo://contracts/evm/{chain_id} — address-to-contract map for one chain
  • ekubo://contracts/evm/{chain_id}/{address} — the exact deployment metadata and, when present in the current contracts checkout, ABI for one contract

Contract resources provide provenance and read-only ABI context. Transaction calldata and complete transaction lists come from first-class preparation tools, not from a wallet, agent, or ad hoc cast encoding. The client must still verify deployed code and permissions and simulate the exact calldata before requesting a signature. VeToken address resources include function-level warnings for operations that fully clear a vote, the fee-preserving compound alternatives, and the stake-orphaning risk of burn. Ownership handovers, ERC721 approvals and transfers, safe transfers, and burns are explicitly outside every safe MCP workflow even though the complete ABI resource describes them.

The checked-in snapshot merges the latest ../evm-contracts GitHub release deployment tables with all non-dry-run Foundry broadcasts and current artifacts. Contracts deployed without a Foundry broadcast, by replaying the CREATE2 input of an existing broadcast, are listed with their transaction in script/evm-contracts-direct-deployments.json. Every contract resource includes the source release, source commit, nearest tag, snapshot worktree state, and per-ABI hash. A release or broadcast address remains discoverable when a legacy contract no longer has an artifact in the current checkout; its address resource explicitly marks the ABI as unavailable. The Yul router address and public quote ABI come from @ekubo/yul-router-sdk, so the MCP server follows the SDK version it ships. Refresh the contract snapshot after contract deployments or ABI changes with bun run contracts:generate from this repository.

get_quotes_with_plans has no provider-selection input and does not select a quote. Same-chain requests return every Ekubo and 0x option in quotes with its source URL and normalized amounts, so the agent or user can choose. Supply sender and slippage_bps together and each option also carries the execution_plan_reference that executes it, so a chosen plan goes straight to a wallet with no second round trip and the compared quote is the executed one. Unless the user specifies a tolerance, choose slippage_bps so the maximum value exposed to slippage is approximately one estimated gas fee (10_000 * gas cost / swap notional, with both values in the same currency), not a generic 50 bps/0.5%. Prefer re-quoting and preparing new calldata after a slippage failure to widening that bound; never resubmit reverted calldata unchanged. Omit both for an indicative comparison, and set include_raw_quotes to add the untouched provider responses, which are otherwise left out as the largest and least useful part of a response. If a configured provider fails, the response reports it in unavailable_sources without invalidating successful quote options, and an option that could not be made executable reports its own execution_unavailable while the rest stand. Cross-chain requests are quoted by Across, by LayerZero's Value Transfer API, and by LI.FI, each included where its credentials are configured, and are compared the same way as same-chain options. LayerZero prices an exact source amount only, so an exact-output bridge request reports unsupported_quote_type for it and is served by Across and LI.FI. After executing a LayerZero or LI.FI option, poll get_value_transfer_status with that option's source until settled is true — LayerZero by the quote's provider_quote_id, LI.FI by the origin transaction hash. Token arguments accept raw EVM addresses or eip155:<chain_id>:<address> identifiers. The output token's EIP-155 chain must match destination_chain_id.

Some integrations do not cover every chain Ekubo is deployed on, and src/chain-support.ts records the known gaps so a tool states them instead of relaying a provider error. On Elysium (99901) the core protocol, API, quoter and Yul swap router are live, so Ekubo quotes there carry swap plans. Across does not support Elysium and reports unsupported_chain without an upstream call. 0x does cover Elysium, so a same-chain quote there asks both the Ekubo quoter and 0x. Cloud Wallet does not support it: a result whose plans or read bundles target Elysium carries a root wallet_support notice, and the references themselves stay valid for any other wallet that implements the same handoff. An Ekubo insufficient_liquidity answer is definitive and is reported with retry_recommended: false. So is a 0x INPUT_INVALID rejection, which is reported as invalid_request with 0x's field reason; for example, 0x refuses any taker at or below 0x000000000000000000000000000000000000ffff, such as 0x…dEaD, on every chain.

The catalog explicitly contains read tools and unsigned preparation tools. All server operations are non-custodial and idempotent: the Worker has no wallet, key material, signing function, or broadcast function. Preparation tools return an exact unsigned transaction plan for the agent to pass to the user's wallet. The agent does not ask for a separate confirmation first: wallet tooling is responsible for current-state simulation, presenting the simulated result, collecting authorization or signature, signing, and submission.

Prepared execution plan bodies, read-call bundles — exact wallet_batch_eth_call argument objects, validated against the wallet boundary before storage — and token lists exported by export_tokens are stored in R2 — strongly consistent, so a fresh reference never 404s from replication lag — and served at /artifact/<id> so wallets fetch them by reference. All three travel as artifact_reference envelopes (under execution_plan_reference, read_calls_reference, and token_list_reference) whose integrity.value keccak256 and bytes count bind the exact stored bytes; the agent passes the envelope unchanged as the wallet tool's reference argument — as a value carried in a variable from the producer result (const ref = r.current_state_reads[0].read_calls_reference), in the same code block when the harness runs tool calls as code, never retyped from url/bytes/integrity shown in an earlier turn, which is the observed way smaller models end up with a parse, digest or 404 failure. A read bundle's call ids (state_call_id on a position) come back as results[].id from the wallet, which is the join key from result to row. No other tool result is stored or replayed, and /mcp responses use Cache-Control: no-store. No fixed request quota is guaranteed; clients must honor HTTP 429 and the Retry-After header it carries. Owner positions use upstream no-cache semantics. Indexed pool-state snapshots may be cached upstream for 180 seconds, while PoolKeys and tick-liquidity data may be cached for 1,800 seconds. Polling more frequently than those freshness windows does not produce fresher pool data.

The token-list reference exists because a list is the largest thing an agent is ever asked to carry between two servers, and the cost is not in fetching it but in re-emitting it. The canonical list is 483 KB: about 146,000 tokens of context to read, and roughly 49,000 output tokens — minutes of generation — to write back out as a wallet's propose_tokens arguments.

export_tokens is the tool for that trip, and it is a separate tool rather than a flag on list_tokens because it does a different job. Listing answers a question the model reasons about — which address is the USDC the user meant — so it returns entries and offers search, paging, and full metadata to serve that. Exporting answers no question: it hands a wallet a list to hold. So it returns a token_list_reference and a count and nothing else, its stored body carries only the five fields a wallet acts on, and its whole input surface is which chain and how many at most.

Scope an export by chain, but do not assume that fits it under a consumer's limit. At the interface visibility threshold Ethereum carries roughly 5,600 tokens, BNB Chain 3,600, Base 2,600, and Arbitrum and Polygon about 1,000 each, against the 1,000 entries a wallet accepts in a single import. An export past the importer's limit is refused whole rather than truncated, so a larger max_tokens is not a safer one.

Every export therefore reports complete. False means more tokens exist at that visibility than max_tokens allowed, and the stored list is a prefix rather than the chain's list — a distinction nothing downstream could otherwise draw, because the agent never sees an entry to miss.

Position-state plans use one Multicall3 eth_call at pending. TWAMM virtual orders or Ve33 reward accumulation, when required, are simulated immediately before the position read in that same call. Splitting them into separate calls would discard the simulated state; the aggregate payload is read-only workflow data and must never be broadcast. Each query carries a complete declarative Multicall3 and child-result decode plan for local wallet execution. The wallet returns raw bytes by default, decodes them on the user's device, and never installs or executes codec code named by the remote plan.

Decode plans distinguish Solidity ABI decoding from protocol semantics. Standard results use function_result; atomic position queries use multicall3 with an ABI and required child-result specification, or function_result_bytes_array for a function returning nested bytes[]. A semantic codec attached to an ABI output preserves the ABI-decoded value and adds the interpreted value. A custom payload with no ABI envelope may instead use semantic_value, which consumes the raw return bytes while the wallet retains those bytes in the result. Codec IDs are platform-neutral. Implementations explicitly identify their ecosystem; for example, Ekubo's compact SqrtRatio codec names the pinned npm package URL, export, version, and integrity for @ekubo/sdk. Wallets must run only a locally installed, allowlisted implementation and must never fetch or execute code from a decode plan.

For a new LP position, start with get_position_pool_candidates; do not browse prod-api or infer a manager from an ABI resource. Its default min_tvl_usd=0 keeps initialized pools with negligible liquidity visible. After the user selects an existing v3 pool, range, token maxima, and slippage, call prepare_lp_position_deposit. Pass its exact execution_plan_reference (URL plus digest) to the wallet MCP for policy checking and exact-plan simulation. The wallet—not this server—controls target, spender, selector, native-value, signing, and submission authorization.

Important: See docs/lp-position-bounds.md for how to calculate correct tick bounds. Ticks encode prices that must account for token decimal differences. For example, an ETH/USDC pair with ETH at 18 decimals and USDC at 6 decimals requires adjusting the price ratio by a factor of 10^(6-18) before converting to ticks, resulting in tick values around -20M, not +76K. Incorrect tick calculations cause deposits to fail or create positions at unintended prices.

If one side must be acquired first, prepare and execute that swap as a separate wallet plan. Wait for its successful receipt, measure the actual token balance, reserve native gas, and only then size and prepare the LP deposit. Never use an unconfirmed quote output as though it were a settled wallet balance.

Finish every swap before minting, and re-read the pool tick with current_state_query afterwards — a position's token ratio follows the range and the current price, not the amounts deposited, so a swap made after the mint moves the tick and re-skews the position it was meant to balance.

For an existing position, call prepare_lp_position_earnings_claim with the connected owner, chain, manager, and token ID from the owner-position list. It automatically selects standard fee collection or Ve33 reward claiming. Run its pending current-state query with the supplied local decode plan, verify the decoded owner against expected_owner, and include the current claim with its unchanged execution plan in the wallet MCP handoff. The prepared call does not remove liquidity, burn the NFT, or transfer it.

For partial or full withdrawals, execute and decode every position's pending current-state query and choose an exact positive liquidity amount no greater than its decoded liquidity. Call prepare_lp_position_withdraw with the legacy single-position fields or a withdrawals array of up to 100 positions. It resolves every PoolKey, bounds, manager overload, recipient, and fee/reward behavior. A multi-position request returns one atomic wallet plan; the wallet may batch these unrelated position calls into one EIP-7702 transaction. Wallet tooling must not construct or alter calls. Each position NFT is preserved.

Every chain input accepts a JSON integer, decimal string, or hexadecimal string. Responses use canonical decimal chain-ID strings. Pool fees are uint64 Q64 values and must always be passed and consumed as decimal or hexadecimal strings, never JSON numbers.

Every executable preparation also includes a signer-neutral execution_plan_reference handoff: an artifact_reference envelope naming where the plan body is stored and an integrity block (keccak256 plus byte count) over its exact bytes. The envelope describes none of the plan's contents; the integrity-verified body is the only source of truth. The agent relays only the envelope, unchanged; the wallet fetches the body itself, recomputes the digest, refuses a mismatch, and validates the plan as if it had been supplied inline. No timestamps travel in the envelope: plan validity is enforced by the wallet's simulation against current chain state, and storage expiry surfaces as a fetch 404. The stored body's ordered_steps place approvals before the main execution and any exact-output allowance cleanup after it, each as a decimal transaction object. The plan_id commits to the chain, sender, destination, calldata, and native value of every approval, execution, and cleanup transaction in the sequence.

Bind the actual wallet address as sender before preparation. Prefer the connected account and call/simulate/submit abstractions exposed by wallet tooling; the wallet refuses a fetched plan whose chain or sender disagrees with its connected chain and account. Pass the whole envelope unchanged as the wallet MCP's reference argument for it to fetch, verify, and execute in order. The wallet executes multi-step plans as one atomic batch; a plan that lists a capability in required_capabilities the wallet does not implement must be rejected, not adapted. Use Cast only when the user selected it or no compatible wallet abstraction is available; the execution-plan resource retains its exact fallback syntax without making Cast the default.

execution_plan_ready means the quote, bounds, and unsigned calldata are complete enough to hand to the wallet. agent_confirmation_required is false: the wallet presents its simulated result and owns authorization. ERC20 plans include the required unsigned approval transaction(s) in addition to the unsigned swap or bridge transaction. Exact-output Ekubo and 0x plans that create an allowance also include a post-execution allowance reset. The client should check current allowance before handing any still-required approval step to the wallet. wallet_validation_required remains true for every prepared plan.

The boundary mirrors the Ekubo interface: the public services provide token data and route quotes, transaction construction applies the user's slippage, and the user's connected wallet or provider handles balances, allowances, current-state validation, gas estimation, signing, submission, and receipts. The Recovery Fund's initial EIP-712 agreement is the one explicit exception to the Ekubo wallet MCP handoff: that wallet intentionally exposes no arbitrary typed-data signing tool. Its preparation result marks the incompatibility and requires a separately selected connected wallet with eth_signTypedData_v4; the resulting execution plan remains compatible with the Ekubo wallet MCP.

For STONX allocation requests, clients should call get_ve33_allocations with only the connected EVM wallet address as owner. The public server is unauthenticated and cannot infer what “my” means. If the client does not expose a connected address, ask the user for it; do not substitute a local keystore, repository account, or machine environment value.

VeToken splitting follows the deployed contract invariants: the source token must retain a nonzero stake, its active vote remains with reduced weight, and the child token starts unvoted. Vote compilation claims pending fees unconditionally before a vote is replaced or cleared, including when the claimable amounts are zero. The extension tool exposes only compound claim-and-extend methods because extension clears its vote.

Documentation truncated — see the full README on GitHub.

Reviews

No reviews yet

Be the first to review this server!