NEAR Intents 1Click API 跨链交换集成指南：从报价到入金的完整实战方案

NEAR Intents 1Click API 是一套把"意图（Intent）"抽象为简单 REST 调用的跨链代币交换服务：你只需请求报价、向 API 提供的唯一存款地址转入资金，即可自动完成跨 EVM、Solana、NEAR、TON、Stellar、Tron 等链的兑换。本指南以仓库 vendored/near/near-intents/SKILL.md 为骨架，结合其下的规则文档与示例源码，完整讲解从 token 列表获取、dry/wet 报价、各链存款构建、状态轮询到高级余额模式的全流程，读完即可落地一个可运行的 React 交换组件或 Node.js 服务端脚本。

1Click API 的工作原理

1Click 简化了 NEAR Intents 的使用方式：它会临时将资产转移给一个可信的交换代理（swapping agent），由该代理协调做市商（Market Makers）执行你的意图。REST API 把意图创建、求解器（solver）协调与交易执行全部封装起来，你只需要处理三个动作：

1. 获取支持的代币列表（GET /v0/tokens）；
2. 请求报价（POST /v0/quote，dry: true预览，dry: false获取存款地址）；
3. 向存款地址转入资金，其余自动完成。

整个交换生命周期（详见 concepts.md）可以概括为：

Request Quote → Deposit Tokens → Submit Tx Hash → Monitor Status → Success/Refund

对应的完整 API 调用链（来自 SKILL.md 的集成流程图）为：

GET /v0/tokens → POST /v0/quote (dry) → POST /v0/quote (wet) → Deposit TX → POST /v0/deposit/submit → GET /v0/status

其中POST /v0/deposit/submit与GET /v0/status均为可选优化步骤：前者让 1Click 立即感知你的存款以加速处理，后者用于轮询交换进度。

前置准备：获取代币列表与 API Key

获取支持的代币（GET /v0/tokens）

所有可交换代币通过 api-tokens.md 中定义的GET /v0/tokens获取，该接口变化不频繁，建议缓存结果：

const response = await fetch('https://1click.chaindefuser.com/v0/tokens'); const tokens = await response.json();

返回的每个Token对象结构如下：

文档提供了一个实用的查找辅助函数：

const findToken = (tokens: Token[], symbol: string, blockchain: string) => tokens.find(t => t.symbol.toLowerCase() === symbol.toLowerCase() && t.blockchain === blockchain ); // 示例 const usdcEth = findToken(tokens, 'USDC', 'eth'); // usdcEth.assetId = "nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near" // usdcEth.contractAddress = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

关键原则：永远使用/v0/tokens返回的assetId，绝不手工拼接资产 ID。从上面的示例可以看到，即使是 EVM 上的 USDC，其assetId也是以nep141:前缀表达的 NEAR 生态格式，手工构造极易出错。

认证与费率

在 Partners Portal 注册可获取 API Key，并通过Authorization: Bearer请求头携带，可免去 0.1%（10 个基点）的手续费：

headers: { Authorization: `Bearer ${apiKey}` }

核心：请求报价（POST /v0/quote）

报价接口 api-quote.md 是集成中最核心的一环。dry: true只做预览（不生成存款地址），dry: false提交并返回约 10 分钟有效的存款地址。

必填字段

可选字段——路由

可选字段——价格

可选字段——费用与追踪

可选字段——虚拟链（高级）

四种交换类型（swapType）

EXACT_INPUT（最常用）——固定输入金额、可变输出：

{ swapType: 'EXACT_INPUT', amount: '1000000' } // 正好交换 1 USDC

行为规则：

• 存款恰好等于amountIn→ 收到amountOut；
• 存款少于amountIn→ 到期后退款；
• 存款多于amountIn→ 交换照常处理，超额部分完成后退还。

EXACT_OUTPUT——固定输出金额、可变输入：

{ swapType: 'EXACT_OUTPUT', amount: '1000000000000000000' } // 正好换出 1 ETH

响应中额外包含minAmountIn、maxAmountIn。行为规则：存款落在minAmountIn与maxAmountIn之间 → 收到精确的amountOut；少于minAmountIn→ 退款；多于maxAmountIn→ 交换照常处理，超额退还。

FLEX_INPUT——带滑点区间的可变输入，适合"全部兑换"场景：

