Near Intent Swaps

npm version License: MIT

📖 Overview

The NEAR Intent Swaps MCP Server enables AI agents to perform cross-chain token swaps through NEAR's intent-based architecture using the Defuse Protocol one-click SDK. This server provides a comprehensive 5-step flow for discovering tokens, getting quotes, executing swaps, and tracking their status.

By implementing the Model Context Protocol (MCP), this server allows Large Language Models (LLMs) to facilitate cross-chain swaps seamlessly, bridging the gap between AI assistants and decentralized cross-chain infrastructure.

✨ Features

• Token Discovery: Discover available tokens across multiple blockchains supported by the Defuse Protocol.
• Simple Quotes: Get basic swap quotes without requiring addresses - perfect for rate checking.
• Full Quotes: Get complete quotes with deposit addresses for executing swaps.
• Swap Execution: Submit deposit transaction hashes to execute cross-chain swaps.
• Status Tracking: Monitor swap progress and completion status in real-time.

📦 Installation

🚀 Using npx (Recommended)

To use this server without installing it globally:

npx @iqai/mcp-near-intent-swaps

🔧 Build from Source

git clone https://github.com/IQAIcom/mcp-near-intent-swaps.git
cd mcp-near-intent-swaps
pnpm install
pnpm run build

⚡ Running with an MCP Client

Add the following configuration to your MCP client settings (e.g., claude_desktop_config.json).

📋 Minimal Configuration

