## Overview
As a resolver, offering farm incentives to delegators can help increase your Unicorn Power balance and consequently, your probability of filling orders. Upon registering as a resolver, the farm contract is automatically deployed. You can fetch the farm by interacting with the `dst1inch` contract's ABI. Note that you can reward delegators with any ERC-20 token, not only tokens from the incentive program.
---
### How to Fetch a Farm with the `dst1inch` Contract
1. Go to the "Read Contract" section of the [`dst1inch` contract](https://etherscan.io/token/0xAccfAc2339e16DC80c50d2fa81b5c2B049B4f947#readContract#F6) on Etherscan. Under the `defaultFarms` method, enter your resolver address within the 'address' parameter and send the call.
1. Click on the returned farm contract address and navigate to the 'Write Contract' section of the returned contract page. This is your newly generated farm distribution address.
3. Call the `setDistributor` method using the address that will be managing and distributing rewards.
4. On the same contract, call `addRewardsToken` with the desired token address that will be distributed to your delegators.
5. Lastly, on the same contract, call `startFarming`, entering the `rewardsToken` address, amount, and period (both amount and period are uint256). Once called, your farm will have started, and rewards will begin to be distributed to your delegators.
---
### How to Replenish Farming Token Balance (Optional)
To replenish the token balance of your farm rewards, call `addRewardsToken` and `startFarming` to the farm contract as done in the initial setup.
---
### Example ABI Interaction
:::info
The example script below reads ABI definitions for both the [dst1inch](https://etherscan.io/token/0xAccfAc2339e16DC80c50d2fa81b5c2B049B4f947#code) and [multiFarmingPod](https://etherscan.io/address/0x1583C1dBe20625d0B752d472E845FbA96D096829#code) contracts.
You will need to create two new files and add the ABI definitions which can be found at these URLS:
- [`dst1inchABI.json`](https://api.etherscan.io/api?module=contract&action=getabi&address=0xAccfAc2339e16DC80c50d2fa81b5c2B049B4f947&apikey=YourApiKeyToken)
- [`abi.json`](https://api.etherscan.io/api?module=contract&action=getabi&address=0x1583C1dBe20625d0B752d472E845FbA96D096829&apikey=YourApiKeyToken)
Don't forget to replace 'YourApiKeyToken' with your actual Etherscan API key at the end of each linked URL above!
:::
```javascript
require("dotenv").config(); //for accessing sensitive information such as private keys, API keys, etc.
const { Web3 } = require("web3");
const web3 = new Web3(`Your_ethereum_RPC`);
const fs = require("fs");
const dst1inchABI = JSON.parse(fs.readFileSync("dst1inchABI.json", "utf8"));
const farmABI = JSON.parse(fs.readFileSync("abi.json", "utf8"));
const erc20Abi = [
// ERC20 ABI fragment (for contract approval)
{
constant: false,
inputs: [
{
name: "spender",
type: "address"
},
{
name: "value",
type: "uint256"
}
],
name: "approve",
outputs: [
{
name: "",
type: "bool"
}
],
payable: false,
stateMutability: "nonpayable",
type: "function"
}
];
const dst1inch = "0xAccfAc2339e16DC80c50d2fa81b5c2B049B4f947";
const dst1inchContract = new web3.eth.Contract(dst1inchABI, dst1inch);
const account = "YOUR_REGISTERED_ADDRESS";
const privateKey = "YOUR_PRIVATE_KEY";
async function distributeFarmingRewards(resolverAddress, newDistributor, rewardsToken, amount, period) {
try {
// Call defaultFarms with your resolver address
const farmAddress = await dst1inchContract.methods.defaultFarms(resolverAddress).call();
console.log(`Farm address: ${farmAddress}`);
const farmContract = new web3.eth.Contract(farmABI, farmAddress);
const tokenContract = new web3.eth.Contract(erc20Abi, rewardsToken);
// Call setDistributor on the returned farm address
const setDistributorTx = {
from: resolverAddress,
to: farmAddress,
data: farmContract.methods.setDistributor(newDistributor).encodeABI()
};
const setDistributorSignedTx = await web3.eth.accounts.signTransaction(setDistributorTx, privateKey);
await web3.eth.sendSignedTransaction(setDistributorSignedTx.rawTransaction);
console.log("Distributor set successfully");
// Approve the farm contract to spend the tokens
const approveTx = {
from: newDistributor,
to: rewardsToken,
data: tokenContract.methods.approve(farmAddress, amount).encodeABI()
};
const approveSignedTx = await web3.eth.accounts.signTransaction(approveTx, privateKey);
await web3.eth.sendSignedTransaction(approveSignedTx.rawTransaction);
console.log("Approval transaction confirmed");
// Call addRewardsToken with the address of distribution token
const addRewardsTokenTx = {
from: newDistributor,
to: farmAddress,
data: farmContract.methods.addRewardsToken(rewardsToken).encodeABI()
};
const addRewardsTokenSignedTx = await web3.eth.accounts.signTransaction(addRewardsTokenTx, privateKey);
await web3.eth.sendSignedTransaction(addRewardsTokenSignedTx.rawTransaction);
console.log("Rewards token added successfully");
// Call startFarming(address rewardsToken, uint256 amount, uint256 period)
const startFarmingTx = {
from: newDistributor,
to: farmAddress,
data: farmContract.methods.startFarming(rewardsToken, amount, period).encodeABI()
};
const startFarmingSignedTx = await web3.eth.accounts.signTransaction(startFarmingTx, privateKey);
await web3.eth.sendSignedTransaction(startFarmingSignedTx.rawTransaction);
console.log("Farming started successfully");
} catch (error) {
console.error("Error distributing farming rewards:", error);
}
}
const resolverAddress = account;
const newDistributor = account; // you can use any address as the distributor
const rewardsToken = "0xRewardsTokenAddress";
const amount = web3.utils.toWei("Amount", "Token Name"); // Amount of rewards tokens
const period = 3600; // Period in seconds
distributeFarmingRewards(resolverAddress, newDistributor, rewardsToken, amount, period)
.then(() => console.log("Farming rewards distributed successfully"))
.catch((error) => console.error("Error distributing farming rewards:", error));
```
Have questions? Reach out to us in the live support chat!
#### The partial fill feature
When an order is 100% filled, a single secret is used to finalize the transaction between two parties. However, when an order is only partially filled by different resolvers, revealing the secret to the public could let others claim the remainder of the order without completing their part.
To solve this, a Merkle tree of secrets is implemented for partial fills, which splits the order into equal parts and generates dedicated secrets for each portion of swap.
For example, if an order is divided into four parts, the first secret is used for the first 25%, the second for 50%, and so on. If a participant fills a part of the order, the next participant uses the corresponding secret based on the current progress to continue filling the order. This ensures that each participant can only fill their portion without exposing the rest of the order.
In the example image below, the 1st secret is used for the initial 0-20% fill, marking the first stage of the order. Secrets 2 and 3 are not used because the order skips directly from 20% to 80%, bypassing the ranges where these secrets would apply. The 4th secret is then used to fill the order from 20% to 80%, covering this larger portion. Finally, the 5th secret is used to complete the final 80-100% of the order, ensuring that the entire order is securely and progressively filled.
## API reference
For detailed information about each endpoint, refer to the Fusion+ API [OpenAPI specs](./relayer/v1.2/submit/method/post).
## After V 6.1
## API reference
For detailed information about each endpoint, refer to the classic swap API [OpenAPI specs](./methods/v6.1/1/quote/method/get).
## Quickstart
In order to quickly understand how to make an exchange using the protocol, we suggest you use the [Quickstart guide](./quick-start.md).
:::info
For workloads that require higher RPS, expanded quotas, or sustained performance, explore the available paid plans on the [**pricing page**](/pricing).
For organizations with significant trading volumes or advanced requirements, [**complete this application**](/get-enterprise) to explore tailored Enterprise options.
:::
- **Src is not set:** The 'src' (source token contract) field is missing.
- **Dst is not set:** The 'dst' (destination token contract) field is missing.
- **Insufficient liquidity:** The aggregator can't find a route for the swap due to low liquidity.
## Swap-specific Errors
- **Not enough src balance:** This means your source token balance is insufficient. It provides the required amount and your current balance.
- **Not enough Allowance:** You haven't granted the necessary token allowance to the 1inch router. It'll indicate the amount, current allowance, and the spender address, e.g., "Spender: 0x1111111254eeb25477b68fb85ed929f73a960582".
- **Insufficient liquidity:** As mentioned earlier, the aggregator couldn't route the swap.
:::info
For workloads that require higher RPS, expanded quotas, or sustained performance, explore the available paid plans on the [**pricing page**](/pricing).
For organizations with significant trading volumes or advanced requirements, [**complete this application**](/get-enterprise) to explore tailored Enterprise options.
:::
---
## What are the "parts" parameters?
The parts parameters is comprised of 3 things
- mainRouteParts
- virtualParts
- parts
Each of these has their own unique meaning. The main route parts denotes the initial split and can be seen on the UI. In this example it's the 70%/30% split
The parts parameter is how many individual blocks there can be. In the picture above we can see 4 blocks with the top being the first main route part with 2 parts to it and the bottom one being the second main route part with 2 parts in it.
The virtual parts is the splits _inside_ of a part. We can see in the first main route part above, in the first block there are 2 virtual parts splitting the USDC between hashflow and uniswap. In the second main route part we can see three virtual parts in the first block, a hashflow route with 2 different rates and one to uniswap.
## What is the "Complexity level?"
Complexity level is how many steps a swap can go through, below are the levels and what it means for the swap. Each level adds to the previous level.
- **Complexity level 0:** the source token can be wrapped or unwrapped and swapped through one liquidity pool per main route part.
- **Complexity level 1:** the source token can be wrapped or unwrapped and swapped through two liquidity pools. This means there can be up to one connector token in each main route part.
- **Complexity level 2 (Default):** the source token can be wrapped or unwrapped and swapped through three liquidity pools. This means there can be up to two connector tokens in each main route part.
- **Complexity level 3:** the source token can be wrapped or unwrapped and swapped through four liquidity pools. This means there can be up to three connector tokens in each main route part.
## How can I limit the liquidity sources in the query?
To limit the liquidity sources to a query, you can manually enter the pool-contacts that you to use using the "protocols" parameter. All other liquidity sources will be excluded by default.
### Still have questions?
Feel free to reach out to us in the live support chat!
:::tip Debugging with `X-Request-Id`
Every API response includes an `X-Request-Id` header that uniquely identifies your request. When contacting support, include this value for faster investigation. If you use the [1inch MCP Server](/portal/documentation/ai-integration/ecosystem), the `debug` tool can look up production logs by this request id.
:::
Claude Desktop | [Instructions](#claude-desktop) | [Install](#ai-skills-installation) |
| 
Cursor | [Instructions](#cursor) | [Install](#ai-skills-installation) |
| 
Windsurf | [Instructions](#windsurf) | [Install](#ai-skills-installation) |
| 
VS Code (Copilot) | [Instructions](#vs-code-copilot) | [Install](#ai-skills-installation) |
| JetBrains IDEs | [Instructions](#jetbrains-ides) | [Install](#ai-skills-installation) |
The following clients are also MCP-compatible and can connect using the [generic setup](#other-mcp-clients) below:
- **Continue** -- open-source AI assistant for VS Code and JetBrains
- **Zed** -- AI-native code editor
- **Amazon Q Developer** -- AWS AI coding assistant
MCP is an open standard with rapidly growing adoption. Any MCP-compatible client can connect to the 1inch MCP Server.
## MCP Server setup
### Claude Code
Claude Code supports HTTP MCP servers natively:
```bash
claude mcp add \
--transport http \
--scope user \
1inch-business \
https://api.1inch.com/mcp/protocol
```
### OpenAI Codex
Codex supports MCP servers in both the CLI and the VS Code extension:
```bash
codex --mcp-server "https://api.1inch.com/mcp/protocol"
```
For the VS Code extension, add the server in the Codex MCP settings panel with the same URL.
### Gemini CLI
Gemini CLI supports HTTP MCP servers natively:
```bash
gemini mcp add \
--transport http \
1inch-business \
https://api.1inch.com/mcp/protocol
```
### Claude Desktop
Claude Desktop communicates via stdio, so you use [`supergateway`](https://www.npmjs.com/package/supergateway) to bridge to the HTTP server. This requires Node.js 18+.
Add the following to your configuration file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"1inch-business": {
"command": "/absolute/path/to/node/bin/npx",
"args": [
"-y",
"supergateway",
"--streamableHttp",
"https://api.1inch.com/mcp/protocol",
"--outputTransport",
"stdio"
],
"env": {
"PATH": "/absolute/path/to/node/bin:/usr/bin:/bin"
}
}
}
}
```
Replace `/absolute/path/to/node/bin` with the path to your Node.js installation (e.g., `/usr/local/bin` or the output of `dirname $(which node)`).
:::info
The `command` and `PATH` fields require absolute paths because AI clients do not inherit your shell's PATH. Using `npx -y` ensures the latest version of `supergateway` is downloaded automatically.
:::
### Cursor
Create or edit `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"1inch-business": {
"url": "https://api.1inch.com/mcp/protocol"
}
}
}
```
### Windsurf
Create or edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"1inch-business": {
"serverUrl": "https://api.1inch.com/mcp/protocol"
}
}
}
```
### VS Code (Copilot)
Create or edit `.vscode/mcp.json` in your project root:
```json
{
"servers": {
"1inch-business": {
"type": "http",
"url": "https://api.1inch.com/mcp/protocol"
}
}
}
```
:::info
VS Code also supports configuring MCP servers through `settings.json` under the `"mcp"` key. See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for additional options.
:::
### JetBrains IDEs
IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs support MCP through the AI Assistant (2025.1+).
1. Open **Settings** -> **Tools** -> **AI Assistant** -> **Model Context Protocol (MCP)**
2. Click **Add**, select **HTTP**, and paste the following JSON snippet:
```json
{
"mcpServers": {
"1inch-business": {
"url": "https://api.1inch.com/mcp/protocol"
}
}
}
```
The 1inch MCP tools will be available in the AI Assistant chat within your IDE.
### Other MCP clients
Most MCP clients support HTTP transport and can connect directly to the server URL:
- **Server URL:** `https://api.1inch.com/mcp/protocol`
For clients that only support stdio transport, use [`supergateway`](https://www.npmjs.com/package/supergateway) to bridge to the HTTP server (requires Node.js 18+):
```bash
npx -y supergateway \
--streamableHttp https://api.1inch.com/mcp/protocol \
--outputTransport stdio
```
Configure your client to launch this as a subprocess and communicate over stdin/stdout.
## AI Skills installation
Install the 1inch AI Skill so your agent knows the server URL, tools, and auth patterns automatically:
```bash
npx skills add 1inch/1inch-ai
```
No npm package required -- distribution is git-based. For more details, see [AI Skills](ecosystem.md#ai-skills).
For **stdio-only** clients (e.g. Claude Desktop), the skill documents the same URLs and auth patterns, but you still need the [supergateway setup](#claude-desktop) above for the actual MCP connection.
## Authentication setup
The public tools (`search`, `list_examples`, `get_example`) work without authentication. To use the execution tools (`swap`, `orderbook`, `product_api`, `debug`), pass your API key via the `Authorization` header. Get a key from the [1inch Business Portal](https://business.1inch.com/portal).
For the conceptual overview of API key vs OAuth authentication, see [Authentication](ecosystem.md#authentication).
**Claude Code:**
```bash
claude mcp add \
--transport http \
--header "Authorization: Bearer YOUR_API_KEY" \
--scope user \
1inch-business \
https://api.1inch.com/mcp/protocol
```
**Cursor** (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"1inch-business": {
"url": "https://api.1inch.com/mcp/protocol",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
**VS Code Copilot** (`.vscode/mcp.json`):
```json
{
"servers": {
"1inch-business": {
"type": "http",
"url": "https://api.1inch.com/mcp/protocol",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
**Claude Desktop** (supergateway):
```json
{
"mcpServers": {
"1inch-business": {
"command": "/absolute/path/to/node/bin/npx",
"args": [
"-y",
"supergateway",
"--streamableHttp",
"https://api.1inch.com/mcp/protocol",
"--header",
"Authorization: Bearer YOUR_API_KEY",
"--outputTransport",
"stdio"
],
"env": {
"PATH": "/absolute/path/to/node/bin:/usr/bin:/bin"
}
}
}
}
```
For other clients, consult the client's MCP documentation for how to set custom HTTP headers on the transport.
## Troubleshooting
| Issue | Solution |
| :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Connection refused | Verify the `command` path is absolute. Check that `https://api.1inch.com/mcp/protocol` is reachable from your network |
| Server not appearing | Restart your AI client after modifying the configuration file. Check that the JSON is valid (no trailing commas) |
| `npx` not found | Ensure Node.js 18+ is installed. Use an absolute path to `npx` in the `command` field (e.g., `/usr/local/bin/npx`) |
| Too many sessions (429) | Each AI client window opens a separate session. Close windows you're not using, or wait 15 minutes for idle sessions to expire. This limit is specific to MCP sessions and does not affect your API usage |
| Tools not loading | Check the AI client's MCP logs for connection errors. In Cursor, use **Developer: Open MCP Log** from the command palette |
| Auth prompt not appearing | If using OAuth, ensure your MCP client supports OAuth flows. Alternatively, use an API key via the `Authorization` header (see [Authentication setup](#authentication-setup)). Some clients may require a restart after configuration changes |
| Stale results | Documentation indexes are updated periodically. If recently published content is missing, try again in a few minutes |