{ swapType: 'FLEX_INPUT', amount: '1000000', slippageTolerance: 100 }

响应包含minAmountIn、minAmountOut。行为规则：任意 ≥minAmountIn的存款都被接受；输出保证 ≥minAmountOut；滑点同时作用于输入与输出区间。

ANY_INPUT——累积式存款，截止时间前可多次存入：

{ swapType: 'ANY_INPUT', amount: '0' } // 无固定金额

适用场景：聚合多笔存款，之后通过/v0/any-input/withdrawals提现。

报价响应字段

{ correlationId: string; // 唯一报价 ID timestamp: string; // 报价生成时间 quoteRequest: { ... }; // 请求回显 quote: { // 存款信息（仅 dry: false 时返回） depositAddress: string; // 资金发往此处 depositMemo: string | null; // 若非 null 必须在交易中携带（Stellar） // 金额 amountIn: string; // 预期输入（最小单位） amountInFormatted: string; // 人类可读 "1.00" amountInUsd: string; // USD 价值（仅展示） minAmountIn?: string; // 用于 EXACT_OUTPUT、FLEX_INPUT maxAmountIn?: string; // 用于 EXACT_OUTPUT amountOut: string; // 预期输出（最小单位） amountOutFormatted: string; // 人类可读 amountOutUsd: string; // USD 价值（仅展示——绝不可用于业务逻辑） minAmountOut?: string; // 滑点后的保证最低输出 // 时间 deadline: string; // ISO 时间戳——存款必须在此之前到账 timeWhenInactive: string; // 报价失效时间（仅 dry: false 返回） timeEstimate: number; // 预计完成时间（秒） } }

实战示例：预览 → 提交拿地址

第一步，dry 预览（ETH USDC → NEAR wNEAR）：

const preview = await fetch('https://1click.chaindefuser.com/v0/quote', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ dry: true, swapType: 'EXACT_INPUT', originAsset: 'nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near', destinationAsset: 'nep141:wrap.near', amount: '1000000', // 1 USDC（6 位小数） recipient: 'user.near', refundTo: '0xYourEthAddress', slippageTolerance: 100, // 1% }) }).then(r => r.json()); // preview.quote.amountOutFormatted = "0.35" (wNEAR)

第二步，dry: false 提交并获取存款地址（携带 API Key 可免 0.1% 费用）：

const committed = await fetch('https://1click.chaindefuser.com/v0/quote', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' // 免除 0.1% 费用 }, body: JSON.stringify({ dry: false, // 提交！ swapType: 'EXACT_INPUT', originAsset: 'nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near', destinationAsset: 'nep141:wrap.near', amount: '1000000', recipient: 'user.near', refundTo: '0xYourEthAddress', slippageTolerance: 100, referral: 'myapp', appFees: [{ recipient: 'myfees.near', fee: 50 }], // 0.5% 手续费 }) }).then(r => r.json()); // committed.quote.depositAddress = "0x..." → 把 1 USDC 发到这里 // committed.quote.deadline = "2025-01-16T15:00:00Z" → 必须在此之前存款

状态机与轮询（GET /v0/status）

交换进度通过 api-status.md 中的GET /v0/status查询，需轮询直到进入终态。

GET /v0/status?depositAddress=0x...

Stellar（MEMO 模式）需附加 memo：?depositAddress=GABCD...&depositMemo=123456。

状态值表

响应结构

interface StatusResponse { correlationId: string; status: string; updatedAt: string; quoteResponse: QuoteResponse; // 原始报价 swapDetails: { amountIn: string; amountInFormatted: string; amountOut: string; amountOutFormatted: string; slippage: number; originChainTxHashes: Array<{ hash: string; explorerUrl: string }>; destinationChainTxHashes: Array<{ hash: string; explorerUrl: string }>; refundedAmount?: string; refundReason?: string; depositedAmount?: string; }; }

推荐的轮询模式

async function pollUntilComplete(depositAddress: string, apiKey?: string) { const headers = apiKey ? { Authorization: `Bearer ${apiKey}` } : {}; for (let i = 0; i < 120; i++) { // 最多约 4 分钟 const res = await fetch( `https://1click.chaindefuser.com/v0/status?depositAddress=${depositAddress}`, { headers } ); const status = await res.json(); if (['SUCCESS', 'FAILED', 'REFUNDED', 'INCOMPLETE_DEPOSIT'].includes(status.status)) { return status; } await new Promise(r => setTimeout(r, 2000)); // 每 2 秒轮询一次 } throw new Error('Timeout waiting for swap completion'); }

通知存款：加速处理（POST /v0/deposit/submit）

api-deposit-submit.md 定义的可选接口用于在存款交易确认后立即通知 1Click，加快处理速度，改善用户体验：

await fetch('https://1click.chaindefuser.com/v0/deposit/submit', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}`, }, body: JSON.stringify({ txHash: '0x123abc...', // 你的存款交易哈希 depositAddress: quote.quote.depositAddress, }) });

NEAR 示例：

await fetch('https://1click.chaindefuser.com/v0/deposit/submit', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ txHash: 'Hk3ds...', depositAddress: quote.quote.depositAddress, nearSenderAccount: 'user.near', }) });

Stellar 示例：

await fetch('https://1click.chaindefuser.com/v0/deposit/submit', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ txHash: 'abc123...', depositAddress: quote.quote.depositAddress, memo: quote.quote.depositMemo, }) });

在存款交易确认后立即调用即可；非必需，但能显著提升 UX。

各链存款构建指南

获取存款地址后，需要按源链构建对应的转账交易。以下实现均来自仓库中对应的 deposit 规则文档，可直接复用。

EVM 链（Ethereum / Base / Arbitrum / Optimism / Polygon / BSC / Avalanche / Gnosis / Berachain）

见 deposit-evm.md。原生代币（ETH/MATIC 等）用 wagmi 的sendTransaction：

import { useSendTransaction } from 'wagmi'; const { sendTransactionAsync } = useSendTransaction(); const hash = await sendTransactionAsync({ to: depositAddress as `0x${string}`, value: BigInt(amountIn), });

ERC-20 代币用writeContract执行transfer，合约地址取自 token API 的contractAddress：

import { useWriteContract } from 'wagmi'; import { erc20Abi } from 'viem'; const { writeContractAsync } = useWriteContract(); const hash = await writeContractAsync({ address: tokenAddress as `0x${string}`, abi: erc20Abi, functionName: 'transfer', args: [depositAddress as `0x${string}`, BigInt(amountIn)], });

Solana（原生 SOL 与 SPL 代币）

见 deposit-solana.md。原生 SOL 直接使用SystemProgram.transfer；SPL 代币需通过关联代币账户（ATA）转账，目标 ATA 不存在时先创建：

import { useWallet, useConnection } from '@solana/wallet-adapter-react'; import { SystemProgram, Transaction, PublicKey } from '@solana/web3.js'; const { publicKey, sendTransaction } = useWallet(); const { connection } = useConnection(); const tx = new Transaction().add( SystemProgram.transfer({ fromPubkey: publicKey!, toPubkey: new PublicKey(depositAddress), lamports: BigInt(amountIn), }) ); const signature = await sendTransaction(tx, connection); await connection.confirmTransaction(signature);

SPL 版本使用@solana/spl-token的getAssociatedTokenAddressSync、createAssociatedTokenAccountInstruction与createTransferInstruction，tokenMint取自 token API 的contractAddress。

NEAR（NEP-141 代币）

见 deposit-near.md，通过@near-wallet-selector/react的 wallet selector 发起ft_transfer：

import { useWalletSelector } from '@near-wallet-selector/react'; const { selector } = useWalletSelector(); const wallet = await selector.wallet(); const result = await wallet.signAndSendTransactions({ transactions: [{ receiverId: tokenContract, // contractAddress 来自 token API actions: [{ type: 'FunctionCall', params: { methodName: 'ft_transfer', args: { receiver_id: depositAddress, amount: amountIn }, gas: '50000000000000', // 50 TGas deposit: '1', // 需要 1 yoctoNEAR }, }], }], }); const txHash = result?.[0]?.transaction?.hash;

原生 NEAR 必须先包装成 wNEAR：对wrap.near先调用near_deposit（deposit 为包装金额），再调用ft_transfer。调用/v0/deposit/submit时需携带nearSenderAccount: 'user.near'。

TON（原生 TON 与 Jetton）

见 deposit-ton.md，通过@tonconnect/ui-react的 TonConnect 发起，金额单位为 nanoton：

import { useTonConnectUI } from '@tonconnect/ui-react'; const [tonConnect] = useTonConnectUI(); const result = await tonConnect.sendTransaction({ validUntil: Math.floor(Date.now() / 1000) + 600, // 10 分钟 messages: [{ address: depositAddress, amount: amountIn, // 单位 nanoton }], }); const txHash = result.boc;

Jetton 转账需要用@ton/core手工构建transferop code（0xf8a7ea5）的消息体，注意目标是用户的 jetton 钱包地址而非代币合约地址，需从 jetton master 合约查询。

Tron（原生 TRX 与 TRC-20）

见 deposit-tron.md，使用tronweb。金额单位为 SUN（1 TRX = 1,000,000 SUN）；TRC-20 通过triggerSmartContract调用transfer(address,uint256)。

Stellar（MEMO 必须）

见 deposit-stellar.md。Stellar 必须使用depositMode: 'MEMO'，交易中必须携带 memo，否则资金丢失。报价示例：

const quote = await fetch('https://1click.chaindefuser.com/v0/quote', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ dry: false, depositMode: 'MEMO', // Stellar 必填 originAsset: 'nep141:stellar-native.omft.near', destinationAsset: 'nep141:wrap.near', amount: '10000000', // 1 XLM（以 stroop 计，7 位小数） recipient: 'user.near', refundTo: 'GA5X...', // Stellar 地址 }) }).then(r => r.json()); // quote.quote.depositMemo = "123456" - 交易中必须携带

交易构建使用@stellar/stellar-sdk的TransactionBuilder，通过.addMemo(Memo.text(quote.quote.depositMemo))附加 memo；状态轮询同样要带上 memo 参数。

完整实现：React 交换组件

仓库 react-swap-widget.md 提供了一个最小可用的 React 交换组件，依赖如下：

npm install @tanstack/react-query wagmi viem

组件结构要点（完整代码见规则文档）：

• API 封装为三个 hooks：useTokens（5 分钟缓存）、useQuote（dry 预览，refetchInterval: 10_000定时刷新）、useSwapStatus（轮询状态，进入终态后自动停止轮询）；
• 执行封装为 mutation：useExecuteSwap依次完成 dry: false 获取存款地址 → 调用钱包sendTransaction→ 调/v0/deposit/submit通知（该步骤.catch(() => {})非关键）；
• EVM 双分支处理：有contractAddress走 ERC-20transfer，否则走原生代币sendTransactionAsync；
• 链校验：handleSwap中通过CHAIN_IDS[fromToken.blockchain]与当前链比对，不匹配则提示切换网络；
• 金额换算：用 viem 的parseUnits(amount, fromToken.decimals)把人类可读金额转最小单位。

使用方式：

import { SwapWidget } from './SwapWidget'; <SwapWidget apiKey={process.env.NEXT_PUBLIC_ONE_CLICK_API_KEY} />

该示例展示的四个关键模式（详见文档 What This Example Shows）：Flow（tokens → dry quote → wet quote → send TX → poll status）、useQuery/useMutation分工、EVM 原生 vs ERC-20 处理、终态自动停轮询。接入现有应用时替换 wagmi 配置、换成自己的设计系统即可。

完整实现：Node.js 服务端脚本

仓库 server-example.md 给出了无框架的纯 TypeScript + viem 服务端实现，适用于机器人、后端服务等场景：

npm install viem

核心流程（executeSwap函数）：取代币列表 → 定位代币 →parseUnits换算 → dry: false 获取真实存款地址 → 按原生/ERC-20 分支发送存款交易 →submitDeposit通知 →pollStatus轮询至终态（最多 6 分钟、每 2 秒一次）。

运行方式：

PRIVATE_KEY=0x... ONE_CLICK_API_KEY=... npx tsx bot.ts

该文档还提供了 Solana 源链的补充示例：原生 SOL 用SystemProgram.transfer，SPL 用createTransferInstruction走关联账户。

React Hooks 封装（可复用）

react-hooks.md 将核心 API 封装为四个可复用 hooks（useTokens/useQuote/useSwapStatus/useExecuteSwap），要点：

• useTokens设置staleTime: 5 * 60 * 1000缓存 5 分钟；
• useQuote固定dry: true+EXACT_INPUT+slippageTolerance: 100，仅当amount非空非零时启用，每 10 秒自动刷新；
• useSwapStatus在进入终态后把refetchInterval置为false，避免无谓轮询；
• useExecuteSwap作为useMutation暴露，把"wet quote → 发送交易 → 通知 API"三步串成一条原子操作，sendTransaction由调用方注入（可接 wagmi、ethers 等任意钱包逻辑）。

高级模式一：Intents 余额模式

默认的**链到链（chain-to-chain）**模式（在源链存款、目标链收款）适合绝大多数场景；但高频交易或追求更快执行时，可选用 intents-balance.md 的intents.near 余额模式——应用以 intents.near 上的余额运作，两种模式在应用内只能二选一。

入金到余额：recipientType: 'INTENTS'，recipient为 NEAR 账户名：

const quote = await fetch('https://1click.chaindefuser.com/v0/quote', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ dry: false, swapType: 'EXACT_INPUT', originAsset: 'nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near', destinationAsset: 'nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near', // 相同资产 depositType: 'ORIGIN_CHAIN', recipientType: 'INTENTS', // 记入 intents 余额 recipient: 'user.near', // 记入该 NEAR 账户 refundTo: '0xUserAddress', amount: '1000000', }) }).then(r => r.json());

从余额提现：depositType: 'INTENTS'、recipientType: 'DESTINATION_CHAIN'，同时指定refundType: 'INTENTS'。

查询余额：通过near-api-js调用intents.near合约的mt_balance_of：

import { connect, keyStores } from 'near-api-js'; const near = await connect({ networkId: 'mainnet', keyStore: new keyStores.InMemoryKeyStore(), nodeUrl: 'https://rpc.mainnet.near.org', }); const account = await near.account(accountId); const balance = await account.viewFunction({ contractId: 'intents.near', methodName: 'mt_balance_of', args: { account_id: accountId, token_id: tokenId }, });

高级模式二：被动存款（QR 码）

passive-deposit.md 描述的是不实现链上转账逻辑的方案：展示存款地址（可生成 QR 码）让用户从自己的钱包手动转账。适合比特币等被动链或 CEX 提币场景。使用FLEX_INPUT以容忍实际到账金额的微小偏差：

const quote = await fetch('https://1click.chaindefuser.com/v0/quote', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ dry: false, swapType: 'FLEX_INPUT', slippageTolerance: 100, // 1% - 允许金额轻微波动 originAsset: 'nep141:btc.omft.near', // Bitcoin destinationAsset: 'nep141:wrap.near', amount: '100000000', // 1 BTC（以 satoshi 计） recipient: 'user.near', refundTo: 'bc1q...', // 比特币退款地址 }) }).then(r => r.json());

UI 层只需展示depositAddress、depositMemo（若有则标红并强调必须携带）、amountInFormatted与deadline，并提供复制按钮。

关键注意事项与最佳实践

CEX 存款警告

concepts.md 特别提醒：中心化交易所（CEX）常使用中间地址或按用户分配的内部地址，通过 NEAR Intents 发送的转账可能无法被识别或未列入白名单而无法入账。建议先向 CEX 地址发送小额测试金额，再执行全量转账。

展示数据与业务逻辑分离

报价响应中的amountOutUsd字段仅供展示，绝不可用于业务逻辑或计算。业务判断必须基于真实代币金额（amountOut、amountIn及其Formatted变体）。

四条关键知识（Skill 元数据）

1. 使用/v0/tokens返回的assetId——绝不手工构造；
2. dry: true仅预览，dry: false才返回存款地址（约 10 分钟有效）；
3. 轮询状态直到终态：SUCCESS、FAILED、REFUNDED、INCOMPLETE_DEPOSIT；
4. 链到链是默认模式——depositType与recipientType默认即链端点，多数场景无需显式设置。

文档索引

本 Skill 的完整知识库位于仓库vendored/near/near-intents/下，按优先级组织：

外部资源：1Click API 文档（https://docs.near-intents.org/near-intents/integration/distribution-channels/1click-api）、API Key 申请（https://partners.near-intents.org/）、OpenAPI 规范（https://1click.chaindefuser.com/docs/v0/openapi.yaml）。本文涉及的所有端点均基于仓库文档中使用的基准地址https://1click.chaindefuser.com。