1inch API 集成：兑换、认证与 RPC 架构

1inch API 究竟是什么

1inch API 是由 1inch Business 运营的一组托管式 REST 和 WebSocket 服务。它不是节点提供商，也不是区块链。它是一个链下聚合与数据层：你向它发送描述代币对和数量的请求，它返回路由、报价，通常还有可直接签名的交易 calldata。然后你的钱包或后端对该 calldata 签名，并提交到你选择的 RPC 端点。

这种分离对架构很重要。1inch API 决定构建什么交易；你的 RPC 端点决定该交易是否以及多快到达链上。将两者视为同一供应商的团队，在兑换失败时往往最终调试了错误的层。RPC 端点指南更深入地解释了节点侧。

该套件的范围远不止兑换。公开文档列出了 Swap、Orderbook、Balance、Spot Price、Token、Transaction、Portfolio、Gas Price、NFT、Traces、History、Web3 RPC、Domain、Token Details 和 Charts API。大多数集成只需要 Swap 加上一两个数据端点。

• Swap API：报价、calldata 和三种模式（聚合器、意图、跨链）
• 数据 API：代币元数据、现货价格、余额、Gas 价格、交易历史
• 认证：Bearer API 密钥或 OAuth 2.1（客户端凭证或带 PKCE 的授权码）
• 传输：HTTPS REST，部分流式端点使用 WebSocket

前提条件与假设

本指南假设你拥有一个 1inch Business 账户，其中至少有一个应用和 API 密钥；在受支持的链上有一个已注资的钱包；以及该链的 RPC URL。它还假设你使用 Node.js 18+ 或 Python 3.10+ 来运行代码示例。这里不要求特定的 RPC 供应商；像 RPC_URL 这样的占位符是有意为之。

你还应该知道目标链 ID。1inch API 的大多数端点都按链区分，在报价请求和 RPC 提交之间混用链 ID 是最常见的集成错误之一。如果你对节点访问不熟悉，多链 RPC 端点指南介绍了如何按链组织端点。

认证：API 密钥与 OAuth 2.1

文档化行为：1inch Business API 支持两种认证方法。API 密钥是用于直接集成的简单 Bearer 令牌。OAuth 2.1 用于用户同意流程和服务器到服务器访问，支持的授权类型包括客户端凭证和带 PKCE 的授权码。两者最终都解析为相同的 Authorization: Bearer {TOKEN} 请求头，API 密钥也可以作为 apiKey 查询参数传递。

建议：后端服务和脚本使用 API 密钥；当第三方需要在无需共享长期密钥的情况下对用户资源进行范围化访问时，使用 OAuth 2.1。切勿将任一凭证放入客户端代码或提交到代码仓库。1inch 文档明确警告不要在 GitHub 等公共场所暴露密钥。

每个响应都包含 X-Request-Id 请求头。请保存它。当你联系支持或关联日志时，该标识符可让提供商定位确切请求，而无需猜测时间窗口。

curl -s 'https://api.1inch.com/swap/v5.2/1/tokens' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ONEINCH_API_KEY" \
  -D /tmp/headers.txt

grep -i 'x-request-id' /tmp/headers.txt

心智模型：报价、calldata、签名、广播

通过 1inch API 进行的经典聚合器兑换有四个阶段。首先，你请求代币对和数量的报价；API 返回预期输出、路由和价格影响。其次，你请求兑换 calldata，其中编码了路由合约调用、路径和最小输出。第三，你的钱包对交易签名。第四，你通过 RPC 端点广播已签名交易并等待回执。

意图模式改变了形态：不再是链上路由调用，而是你签署一个由求解器填充的订单，从用户角度看是无 Gas 的，并且设计上受 MEV 保护。跨链模式同样使用订单结算而非桥接合约。在两种情况下，1inch API 仍然返回你需要签名的内容，你仍然需要 RPC 端点来读取链状态、检查授权和确认余额。

在代码中保持各阶段分离。报价不是承诺；如果市场变动，calldata 可能过期。在签名前立即重新报价，并将最小输出视为唯一的硬性保证。

可运行流程：报价并构建兑换

以下 Node.js 脚本在以太坊主网上为固定数量请求报价和兑换 calldata。它不签名也不广播；这是有意为之，以便你先检查响应。将 ONEINCH_API_KEY 和代币地址替换为你自己的值。

注意 from 参数：它必须是将要签署交易的地址。如果你传入不同的地址，授权检查和 calldata 可能与你钱包不匹配。

const API = 'https://api.1inch.com/swap/v5.2/1';
const KEY = process.env.ONEINCH_API_KEY;
const FROM = '0xYourWalletAddress';
const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';

async function main() {
  const amount = '1000000000'; // 1000 USDC (6 decimals)
  const q = await fetch(`${API}/quote?fromTokenAddress=${USDC}&toTokenAddress=${WETH}&amount=${amount}`, {
    headers: { Authorization: `Bearer ${KEY}` }
  });
  if (!q.ok) throw new Error(`quote ${q.status} ${await q.text()}`);
  const quote = await q.json();
  console.log('expected WETH:', quote.toTokenAmount, 'impact:', quote.estimatedGas);

  const s = await fetch(`${API}/swap?fromTokenAddress=${USDC}&toTokenAddress=${WETH}&amount=${amount}&fromAddress=${FROM}&slippage=1`, {
    headers: { Authorization: `Bearer ${KEY}` }
  });
  if (!s.ok) throw new Error(`swap ${s.status} ${await s.text()}`);
  const swap = await s.json();
  console.log('to:', swap.tx.to, 'data bytes:', swap.tx.data.length);
  console.log('min out:', swap.toTokenAmount);
}

