MCP Server Tools Reference

The 1inch MCP server provides nine tools. Five execution tools require authentication; four public tools work without it. For the conceptual overview, see the MCP server page.

Tool schemas describe parameters, not workflows. For single-step calls the schemas are enough, but several tools are one step of a multi-call flow (sign-then-resubmit, approvals, pairing) or accept raw paths the agent has to know. The AI Skills close that gap — each tool below notes what its skill adds and when the tool alone falls short. The reverse also holds: a skill is static context and executes nothing by itself; it always needs this MCP connection, plus authentication for the execution tools.

Authenticated tools (API key or OAuth)

These tools require authentication. Authenticate via an API key header or OAuth — see Authentication setup.

swap

Execute token swaps via 1inch. The server automatically finds the best rate across all available routes, handles token resolution, allowance checks, and transaction building — the agent only signs transactions where required. Supports same-chain and cross-chain swaps.

When the tool alone is enough — and when it isn't: a single quote (quoteOnly: true) or a classic swap is self-contained. Intent and cross-chain execution is a two-call flow — sign the returned typed data, then call swap again with signedOrder — and agents without guidance commonly stop after the first call or pick the wrong mode. 1inch-swap carries the per-mode signing guides and the quote-first comparison flow.

Typical flow:

1. Call swap with source/destination tokens and amount — the server finds the best rate automatically
2. Sign the returned transaction (eth_sendTransaction) or typed data (eth_signTypedData_v4)
3. For Fusion/cross-chain: call swap again with the signedOrder to submit

orderbook

Manage limit orders via the 1inch Orderbook API (v4.1). The server builds orders server-side using the Limit Order SDK — no SDK installation needed on the client.

When the tool alone is enough — and when it isn't: list queries are self-contained. Placing an order is a sequence the schema does not convey — build, then a possible approve transaction, then an eth_signTypedData_v4 signature, then create — and cancellation happens on-chain rather than through an API call. 1inch-orderbook walks the agent through that ordering and the approval handling.

Actions:

Build parameters:

Typical flow:

1. Call orderbook with action: "build" and your order parameters
2. Approve the maker asset for the Limit Order Protocol contract (address provided in the response)
3. Sign the returned typedData with eth_signTypedData_v4
4. Call orderbook with action: "create", passing orderHash, signature, and orderData from the build response

product_api

Call any 1inch Business product API endpoint using your authenticated session. This single tool provides access to all 1inch APIs: Portfolio, Spot Price, Token, Gas Price, Web3 RPC, Balance, NFT, Charts, Transaction Gateway, and every other endpoint available in the 1inch Business platform.

For Portfolio v5.0 through this gateway, use paths starting with /portfolio/portfolio/v5.0/... (the first /portfolio segment is stripped when routing to the Portfolio service).

When the tool alone is enough — and when it isn't: the tool is a raw gateway — it accepts any path but does not tell the agent which endpoint or version answers a given question. If you already know the exact path, it is fully usable on its own; unguided agents instead tend to invent paths (404s) or misread units — Spot Price, for example, returns native token WEI unless currency is set. Three skills carry the exact call recipes: 1inch-wallet-data (portfolio, balances, history, NFTs, tokens), 1inch-market-data (spot prices, gas, charts), and 1inch-infrastructure (Web3 RPC, tx gateway, domains). When no recipe matches, the agent should confirm paths via the search tool rather than guessing.

walletconnect

Pair a non-custodial wallet with the MCP session via WalletConnect v2 so the assistant can request signatures and submit on-chain transactions for the user. Supports EVM and Solana namespaces (depending on the wallet). The MCP server never sees private keys — the wallet app shows every signature / transaction request and the user approves it directly.

When to use it: any flow that needs a real signature or eth_sendTransaction driven by the assistant — for example completing a swap, sending an order on-chain, or confirming an Aqua create_position / close_position — instead of pasting transaction data back into a wallet manually.

When the tool alone is enough — and when it isn't: the individual actions are simple, but the pairing flow has sharp edges the schema does not encode — pending status is a success state to keep polling (not an error), many mobile wallets reject EVM and Solana proposed together, and the QR expires after about 10 minutes. Agents without that context restart pairings or give up mid-flow. 1inch-walletconnect encodes those rules and the session handling.

sign params by method:

Typical flow:

1. connect — call with action: "connect" (optionally pairingTarget: "solana" or "both"). The response contains a pairing QR (PNG resource link) and a wc: URI. Desktop / scan UX: the assistant fetches the QR via MCP resources/read and renders or opens the PNG. Mobile UX: the response includes mobileDeeplinks for curated wallets — tap one to open the wallet directly without scanning.
2. User approves in the wallet. The wallet shows the connection request; the user picks accounts/chains and approves.
3. status — call with action: "status" until kind: "session" is returned (or a clear error). kind: "pending" is a success state — keep polling.
4. accept_terms — for anonymous Aqua writes, the connected wallet signs the 1inch Terms of Use once (personal_sign, no gas). Idempotent if already accepted. Required before create_position / close_position on an unauthenticated session.
5. sign / send_transaction — drive the user's wallet for individual signatures or transactions. The user approves each request in their wallet app.
6. disconnect — call with action: "disconnect" to end the session and clear server-side pairing state.

Idempotent connect: calling connect again while a pairing is still in progress with the same pairingTarget returns the same wc: URI. Changing pairingTarget starts a new proposal and invalidates the previous QR.

Supported wallets