{
  "mcpServers": {
    "near-intent-swaps": {
      "command": "npx",
      "args": ["-y", "@iqai/mcp-near-intent-swaps"],
      "env": {
        "NEAR_SWAP_JWT_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

⚙️ Advanced Configuration (Local Build)

{
  "mcpServers": {
    "near-intent-swaps": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-near-intent-swaps/dist/index.js"],
      "env": {
        "NEAR_SWAP_JWT_TOKEN": "your-jwt-token-here",
        "NEAR_SWAP_API_URL": "https://1click.chaindefuser.com"
      }
    }
  }
}

🔐 Configuration (Environment Variables)

Variable	Required	Description	Default
NEAR_SWAP_JWT_TOKEN	Yes	JWT token for Defuse Protocol API authentication	-
NEAR_SWAP_API_URL	No	Custom API endpoint	https://1click.chaindefuser.com

💡 Usage Examples

🔍 Token Discovery

• "What tokens are available for cross-chain swaps on NEAR?"
• "Show me all supported tokens in the Defuse Protocol."
• "List available tokens I can swap from Arbitrum to Solana."

📊 Getting Quotes

• "What's the rate to swap 100 USDC from Arbitrum to SOL?"
• "Get me a quote for swapping ETH to USDC on NEAR."
• "How much SOL would I get for 1000 USDC?"

💱 Executing Swaps

• "I want to swap 500 USDC from Arbitrum to Solana."
• "Help me execute a cross-chain swap with this deposit address."
• "I've sent the funds to the deposit address, here's my transaction hash."

📈 Tracking Status

• "Check the status of my swap with deposit address 0xabc..."
• "Is my cross-chain swap complete?"
• "What's the current state of my pending swap?"

🛠️ MCP Tools

CHECK_NEAR_SWAP_STATUS

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

Parameter	Type	Required	Description
depositAddress	string	✅	The unique deposit address from the quote response - used to track and retrieve the current status of the swap

EXECUTE_NEAR_SWAP

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

Parameter	Type	Required	Description
txHash	string	✅	Transaction hash of your deposit transaction that was sent to the deposit address from the quote
depositAddress	string	✅	The deposit address that was provided in the quote response and to which the deposit transaction was sent

GET_NEAR_SWAP_FULL_QUOTE

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

Parameter	Type	Required	Default	Description
swapType	string		"EXACT_INPUT"	(Optional, defaults to EXACT_INPUT) Whether to use the amount as the output or the input for the basis of the swap: EXACT_INPUT - request output amount for exact input, EXACT_OUTPUT - request output amount for exact output. The refundTo address will always receive excess tokens back even after the swap is complete.
originAsset	string	✅		ID of the origin asset (e.g. 'nep141:arb-0xaf88d065e77c8cc2239327c5edb3a432268e5831.omft.near')
destinationAsset	string	✅		ID of the destination asset (e.g. 'nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near')
amount	string	✅		Amount to swap as the base amount (can be switched to exact input/output using the dedicated flag), denoted in the smallest unit of the specified currency (e.g., wei for ETH)
recipient	string	✅		Recipient address. The format should match recipientType.
recipientType	string		"DESTINATION_CHAIN"	(Optional, defaults to DESTINATION_CHAIN) Type of recipient address: DESTINATION_CHAIN - assets will be transferred to chain of destinationAsset, INTENTS - assets will be transferred to account inside intents
refundTo	string			(Optional) Address for user refund
refundType	string		"ORIGIN_CHAIN"	(Optional, defaults to ORIGIN_CHAIN) Type of refund address: ORIGIN_CHAIN - assets will be refunded to refundTo address on the origin chain, INTENTS - assets will be refunded to refundTo intents account
slippageTolerance	number		100	(Optional, defaults to 100) Slippage tolerance for the swap. This value is in basis points (1/100th of a percent), e.g. 100 for 1% slippage.
dry	boolean		false	(Optional, defaults to false) Flag indicating whether this is a dry run request. If true, the response will NOT contain the following fields: depositAddress, timeWhenInactive, deadline.
depositType	string		"ORIGIN_CHAIN"	(Optional, defaults to ORIGIN_CHAIN) Type of the deposit address: ORIGIN_CHAIN - deposit address on the origin chain, INTENTS - account ID inside near intents to which you should transfer assets inside intents
deadline	string		"2026-02-10T11:56:58.847Z"	(Optional, defaults to 1 hour from now) Timestamp in ISO format, that identifies when user refund will begin if the swap isn't completed by then. It needs to exceed the time required for the deposit tx to be minted, e.g. for Bitcoin it might require ~1h depending on the gas fees paid.
referral	string			(Optional) Referral identifier (lower case only). It will be reflected in the on-chain data and displayed on public analytics platforms.
quoteWaitingTimeMs	number		3000	(Optional, defaults to 3000) Time in milliseconds user is willing to wait for quote from relay

GET_NEAR_SWAP_SIMPLE_QUOTE

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

Parameter	Type	Required	Default	Description
originAsset	string	✅		ID of the origin asset (e.g. 'nep141:arb-0xaf88d065e77c8cc2239327c5edb3a432268e5831.omft.near')
destinationAsset	string	✅		ID of the destination asset (e.g. 'nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near')
amount	string	✅		Amount to swap as the base amount, denoted in the smallest unit of the specified currency (e.g., wei for ETH)
swapType	string		"EXACT_INPUT"	(Optional, defaults to EXACT_INPUT) Whether to use the amount as input or output for the swap calculation
slippageTolerance	number		100	(Optional, defaults to 100) Slippage tolerance in basis points (100 = 1%)
quoteWaitingTimeMs	number		3000	(Optional, defaults to 3000) Time in milliseconds to wait for quote from relay

GET_NEAR_SWAP_TOKENS

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

No parameters

👨‍💻 Development

🏗️ Build Project

pnpm run build

👁️ Development Mode (Watch)

pnpm run watch

✅ Linting & Formatting

pnpm run lint
pnpm run format

📁 Project Structure

• src/tools/: Individual tool definitions
• src/services/: API client and business logic
• src/lib/: Shared utilities
• src/index.ts: Server entry point

📚 Resources

• Defuse Protocol one-click SDK
• Model Context Protocol (MCP)
• NEAR Protocol

⚠️ Disclaimer

This project interacts with cross-chain swap infrastructure. Users should exercise caution and verify all transaction details before executing swaps. Cross-chain transactions involve multiple blockchains and carry inherent risks.

📄 License

MIT