main().catch(e => { console.error(e); process.exit(1); });

通过你自己的 RPC 端点广播

拿到 calldata 后，交易通过 RPC 端点发送到链上。下面的示例使用 ethers.js 和占位符 RPC_URL。同样的模式也适用于 viem、web3.py 或直接调用 eth_sendRawTransaction。

如果你的应用提交大量兑换，RPC 端点会成为吞吐量和延迟瓶颈。公共端点在拥堵时可能限流或丢弃交易。对于生产兑换流程，具有可预测限制的专用或托管端点是更安全的默认选择；在规划容量时，请参阅专用节点选项和 RPC 定价。

import { JsonRpcProvider, Wallet, Contract } from 'ethers';

const provider = new JsonRpcProvider(process.env.RPC_URL);
const wallet = new Wallet(process.env.PRIVATE_KEY, provider);

async function send(swap) {
  const tx = await wallet.sendTransaction({
    to: swap.tx.to,
    data: swap.tx.data,
    value: BigInt(swap.tx.value ?? '0'),
    gasLimit: BigInt(swap.tx.gas ?? 500000)
  });
  console.log('submitted', tx.hash);
  const receipt = await tx.wait();
  console.log('status', receipt.status, 'block', receipt.blockNumber);
}

export { send };

验证：正确的集成是什么样子

正确的集成会产生 status: 1 的回执、等于或高于报价最小值的 toTokenAmount，以及可与提供商日志关联的 X-Request-Id。在主网之前，请在 API 和你的 RPC 端点都支持的测试网上运行相同流程。为每次测试运行在小表格中记录以下内容；不要猜测数值，要测量它们。

• 客户端测量的报价延迟（毫秒）和兑换 calldata 延迟（毫秒）
• 从 sendTransaction 到交易哈希的 RPC 广播延迟（毫秒）
• 从哈希到回执的确认时间（秒）
• 实际滑点与报价最小输出对比
• 每个非 200 响应的 HTTP 状态和 X-Request-Id

常见故障排查

大多数 1inch API 集成失败分为四类：认证、授权、过期 calldata 和 RPC 提交。认证错误通常返回 401，表示 Bearer 令牌缺失或格式错误。授权错误表现为交易回滚，因为路由合约无法拉取输入代币；在兑换前检查代币合约上的 allowance。

过期 calldata 发生在你报价、等待、然后签名时。市场变动，最小输出不再可实现。在签名前立即重新报价。RPC 提交失败是另一回事：nonce too low、replacement transaction underpriced 或超时通常表明你的节点存在 nonce 或 Gas 价格问题，而不是 1inch API 问题。nonce 解释在这里很有用。

如果 API 返回 429，说明你触发了速率限制。使用抖动退避，并考虑你的套餐限制是否与流量匹配。如果响应是 5xx，捕获 X-Request-Id，并对只读端点进行幂等重试；切勿盲目重试兑换提交。

链覆盖范围与你掌控的 RPC 层

1inch 文档记录了在众多网络上的兑换支持，包括 Ethereum、BNB Chain、Polygon、Optimism、Arbitrum、Gnosis、Avalanche、zkSync Era、Base、Linea、Unichain、Sonic、Solana、Cronos、Monad、HyperEVM 和 Arc，覆盖范围随时间扩大。可用性因端点 and 产品而异，因此请检查当前文档，而不是假设某条链受支持。

对于你启用的每条链，你需要一个匹配的 RPC 端点。这是与 1inch API 分开的供应商决策。如果你正在选择端点，网络目录列出了支持的链，API 服务概览描述了托管访问。对于每条链的具体端点推荐，请使用 RPC Assistant，而不是在此硬编码供应商。

• 将报价请求中的链 ID 与 RPC 端点的链 ID 匹配
• 为每条链保留单独的凭证和速率限制
• 监控每条链的确认延迟；差异很大

限制与权衡

1inch API 是一个托管依赖项。你无法控制其正常运行时间、定价变化或链添加。聚合器模式依赖链上流动性和路由合约；意图和跨链模式依赖求解器参与。这些都不能保证特定成交。

还有隐私和合规维度。一些团队对 API 访问的 KYC 要求提出了疑问；当前条款由 1inch Business 设定，应直接查阅。如果你的应用无法接受托管聚合器依赖，直接从 RPC 端点读取池状态是一种替代方案，但你需要自行负责路由、Gas 估算和 MEV 风险。

最后，API 不能替代节点。你仍然需要可靠的 RPC 访问来获取余额、授权、nonce 和回执。请分别预算两层。

后续步骤

从只读集成开始：代币元数据和现货价格，然后是不签名的报价。一旦这些稳定，再添加兑换 calldata 并在测试网上广播。按阶段监测延迟和错误率，以便区分 API 问题和 RPC 问题。

当你准备投入生产时，请查看 RPC 定价和专用节点选项，并使用 RPC Assistant 为你支持的每条链选择端点。如需更广泛的背景，区块链节点托管指南涵盖了运行或租用节点的运营方面。