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](#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)](https://modelcontextprotocol.io/) 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**, and the **`debug`** tool 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.

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

For setup instructions per client, see [Supported Clients](supported-clients.md).

:::tip
For AI agents and automation that don't use MCP, see our [LLM-optimized documentation](/llms.txt) -- a machine-readable index of all APIs following the [llmstxt.org](https://llmstxt.org) specification.
:::

### MCP Server capabilities

The MCP server exposes **seven tools**. The first three are public; the rest require [authentication](#authentication).

| Tool            | Auth     | Description                                                                                    |
| :-------------- | :------- | :--------------------------------------------------------------------------------------------- |
| `swap`          | Required | Build quotes and execution steps for classic (Pro), intent (Fusion), and cross-chain swaps     |
| `orderbook`     | Required | Build, sign, submit, list, and cancel limit orders via the 1inch Orderbook API                 |
| `product_api`   | Required | Call 1inch Business product APIs (Portfolio, Spot Price, Token, Gas Price, Web3 RPC, and more) |
| `debug`         | Required | Debug production issues: look up request logs by correlation id or time window                 |
| `search`        | Public   | Search documentation and API reference                                                         |
| `list_examples` | Public   | List available SDK code examples                                                               |
| `get_example`   | Public   | Retrieve full example source (TypeScript, Go, Python, etc.)                                    |

Full parameter reference: [Available tools](#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
npx skills add 1inch/1inch-ai
```

Source and full details: [github.com/1inch/1inch-ai](https://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`, `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](https://business.1inch.com/portal).

How to set the header depends on your MCP client — see the [Authentication setup](supported-clients.md#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](/documentation/apis/authentication#oauth-21).

## 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

| Goal                      | How the agent usually proceeds                                                                                   |
| :------------------------ | :--------------------------------------------------------------------------------------------------------------- |
| Swap or quote exploration | Swap tool for quotes / steps; combine with doc search for mode differences (classic vs Fusion vs cross-chain)    |
| Place a limit order       | Orderbook tool to build the order server-side → sign the returned typed data → submit back via orderbook         |
| Operational checks        | Business API tool for token metadata, gas, spot price, portfolio P&L, etc., then map results back into your code |
| Debug production issues   | **`debug`** with a request id from API responses or a time window to retrieve logs for your account              |
| New feature in your repo  | Documentation search → example catalog → example source → apply or refactor code in your project                 |
| Correct API usage         | Search docs for parameters and errors → cross-check with an example → suggest headers, chains, and payloads      |

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

|                        | MCP                                                                     | [`/llms.txt`](/llms.txt)                               |
| :--------------------- | :---------------------------------------------------------------------- | :----------------------------------------------------- |
| **Best for**           | Agentic execution (swaps, orders, APIs) + interactive coding assistants | Bulk context, custom RAG, CI jobs, clients without MCP |
| **Freshness**          | Live API access + server-side search (periodically indexed)             | Snapshot index you fetch and chunk yourself            |
| **Authenticated APIs** | Yes — swaps, orderbook, portfolio, gas, spot price, debugging, and more | No — static links and summaries only                   |

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)](supported-clients.md#troubleshooting)—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 seven tools. Four execution tools require [authentication](#authentication); three public tools work without it.

### Authenticated tools (API key or OAuth)

These tools require [authentication](#authentication). You can authenticate via an API key header or OAuth — see [Authentication setup](supported-clients.md#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.

| Parameter       | Type    | Required | Description                                                     |
| :-------------- | :------ | :------- | :-------------------------------------------------------------- |
| `src`           | string  | Yes      | Source token (symbol or address)                                |
| `dst`           | string  | Yes      | Destination token (symbol or address)                           |
| `amount`        | string  | Yes      | Amount in smallest units                                        |
| `chain`         | number  | Yes      | Chain ID                                                        |
| `from`          | string  | Yes      | Sender wallet address                                           |
| `quoteOnly`     | boolean | No       | If true, returns quotes without building a transaction          |
| `preferredType` | string  | No       | `"classic"`, `"fusion"`, or `"crosschain"` (omit to auto-route) |
| `dstChain`      | number  | No       | Destination chain ID (triggers cross-chain mode)                |
| `slippage`      | number  | No       | Slippage tolerance in percent (default 0.5)                     |
| `signedOrder`   | string  | No       | Submit a previously signed Fusion/cross-chain order             |
| `orderHash`     | string  | No       | Order hash for submission                                       |

**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:**

| Action   | Description                                                              |
| :------- | :----------------------------------------------------------------------- |
| `build`  | Server-side order construction. Returns EIP-712 typed data for signing   |
| `create` | Submit a signed order to the orderbook                                   |
| `list`   | Query orders by maker address, order hash, or browse all with pagination |
| `cancel` | Load order state and return on-chain cancellation guidance               |

**Build parameters:**

| Parameter           | Type   | Required | Description                          |
| :------------------ | :----- | :------- | :----------------------------------- |
| `action`            | string | Yes      | `"build"`                            |
| `chain`             | number | Yes      | Chain ID                             |
| `makerAsset`        | string | Yes      | Token to sell (symbol or address)    |
| `takerAsset`        | string | Yes      | Token to receive (symbol or address) |
| `makingAmount`      | string | Yes      | Amount to sell (smallest units)      |
| `takingAmount`      | string | Yes      | Amount to receive (smallest units)   |
| `maker`             | string | Yes      | Maker wallet address                 |
| `expirationSeconds` | number | No       | Expiration in seconds (default 600)  |

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

| Parameter | Type   | Required | Description                                                       |
| :-------- | :----- | :------- | :---------------------------------------------------------------- |
| `method`  | string | No       | `"GET"` or `"POST"` (default `"GET"`)                             |
| `path`    | string | Yes      | API path (e.g. `/portfolio/portfolio/v5.0/general/current_value`) |
| `query`   | object | No       | Query parameters as key-value pairs                               |
| `body`    | object | No       | Request body for POST requests                                    |

#### `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.

| Parameter   | Type   | Required | Description                                                                                                                                                                                                   |
| :---------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `requestId` | string | No\*     | `x-request-id` (or correlation id) from API responses. When set, searches logs for this value; optional `startTime` / `endTime` narrow the window (defaults to the last 24 hours ending at `endTime` or now). |
| `startTime` | string | No\*     | RFC3339 start of the query window (required with `endTime` when `requestId` is omitted).                                                                                                                      |
| `endTime`   | string | No       | RFC3339 end of the query window.                                                                                                                                                                              |
| `logLevel`  | string | No       | Filter by log level: `"info"`, `"warn"`, or `"error"`. Omit to return all levels. Only applies to time-window mode (ignored when `requestId` is set).                                                         |
| `limit`     | number | No       | Max log lines (1–100, default 50).                                                                                                                                                                            |

\*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.

| Parameter      | Type    | Required | Description                           |
| :------------- | :------ | :------- | :------------------------------------ |
| `query`        | string  | Yes      | Search query                          |
| `limit`        | number  | No       | Results per page (1–100)              |
| `page`         | number  | No       | Page number (1-based)                 |
| `include_body` | boolean | No       | Include full document body in results |

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

| Parameter | Type   | Required | Description                                |
| :-------- | :----- | :------- | :----------------------------------------- |
| `name`    | string | Yes      | Example name from `list_examples`          |
| `file`    | string | No       | Specific file path (omit to get all files) |

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

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

:::info
The examples are provided in TypeScript — but your AI assistant can translate them into any language. Just ask for "the swap example in Java" or "convert this to Rust" and it will adapt the code for you.
:::

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

### 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](/portal/assets/legal-docs/terms_of_service_public_api_20260218.pdf) and the applicable [Software Legal Notice](/portal/assets/legal-docs/software_policy_20260218.pdf). Users are responsible for ensuring compliance with applicable regulations.