Polkaswap

Inspiration

Planning a swap involves identifying assets, reading precise amounts, comparing routes, and checking fees, price impact, and freshness. We wanted browser agents to obtain those facts directly from the exchange and explain them through a structured, inspectable interface.

Polkaswap already connects people to SORA liquidity. WebMCP lets an agent use that same application to build a useful plan while wallet access remains a separate decision.

What it does

Polkaswap exposes nine public WebMCP tools for capabilities, status, readiness, asset search and resolution, common assets, quotes, unsigned swap plans, and pool information.

An agent can respond to “Plan swapping 1 XOR for VAL with 0.5% slippage” by calling polkaswap_plan_swap directly. It waits for the node, resolves assets, obtains a fresh quote, and returns the route, amount bounds, fee estimate when available, warnings, expiry, network context, and unsigned SDK-call metadata. Unavailable fees produce an explicit warning. No wallet connection or prior quote-button click is required.

People can inspect the same planning workflow in the agent playground. Changing the pair or amount refreshes the plan automatically; visible pages also refresh expired plans. A switch stops automatic planning. The interface prevents older responses from overwriting newer inputs.

Public tools cannot expose account identity or balances, connect a wallet, create an executable intent, sign, submit, transfer funds, or change liquidity. Plans return mode: "unsigned", canExecute: false, and requiresWallet: false. The preview is SDK-call metadata, not a SCALE-encoded transaction. This entry provides autonomous planning, with no unattended trading.

How we built it

The implementation uses Vue 3, TypeScript, Vite, the existing SORA SDK and node connection, and FPNumber for precise token amounts. Tools register through document.modelContext.registerTool() when WebMCP is available. The playground registers its tools at the top level and forwards calls into its same-origin application iframe.

Strict schemas require decimal-string amounts and reject additional properties. Public result projection excludes wallet and provider details. Cancellation, bounded errors, network-context checks, and five-minute expiry keep planning results predictable. No executable authorization is stored by planning.

Everything ships as static assets suitable for IPFS, without hosted command middleware. An optional local Node.js stdio MCP bridge shares the same public catalogue. Humans use visible controls and agents use named tools, with both reaching the application's existing planning logic.

Challenges we addressed

Browser agents do not discover tools registered inside the playground iframe, so discovery needed a top-level adapter. Useful market results also needed careful separation from the application's broader wallet-aware API.

Planning introduced timing problems: inputs can change during a quote, results can expire, and pages can become hidden. The scheduler serializes requests, ignores superseded results, pauses while hidden, and bounds retries for transient failures.

Accomplishments

Native verification of the published build discovered all nine tools and directly invoked polkaswap_plan_swap. It returned an unsigned live SORA plan without wallet access. The page planner also refreshed from 1 to 2 XOR and stopped automatic refresh when disabled.

The clean submission passed 306 focused tests across 21 files, 13 translation tests across four files, and nine preview-helper tests. The official Node MCP stdio check discovered all nine schemas. A separate browser registration-harness smoke verified planning and input-change replanning with zero captured console, request, or HTTP errors.

Existing project and challenge contribution

Polkaswap is an existing open-source exchange. Its exchange UI, SORA integration, wallet workflows, static deployment infrastructure, and earlier browser-agent foundation predate this contribution.

The August 25–September 3, 2026 challenge contribution adds the public WebMCP catalogue and adapters, wallet-independent swap planning, the agent playground and automatic replanning behavior, and supporting tests and documentation. The linked public comparison identifies the changes from baseline 893783b to submission commit 4955eb0.

What's next

We want clearer multi-route comparisons, more useful public market reads, and better explanations when node data is temporarily unavailable. Signing and execution remain outside the public WebMCP tools.

Built With

• mcp
• typescript
• webmcp