Ecosystem

1inch provides two complementary AI integration methods: the MCP Server — a live protocol your AI assistant uses to execute swaps, place limit orders, query APIs, and access documentation — and AI Skills — reusable instruction packages that teach agents the setup patterns. Both are free to connect, work together, and share the same authentication.

MCP Server

The 1inch MCP Server is an AI-native integration: your editor or CLI agent speaks to 1inch over the Model Context Protocol (MCP) so it can execute token swaps, place limit orders, query portfolio and price data, and pull documentation — all through natural conversation.

Cost and access: There is no separate charge to connect to the MCP server. Swap, Orderbook, Business API access, the debug tool, and walletconnect use the same authentication and API entitlements as the rest of the 1inch Business / developer stack (standard API terms apply to those calls). Documentation search, the example catalog, and example source work without authentication, so you can start exploring immediately.

Non-custodial: The walletconnect tool relays signing requests to the user's own wallet via WalletConnect v2. The MCP server never holds private keys — the user always approves each signature or transaction in their own wallet app.

The server is hosted at https://api.1inch.com/mcp/protocol

For setup instructions per client, see Supported Clients.

MCP Server capabilities

The MCP server exposes eight tools. The last three are public; the rest require authentication.

Full parameter reference: Available tools.

AI Skills

The 1inch AI Skill is a reusable instruction package that teaches AI agents how to connect to and use the 1inch MCP server — the production URL, available tools, authentication setup, and client configuration patterns. Install it once and your agent knows the setup automatically.

         
         

           Bash
         
 
         
         

           
           

             
1
           
 
           
           
npx skills add 1inch/1inch-ai
         
       

Source and full details: github.com/1inch/1inch-ai

Use both together: the skill teaches your agent how to connect; MCP provides the live connection.

Authentication

The public tools (search, list_examples, get_example) work without authentication. The execution tools (swap, orderbook, product_api, walletconnect, debug) require authentication via either an API key or OAuth.

API key

Pass your 1inch API key via the Authorization: Bearer <apikey> header. Get a key from the 1inch Business Portal.

How to set the header depends on your MCP client — see the Authentication setup section in Supported Clients for client-specific configuration.

OAuth

When you call an authenticated tool without an API key, MCP clients that support OAuth will automatically prompt you to log in via the 1inch Business Portal. After authentication, all tools become available for the duration of your session. For all supported OAuth flows including client_credentials for server-to-server use, see OAuth 2.1.

Agentic use

"Agentic" here means your client runs a tool loop: the model decides which MCP tools to call, uses the results, and may call again until the task is done. You describe the outcome; the agent plans steps.

Typical tool chains

You do not need to name each tool: a capable client exposes them to the model; prompts like "swap 100 USDC to ETH on Base" or "find the official swap example" are enough.

Prompt patterns that work well for agents

• Direct execution: "Swap 100 USDC to ETH on Base from my wallet 0x1234…"
• Multi-step flows: "Place a limit order to sell 1000 USDC for 1000 USDT on Ethereum, expiring in 1 hour."
• Outcome first: "Implement ERC-20 → USDC swap on Base in TypeScript; use 1inch MCP for docs and examples, then wire it into src/swap.ts."
• Operational queries: "What's my portfolio P&L on Ethereum?" or "What's the current gas price on Base?"
• Verify against examples: "Fetch the closest SDK example from MCP, then diff our quote() call against it."

MCP vs llms.txt for agents

Use both if you split work: e.g. llms.txt in a pipeline for broad grounding, MCP in the IDE for grounded examples and tool-backed answers.

Limits and responsibility

• Sessions: See Too many sessions (429)—each client window may count as a session; agents should avoid spawning unbounded parallel MCP connections.
• Approvals: Your client may ask you to approve tool calls, especially OAuth or API writes. The MCP server does not bypass your org's access rules.
• Secrets: Pass API keys or headers only as documented for your client (e.g. supergateway --header); never commit credentials.

Available tools

The 1inch MCP Server provides eight tools. Five execution tools require authentication; three public tools work without it.

Authenticated tools (API key or OAuth)

These tools require authentication. You can authenticate via an API key header or OAuth — see Authentication setup for client-specific configuration.

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.

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.

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).

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 or sending an order on-chain — instead of pasting transaction data back into a wallet manually.

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 (in the same MCP session as connect) 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. The session response includes optional evm (address, chains) and solana (accounts as CAIP-10 strings) blocks, depending on what the wallet approved.
4. sign / send_transaction — drive the user's wallet for individual signatures or transactions. The user approves each request in their wallet app.
5. 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 (does not invalidate the existing one). 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.

*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: The tool returns 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 tools (no authentication required)

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.

What you can do

Once connected, you work through natural conversation. Your AI assistant calls the right tools behind the scenes.

Execute token swaps

Describe the swap you want ("swap 100 USDC to ETH on Base"), and the assistant automatically finds the best rate across all available routes, handles token resolution, allowance checks, and transaction building. You only need to sign the transaction. Supports same-chain swaps (classic and Fusion) and cross-chain swaps.

Place limit orders

Create limit orders without installing any SDK. Tell your AI "place a limit order to sell 100 USDC for 100 USDT on Ethereum", and the server builds the order server-side, returns the data for you to sign, and submits it to the orderbook.

Query any 1inch API

The product_api tool gives your AI access to all 1inch Business product APIs — Portfolio, Spot Price, Token, Gas Price, Web3 RPC, Balance, NFT, Charts, Transaction Gateway, and more. Ask "what's my portfolio value on Ethereum?" or "what's the current gas price on Base?" — every API endpoint available in the 1inch Business platform is accessible through this single tool.

