Add Balancer plugin for Base MCP

[tiago-hansen]

Summary

Adds a native Base MCP plugin for Balancer, authored against skills/base-mcp/references/plugin-spec.md.

• New file: skills/base-mcp/plugins/balancer.md.

Integration: cli-only

Balancer's API returns swap paths and pool data, not calldata; calldata is encoded by @balancer/sdk running in Node, and its query() simulation needs a Base RPC. Balancer ships no hosted calldata endpoint, so every step requires a shell — reads/quotes via curl, calldata via a short Node SDK script — then submit via send_calls. On chat-only surfaces the plugin is unsupported (no web_request/paste fallback): tell the user it needs a terminal and stop. Same pattern as Aerodrome.

v2 / v3 routing (verified live)

The SOR routes each pair through Balancer v2 or v3 by liquidity, and the two settle differently. Tested against the live API + a Base RPC — USDC→WETH currently routes v2, so this is the common path, not an edge case:

• v3 → v3 Router; Permit2 allowance batched ahead of the Router call; msg.sender is sender/recipient.
• v2 → Balancer V2 Vault (0xBA1222…BF2C8); plain ERC20 approval to the Vault; buildCall requires sender/recipient (else it throws).

The build script detects v2 from the SOR paths and emits protocolVersion so the agent assembles the correct send_calls batch.

Frontmatter

field	value
integration	cli-only
requires.shell	required
requires.allowlist	[] (API reached from the shell via curl, not web_request)
requires.cliPackage	null (no Balancer CLI — the shell path is a Node script using @balancer/sdk)
chains	[base, ethereum, arbitrum, optimism, avalanche]
auth	none
risk	[slippage, low-liquidity]

[cb-heimdall]

✅ Heimdall Review Status

Requirement	Status	More Info
Reviews	✅ 1/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[stephancill]

Thanks for the submission. The frontmatter and structure are spec-conformant and the v3 swap path builds and submits correctly. There is a blocking correctness issue in the build script:

Required

• Revert the SKILL.md plugins-table row. Plugins shouldn't add themselves to the registry — maintainers will register them when the program is ready. Limit the PR to plugins/balancer.md.
• build-swap.mjs omits sender/recipient on the basis that "v3 makes msg.sender the sender/recipient." That is v3-only. The SOR routes through both v2 and v3 depending on liquidity, and v2-routed pairs cause buildCall to throw: Input Validation: Swap input missing parameter sender/recipient for Balancer v2. A significant share of common Base pairs currently route v2 (e.g. WETH->cbETH, USDC->DAI, WETH->BAL), so the headline example fails intermittently. Pass sender/recipient (the wallet from get_wallets) whenever any path has protocolVersion: 2.
• v2 settles through the V2 Vault, so the Permit2 onchain-allowance batch in ## Submission is v3-specific. Document the version-dependent submission (v2 uses Vault approval, not Permit2).

[youssefea]

Thank you for your submission @tiago-hansen ! This would limit the calldata generation to CLI only where the agent has access to generating nodejs code, right? In which case, can you please update the fontmatter?

[youssefea]

Thanks again for putting this together, @tiago-hansen. One operational note: this PR includes one or more commits that GitHub marks as unverified. We require verified commits for external plugin submissions so we can rely on GitHub signature and provenance checks before merging code into base/skills.

Could you please open a new PR with verified commits? I cannot merge this PR as-is. Thank you.

[tiago-hansen]

Thanks for the review and the clear guidance, @youssefea! 🙏

I've opened #104 to replace this PR with verified, SSH-signed commits, so it satisfies the verified-signatures branch requirement. It's the same Balancer plugin, with a few small robustness improvements folded in:

• build-swap.mjs now emits the full, version-correct send_calls batch (approval(s) + action call) instead of just the action call, so a v3 Permit2 approval can't be mismatched against a v2 Vault target.
• Handles a null priceImpact (the SOR returns it for some valid multi-hop routes, e.g. USDC→WETH) as "unknown" rather than a hard error.
• Removes the web_request references.

Closing this in favor of #104.