MCP Near Intents

Package: @iqai/mcp-near-intents
Purpose: An MCP server for Near Intents swaps using the Defuse Protocol one-click SDK. This server provides tools for cross-chain token swaps through NEAR's intent-based architecture.
Example: 🚀 Near Intents Swaps Example

Usage with ADK TypeScript

McpNearIntents({
  env: {
    NEAR_SWAP_JWT_TOKEN: process.env.NEAR_SWAP_JWT_TOKEN,
  },
})

import {McpToolset} from "@iqai/adk";

const toolset = new McpToolset({
  name: "Near Intents Swaps MCP Client",
  description: "Client for Near Intents cross-chain swaps",
  transport: {
    mode: "stdio",
    command: "pnpm",
    args: ["dlx", "@iqai/mcp-near-intents"],
    env: {
      NEAR_SWAP_JWT_TOKEN: process.env.NEAR_SWAP_JWT_TOKEN,
      PATH: process.env.PATH || "",
    },
  },
})

const tools = await toolset.getTools()

{
  "mcpServers": {
    "near-intents-server": {
      "command": "pnpm",
      "args": ["dlx", "@iqai/mcp-near-intents"],
      "env": {
        "NEAR_SWAP_JWT_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

Features

GET_NEAR_SWAP_TOKENS: Discover available tokens for swaps
GET_NEAR_SWAP_SIMPLE_QUOTE: Get basic swap quotes without addresses
GET_NEAR_SWAP_FULL_QUOTE: Get complete quotes with deposit addresses
EXECUTE_NEAR_SWAP: Execute swaps by submitting deposit transactions
CHECK_NEAR_SWAP_STATUS: Check the status of swap executions

User Flow

This server supports a complete 5-step user flow:

[DISCOVERY] Use GET_NEAR_SWAP_TOKENS to discover available tokens
[STEP 1] Use GET_NEAR_SWAP_SIMPLE_QUOTE to check swap rates without addresses
[STEP 2] Use GET_NEAR_SWAP_FULL_QUOTE to get deposit address when ready to swap
[STEP 3] User sends funds to the deposit address (external action)
[STEP 4] Use EXECUTE_NEAR_SWAP to submit deposit transaction hash
[STEP 5] Use CHECK_NEAR_SWAP_STATUS to monitor swap progress until completion

Prerequisites

Node.js >= 16
pnpm >= 8
A JWT token from the Defuse Protocol (for authentication)

Configuration

Set the following environment variables:

# Optional: Custom API endpoint (defaults to https://1click.chaindefuser.com)
export NEAR_SWAP_API_URL="https://1click.chaindefuser.com"

# Required: JWT token for authentication
export NEAR_SWAP_JWT_TOKEN="your-jwt-token-here"

Usage

Running the Server

# Start the MCP server
pnpm start

# Or run directly
node dist/index.js

Available Tools

GET_NEAR_SWAP_SIMPLE_QUOTE

originAsset:stringdestinationAsset:stringamount:stringswapType:stringslippageTolerance:numberquoteWaitingTimeMs:number

Description

[STEP 1] Get a simple quote for a NEAR intent swap between different chains and assets. This is a dry run that doesn't require any addresses - perfect for users who want to check swap rates and fees before committing to a swap. Use this when users want to explore swap options without providing recipient addresses. NOTE: If users provide simple token names (e.g., 'ETH', 'USDC'), first use GET_NEAR_SWAP_TOKENS to discover the exact token IDs required for this API.

GET_NEAR_SWAP_FULL_QUOTE

swapType:stringoriginAsset:stringdestinationAsset:stringamount:stringrecipient:stringrecipientType:stringrefundTo:stringrefundType:stringslippageTolerance:numberdry:booleandepositType:stringdeadline:stringreferral:stringquoteWaitingTimeMs:number

Description

[STEP 2] Get a full quote with deposit address for a NEAR intent swap. This requires recipient and refund addresses and returns a unique deposit address where users can send their funds to initiate the swap. Use this when users are ready to proceed with the swap after checking the simple quote. NOTE: If users provide simple token names (e.g., 'ETH', 'USDC'), first use GET_NEAR_SWAP_TOKENS to discover the exact token IDs required for this API.

EXECUTE_NEAR_SWAP

txHash:stringdepositAddress:string

Description

[STEP 4] Submit a deposit transaction hash to initiate the swap after sending funds to the deposit address. This notifies the 1Click service that funds have been sent and triggers the swap execution process. Use this after users have sent their funds to the deposit address from the full quote response.

CHECK_NEAR_SWAP_STATUS

depositAddress:string

Description

[STEP 5] Check the current execution status of a NEAR intent swap. Returns the swap state (PENDING_DEPOSIT, PROCESSING, SUCCESS, REFUNDED, FAILED, etc.) along with detailed transaction information. Use this to monitor swap progress after initiating the swap, and continue polling until the swap is complete.

GET_NEAR_SWAP_TOKENS

No parameters

Description

[DISCOVERY] Get a list of tokens currently supported by the 1Click API for NEAR Intents. Returns token metadata including blockchain, contract address, current USD price, symbol, decimals, and price update timestamp. Use this to help users discover available tokens before requesting quotes.

Example Usage

1. Discovering Available Tokens

{}

2. Getting a Simple Quote

{
  "originAsset": "nep141:arb-0xaf88d065e77c8cc2239327c5edb3a432268e5831.omft.near",
  "destinationAsset": "nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near",
  "amount": "1000000000000000000",
  "swapType": "EXACT_INPUT",
  "slippageTolerance": 100
}

3. Getting a Full Quote with Deposit Address

{
  "originAsset": "nep141:arb-0xaf88d065e77c8cc2239327c5edb3a432268e5831.omft.near",
  "destinationAsset": "nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near",
  "amount": "1000000000000000000",
  "recipient": "13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK",
  "recipientType": "DESTINATION_CHAIN",
  "refundTo": "0x2527D02599Ba641c19FEa793cD0F167589a0f10D",
  "refundType": "ORIGIN_CHAIN",
  "slippageTolerance": 100,
  "dry": false
}

4. Executing a Swap

{
  "txHash": "0x1234567890abcdef...",
  "depositAddress": "0xabcdef1234567890..."
}

5. Checking Status

{
  "depositAddress": "0xabcdef1234567890..."
}

Token Names vs Token IDs

When users provide simple token names (e.g., 'ETH', 'USDC'), use GET_NEAR_SWAP_TOKENS first to discover the exact token IDs required by the API. The API expects full token identifiers like 'nep141:arb-0xaf88d065e77c8cc2239327c5edb3a432268e5831.omft.near'.

Authentication

This server requires a JWT token for authentication with the Defuse Protocol API. Make sure to set the NEAR_SWAP_JWT_TOKEN environment variable before running the server.

Error Handling

The server provides detailed error messages for common issues:

Missing JWT token
Invalid request parameters
API connection errors
Invalid asset identifiers

MCP Near Intents

On this page