Connect a non-custodial wallet

The walletconnect tool pairs your AI session with a real wallet via WalletConnect v2 so the assistant can request signatures and submit transactions for you — without ever seeing your private key. Ask "connect my wallet" and the assistant returns a pairing QR (or, on mobile, a tap-to-open deep link for supported wallets like MetaMask, Phantom, Coinbase Wallet, 1inch Wallet, and more). After you approve in the wallet, follow-up requests like "now execute that swap" or "sign this typed data" go straight to your wallet for one-tap approval. Works for EVM and Solana.

Debug production issues

Use debug to trace a request by x-request-id or to list logs in a time range. Paste the correlation id from a failed API response and ask the assistant to pull the matching log lines.

Search documentation and browse SDK examples

Ask any question about 1inch APIs, supported chains, error codes, or integration patterns. Your AI searches across all documentation, API references, and SDK guides — no manual browsing required. You can also pull complete, working code examples directly into your conversation in TypeScript, Go, or Python.

Example prompts

The following examples show the kinds of questions and requests that work well with the 1inch MCP Server and AI Skills. Use them as starting points and adapt to your specific use case.

Executing swaps

"Swap 1000 USDC to ETH on Ethereum from my wallet 0x1234..."

"Find the best rate for swapping 0.5 ETH to USDT on Arbitrum."

"Swap 100 USDC from Base to Polygon."

The assistant calls the swap tool, automatically finds the best rate and route, and returns the transaction or typed data for you to sign.

Managing limit orders

"Place a limit order to sell 1000 USDC for 1000 USDT on Ethereum, expiring in 1 hour."

"List my active limit orders on Ethereum for wallet 0x1234..."

"Check the status of order 0xabc..."

The assistant builds orders server-side, guides you through signing, and submits to the orderbook.

Querying portfolio and token data

"What's my portfolio P&L on Ethereum for wallet 0x1234...?"

"What's the current price of 1INCH in USD?"

"What's the gas price on Base right now?"

The assistant calls the appropriate product API endpoint and returns the data directly.

Connecting a wallet (WalletConnect)

"Connect my wallet so you can execute swaps for me."

"Pair my Phantom wallet for Solana — I'll scan the QR."

"Connect both EVM and Solana so the same session can sign on either."

"What's the status of my wallet connection?"

"Sign this message: 'Welcome to 1inch — login at <date>' from 0x1234..."

"Disconnect my wallet."

The assistant calls the walletconnect tool, presents a QR (or mobile deep link), polls until your wallet approves the pairing, and uses the same session for all follow-up signatures and transactions until you ask it to disconnect.

Debugging with production logs

"Here's my x-request-id from a 500 response — pull the server logs."

"List logs between 2026-01-15T00:00:00Z and 2026-01-15T23:59:59Z."

The assistant calls debug with your request id or time window and returns the matching log entries.

Debugging and troubleshooting

"My swap transaction is returning a 400 error. What are the common causes?"

"I'm getting CORS errors when calling the 1inch API from my frontend. How do I fix this?"

"The approval transaction succeeded but the swap still fails with 'insufficient allowance'. What should I check?"

The assistant searches the FAQ and API documentation for known issues and solutions specific to your error.

Starting a new integration

"I'm building a swap feature on Base. Show me a complete TypeScript example for swapping ERC-20 tokens using the 1inch API."

"I need to integrate 1inch swaps into my Go backend service. Show me how to use the Go SDK."

"How do I call the 1inch swap API from Python?"

The assistant retrieves the relevant SDK example with full source code — including wallet setup, token approval, swap execution, and error handling — in the language you need, ready for you to adapt.

Getting code for specific scenarios

"Show me how to swap native ETH to USDC on Base, including gas estimation."

"Get the Solana swap implementation with proper error handling."

"How do I check and set token allowance before executing a swap in Go?"

"Show me how to set up a viem provider configured for 1inch on Arbitrum."

"Show me a working cross-chain swap example between Ethereum and Base."

The assistant retrieves the matching documentation and example files in your language, and highlights the relevant sections for your scenario.

Understanding APIs and parameters

"What authentication method does the 1inch API use? Show me the header format."

"What parameters does the swap endpoint accept, and which ones are required?"

"What chains and chain IDs does 1inch support?"

"How does the orderbook API work for limit orders?"

The assistant searches the API reference and returns the specific details you need, with links to the full documentation for deeper reading.

Prompting tips

To get the most out of the MCP Server:

• Just say what you want done. "Swap 100 USDC to ETH on Base" or "place a limit order for 1000 USDT on Ethereum" — the assistant handles the rest.
• Mention your chain. Saying "on Base", "on Arbitrum", or "cross-chain from Ethereum to Polygon" helps the assistant pick the right route immediately.
• Combine execution with research. The assistant maintains context, so you can ask "what's the best rate for this swap?" then follow up with "now execute it" and "show me how to handle the error I got" — all in the same session.
• Ask about trade-offs. Questions like "What's the best way to handle large swaps?" or "When should I use limit orders instead of swaps?" get you a tailored recommendation backed by the documentation.
• Ask for examples when building features. When you need working code, ask for an SDK example — the examples are tested, complete implementations that give the AI better context to help you.
• Iterate on the code. Once the assistant retrieves an example, ask follow-up questions: "Now adapt this for USDT instead of USDC" or "Add retry logic for failed transactions."

Legal Disclaimer

Use of the 1inch MCP Server is subject to the 1inch Business Portal Terms of Service and the applicable Software Legal Notice. Users are responsible for ensuring compliance with applicable regulations.