AI Skills

The 1inch AI Skills package teaches AI agents how to connect to and use the 1inch MCP server — the production URL, authentication, and domain-specific workflows (swaps, limit orders, market data, wallet data, and more). Install once; your agent loads the relevant skill on demand.

Install

npx skills add 1inch/1inch-ai

No npm package required — distribution is git-based. Source and full details: github.com/1inch/1inch-ai.

Skills included

The package contains one hub skill and eight domain skills. Each entry links to its full description in the skill reference.

Skills cost almost no context until the agent needs them. Prefer domain skills for concrete tasks (for example "what's the gas price on Base?" → 1inch-market-data teaches GET /gas-price/v1.6/{chainId}).

Skill reference

1inch-mcp-server

The hub skill. It carries the connection knowledge every other skill builds on: the server URL (https://api.1inch.com/mcp/protocol), per-client setup (Cursor, VS Code Copilot, Claude Code, Codex, Gemini CLI over HTTP; Claude Desktop over stdio via supergateway), the authentication options, and an overview of all nine tools. It also tells the agent which domain skill to load for each kind of task, so the detailed recipes stay out of context until needed.

Load it when: setting up the MCP connection for the first time, resolving auth questions, or when the agent needs to decide which domain skill applies.

"Connect me to the 1inch MCP server in Cursor and check which tools are available."

1inch-swap

Teaches quoting and executing token swaps with the swap tool across all three modes:

• Classic — on-chain swap via the aggregation router; the user pays gas (preferredType: "classic")
• Intent — gasless swap filled by resolvers (preferredType: "fusion")
• Cross-chain — swaps between chains without bridges (set dstChain)

The skill covers the quote-first flow (quoteOnly: true to compare modes before executing), per-mode signing guides, submitting a signed Intent or cross-chain order back via signedOrder, and the wallet-first flow — pairing the user's wallet with 1inch-walletconnect so approvals and signatures happen in the wallet app instead of manual signing steps.

Load it when: the user wants the best rate, a gasless swap, a cross-chain swap without bridges, or a quote comparison.

"Quote swapping 100 USDC to ETH on Base, then execute the best option."

1inch-orderbook

Teaches limit orders with the orderbook tool (Limit Order Protocol v4.1) — the server builds orders server-side, so no SDK installation is needed:

• build — server returns EIP-712 typedData, orderHash, and orderData; amounts in smallest units, assets as symbol or address
• sign — eth_signTypedData_v4 with the maker wallet
• create — submit the signed order to the orderbook
• list — query by maker address, by order hash, or browse all with pagination
• cancel — load order state and on-chain cancellation guidance

It also covers the approval step (when build returns an approval block, broadcast the approve transaction first) and the wallet-first flow via 1inch-walletconnect.

Load it when: the user wants to buy or sell at a target price, manage maker orders, or check open orders.

"Build a limit order to sell 1 WETH for USDC on Ethereum, expiring in 1 hour."

1inch-wallet-data

Teaches exact product_api call recipes for wallet-centric data, so the agent calls the right endpoint with the right version instead of guessing paths:

When a path returns 404, the skill directs the agent to the live API index or the search tool rather than inventing version numbers.

Load it when: the user asks about holdings, balances, transaction history, token lookup, or NFT inventory.

"What's my portfolio value on Ethereum for 0x1234…, and list the wallet's balances on Base."

1inch-market-data

Teaches exact product_api call recipes for market data:

It also carries the one gotcha that trips up most integrations: Spot Price returns prices in native token WEI unless you pass currency (e.g. USD).

Load it when: the user asks for a token price, USD price, gas price, or candle/chart data.

"What's the USD price of WETH on Ethereum, and the current gas price on Base?"

1inch-infrastructure

Teaches exact product_api call recipes for chain infrastructure:

Load it when: the user needs JSON-RPC access through 1inch, wants to broadcast a signed transaction, or needs to resolve a domain name.

"Get the latest block number on Ethereum via 1inch Web3 RPC, then resolve vitalik.eth."

1inch-walletconnect

Teaches non-custodial wallet pairing with the walletconnect tool — the server never holds private keys; the user approves every request in their own wallet app:

• connect — returns a pairing QR and wc: URI, plus mobile deep links for curated wallets; choose pairingTarget: eth, solana, or both
• status — poll until the session is active (pending is a success state while waiting)
• sign / send_transaction — drive signatures and transactions through the connected wallet
• disconnect — end the session

It also carries the practical pairing knowledge: many mobile wallets reject EVM and Solana proposed together (start with one namespace), the pairing QR expires after about 10 minutes, and repeating connect with the same pairingTarget returns the same URI instead of invalidating the pending one.

Load it when: the user wants to connect a wallet, scan a QR, or have swaps and orders signed in their wallet instead of handling keys or calldata manually.

"Connect my wallet so you can execute swaps for me — I'll scan the QR."

1inch-aqua

Teaches 1inch Aqua analytics with the aqua tool (public, no authentication) and the drill-down flow for exploring strategies:

1. Get your bearings with list_opened (system-wide feed) or maker_stats (TVL, fees, APY for one maker)
2. Call list_maker_strategies to identify each strategy (chainId, maker, app, strategyHash)
3. Drill into one strategy with strategy_overview (state), strategy_activity (on-chain events), or strategy_volume (time series)

For raw access to Aqua endpoints not covered by the tool, the skill falls back to product_api with paths under /aqua/v1.0/strategies/....

Load it when: the user asks about Aqua makers, strategies, TVL, APY, or liquidity activity.

"What are the aggregated stats for Aqua maker 0x1234…, and show me the volume series for its largest open strategy."

1inch-debug

Teaches request log lookup with the debug tool in its two modes:

• By request id — pass the x-request-id (correlation id) from any API response to trace a specific request, with an optional time window (default 24-hour lookback)
• By time window — pass startTime and endTime (RFC3339) to retrieve all logs for the account, optionally filtered by logLevel (info, warn, error)

Logs are scoped to the authenticated organization by the gateway auth context — other orgs cannot be queried. The queryable window depends on the log retention period of your subscription plan.

Load it when: an API call failed or returned something unexpected and the user wants to trace what happened.

"This swap request returned a 400 — here's the x-request-id, find the logs for it."

Skills and MCP together

Use both: skills teach your agent how to call tools; MCP provides the live connection.

• The skill gives setup knowledge and call recipes as reusable context.
• The MCP server is the live protocol the agent calls to execute swaps, place orders, query APIs, and search docs.

When one is not enough

A skill alone executes nothing. Skills are static instructions — without the MCP connection there is no tool to call, and the execution tools additionally need authentication. Installing the package without connecting the server gives your agent knowledge it cannot act on.

The MCP connection alone covers single-step calls, not flows. Tool schemas describe parameters, not workflows. Without the skills, agents routinely stop halfway through the two-call Intent/cross-chain signing flow, skip the approve step when placing limit orders, guess product_api paths (404s), misread Spot Price's native-WEI default, or restart WalletConnect pairings that were still pending. The tools reference notes per tool where the schema alone falls short.

For stdio-only clients (e.g. Claude Desktop), the hub skill documents the same URLs and auth patterns, but you still need the supergateway setup for the actual MCP connection.

Next steps

• Supported clients — install the skills and configure MCP per editor
• Tools reference — the tools your agent gains access to