The connect response includes mobileDeeplinks for these curated wallets so users on mobile can pair with one tap. Any WalletConnect v2-compatible wallet can also pair by scanning the QR or pasting the wc: URI:

Error states

The tool returns a structured JSON error with kind: "error" and a code so the assistant can react:

debug

Debug production issues by looking up request logs. Provide a correlation id (x-request-id from any API response) to trace a specific request, or specify a time window to retrieve all logs for your account.

When the tool alone is enough — and when it isn't: if you already have an x-request-id, the tool is self-contained. Without one, the agent needs to know the time-window mode's required parameters and that results are scoped to the authenticated organization and capped by your plan's log retention. 1inch-debug covers the mode selection and those scoping rules.

*Provide requestId, or both startTime and endTime, to list all logs in that window (when requestId is omitted).

Log retention: the time window you can query depends on the log retention period of your subscription plan.

Response shape: JSON with mode (request_id or logs), timeRange (start / end in RFC3339), count, and logs (array of entries). Each entry includes timestamp, message, and optional level and HTTP status code.

Public and mixed-access tools

The tools in this section are usable without authentication. The aqua tool is public: analytics and maker writes (create_position, close_position) work without an API key (pair WalletConnect and sign the 1inch Terms of Use). Taker actions (quote, build_swap) need an API key / OAuth session.

aqua

Analytics for 1inch Aqua, the programmable shared-liquidity layer, plus optional maker writes that preview, create, and close XYC AMM positions. A position is full range by default, or concentrated when you pass a price range. Query maker performance, browse positions, and pull per-position state, on-chain events, and volume series without installing the Aqua SDK. Analytics need no authentication. Writes are non-custodial: the user's wallet signs. Maker writes work without an API key: pair WalletConnect and sign the 1inch Terms of Use. An API key or OAuth session is optional.

For these actions in sequence, see the Aqua walkthrough, which opens a maker position from an AI client.

When the tool alone is enough — and when it isn't: list_opened and maker_stats work with nothing more than an address. The strategy_* actions need the full identifier tuple (chainId, maker, app, strategyHash), which only comes from earlier calls — agents that call them blind get 404s. Creating a position is two calls to create_position: the first (without confirmed) returns a preview and a short-lived previewRef; the second repeats the parameters with the returned openingPrice, the previewRef, and confirmed: true. Anonymous makers must pair WalletConnect and call accept_terms first. 1inch-aqua teaches the drill-down order, the preview-then-confirm flow, and the raw-path fallback for endpoints the tool does not cover.

Actions:

Required parameters per action:

Parameters:

*Required for the actions named in the description — see the table above.

Typical flow:

1. Get your bearings with list_opened (system-wide) or maker_stats (a single maker)
2. Call list_maker_strategies to obtain the chainId / maker / app / strategyHash combination that identifies each strategy
3. Drill into one strategy with strategy_overview (state), strategy_activity (events), or strategy_volume (series)
4. Page through large result sets by passing the returned cursor back in the next call
5. To open a position: create_position without confirmed → review the advisories → create_position again with the same parameters, the returned openingPrice, the previewRef, and confirmed: true. The previewRef is single-use and expires after about two minutes; a stale one is refused and you preview again. Closing is permanent — pass confirmed: true.

Manage a position (maker writes)

1. Pair WalletConnect (connect → approve → status) and call accept_terms. An API key or OAuth session is optional
2. Call create_position without confirmed (two ERC-20 legs, optional priceRange / feeBpsIn)
3. Show the user the preview (opening price vs market, range, fee, advisories, suggested pairs from wallet balances). Adjust and preview again if needed
4. Call create_position again with the same parameters, the returned openingPrice, previewRef, and confirmed: true. Approve tokens and sign in the wallet
5. Monitor with strategy_overview / strategy_activity using the full chainId / maker / app / strategyHash tuple
6. To exit: close_position with confirmed: true and strategy or strategyHash. Closing cannot be undone

Concentrated price ranges

priceRange bounds are raw Swap VM prices, not human-readable ones: P = tokenGt / tokenLt in 1e18 fixed point, where tokenGt is whichever of the two tokens has the higher address value. Compare the lowercase hex; symbol order is irrelevant. To convert a price the user states in their own units:

1. Order the two tokens by address. The higher one is tokenGt
2. Express the price as tokenGt units per tokenLt unit, inverting it if necessary
3. Scale for decimals: rawP = humanPrice × 10^(18 + decimals(tokenGt) − decimals(tokenLt))
4. Pass rawPriceMin and rawPriceMax as decimal strings

Show the user the conversion before confirming. If the price implied by the leg amounts falls outside the band, the position opens one-sided, snapped to the nearer bound; the preview reports oneSided and snapped and does not block it. A range cannot be edited in place — close the position and open a new one to move a band.

Availability

The full Aqua tool is available for B2C without a 1inch Business Portal account. Analytics need no authentication. For create_position / close_position, pair WalletConnect and sign the 1inch Terms of Use. Anonymous writes from restricted regions are blocked.

search

Search across all 1inch documentation, API references, and SDK guides. Returns matching results with titles, snippets, and links.

list_examples

List all available SDK code examples. Returns example names that can be used with the get_example tool. No parameters required.

Currently available examples:

• @1inch-examples/intent-swap — Intent/Fusion swaps for EVM and Solana
• @1inch-examples/limit-order — Limit orders for EVM chains
• @1inch-examples/cross-chain-swap — Cross-chain swaps (Fusion+)

get_example

Retrieve the full source code of an SDK example.