Integración de la API de 1inch: Swap, Autenticación y Arquitectura RPC

Qué es realmente la API de 1inch

La API de 1inch es un conjunto de servicios REST y WebSocket alojados operados por 1inch Business. No es un proveedor de nodos ni una blockchain. Es una capa de agregación y datos fuera de la cadena: le envías una solicitud que describe un par de tokens y una cantidad, y devuelve una ruta, una cotización y, por lo general, calldata de transacción listo para firmar. Tu billetera o backend luego firma ese calldata y lo envía a un endpoint RPC de tu elección.

Esa separación es importante para la arquitectura. La API de 1inch decide qué transacción construir; tu endpoint RPC decide si esa transacción llega a la cadena y con qué rapidez. Los equipos que tratan ambos como un solo proveedor a menudo terminan depurando la capa equivocada cuando falla un swap. La guía de endpoints RPC explica el lado del nodo con más profundidad.

La suite es más amplia que los swaps. La documentación pública enumera las API Swap, Orderbook, Balance, Spot Price, Token, Transaction, Portfolio, Gas Price, NFT, Traces, History, Web3 RPC, Domain, Token Details y Charts. La mayoría de las integraciones solo necesitan Swap más uno o dos endpoints de datos.

• API Swap: cotizaciones, calldata y tres modos (agregador, intents, cross-chain)
• API de datos: metadatos de tokens, precios spot, saldos, precio del gas, historial de transacciones
• Autenticación: clave API de portador u OAuth 2.1 (credenciales de cliente o código de autorización con PKCE)
• Transporte: REST sobre HTTPS más WebSocket para algunos endpoints de streaming

Requisitos previos y supuestos

Esta guía asume que tienes una cuenta de 1inch Business con al menos una aplicación y clave API, una billetera con fondos en una cadena compatible y una URL RPC para esa cadena. También asume Node.js 18+ o Python 3.10+ si deseas ejecutar los ejemplos de código. Nada aquí requiere un proveedor RPC específico; los marcadores de posición como RPC_URL son intencionales.

También debes saber qué ID de cadena estás utilizando. La API de 1inch está limitada por cadena en la mayoría de los endpoints, y mezclar IDs de cadena entre la solicitud de cotización y el envío por RPC es uno de los errores de integración más comunes. Si eres nuevo en el acceso a nodos, la guía de endpoints RPC multicadena cubre cómo organizar endpoints por cadena.

Autenticación: claves API versus OAuth 2.1

Comportamiento documentado: la API de 1inch Business admite dos métodos de autenticación. Las claves API son tokens de portador simples destinados a integraciones directas. OAuth 2.1 está destinado a flujos de consentimiento del usuario y acceso servidor a servidor, con credenciales de cliente y código de autorización más PKCE como tipos de concesión admitidos. Ambos se resuelven en el mismo encabezado Authorization: Bearer {TOKEN}, y las claves API también se pueden pasar como parámetro de consulta apiKey.

Recomendación: usa claves API para servicios backend y scripts, y OAuth 2.1 cuando un tercero necesite acceso con alcance a los recursos de un usuario sin compartir un secreto de larga duración. Nunca envíes ninguna de las dos credenciales en código del lado del cliente ni las confirmes en un repositorio. La documentación de 1inch advierte explícitamente contra exponer claves en lugares públicos como GitHub.

Cada respuesta incluye un encabezado X-Request-Id. Guárdalo. Cuando contactes al soporte o correlaciones registros, ese identificador permite al proveedor localizar la solicitud exacta sin adivinar una ventana de tiempo.

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

Modelo mental: cotización, calldata, firma, difusión

Un swap clásico de agregador a través de la API de 1inch tiene cuatro etapas. Primero, solicitas una cotización para un par de tokens y una cantidad; la API devuelve la salida esperada, una ruta y el impacto en el precio. Segundo, solicitas el calldata del swap, que codifica la llamada al router, la ruta y la salida mínima. Tercero, tu billetera firma la transacción. Cuarto, difundes la transacción firmada a través de un endpoint RPC y esperas un recibo.

El modo intents cambia la forma: en lugar de una llamada al router en la cadena, firmas una orden que los solvers completan, lo que no requiere gas desde la perspectiva del usuario y está protegido contra MEV por diseño. El modo cross-chain utiliza de manera similar la liquidación de órdenes en lugar de un contrato puente. En ambos casos, la API de 1inch sigue devolviendo algo que firmas, y sigues necesitando un endpoint RPC para leer el estado de la cadena, verificar allowances y confirmar saldos.

Mantén las etapas separadas en tu código. Una cotización no es un compromiso; el calldata puede quedar obsoleto si el mercado se mueve. Vuelve a cotizar inmediatamente antes de firmar y trata la salida mínima como la única garantía firme.

Procedimiento ejecutable: cotizar y construir un swap

El siguiente script de Node.js solicita una cotización y el calldata de swap para una cantidad fija en la red principal de Ethereum. No firma ni difunde; esto es deliberado para que puedas inspeccionar la respuesta primero. Reemplaza ONEINCH_API_KEY y las direcciones de tokens con tus propios valores.

Observa el parámetro from: debe ser la dirección que firmará la transacción. Si pasas una dirección diferente, la verificación de allowance y el calldata pueden no coincidir con tu billetera.

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); });

Difusión a través de tu propio endpoint RPC

Una vez que tienes el calldata, la transacción va a la cadena a través de un endpoint RPC. El siguiente ejemplo usa ethers.js con un marcador de posición RPC_URL. El mismo patrón funciona con viem, web3.py o una llamada directa a eth_sendRawTransaction.

Si tu aplicación envía muchos swaps, el endpoint RPC se convierte en un cuello de botella de rendimiento y latencia. Un endpoint público puede limitar la tasa o descartar transacciones durante la congestión. Para flujos de swap en producción, un endpoint dedicado o gestionado con límites predecibles es la opción predeterminada más segura; consulta opciones de nodos dedicados y precios de RPC al dimensionar.

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 };

Verificación: cómo se ve una integración correcta

Una integración correcta produce un recibo con status: 1, un toTokenAmount igual o superior al mínimo cotizado y un X-Request-Id que puedes correlacionar con los registros del proveedor. Antes de la red principal, ejecuta el mismo flujo en una testnet donde tanto la API como tu endpoint RPC lo admitan. Registra lo siguiente en una pequeña tabla para cada ejecución de prueba; no adivines valores, mide.

• Latencia de cotización (ms) y latencia del calldata de swap (ms), medidas del lado del cliente
• Latencia de difusión por RPC (ms) desde sendTransaction hasta el hash de la transacción
• Tiempo de confirmación (s) desde el hash hasta el recibo
• Deslizamiento realizado versus salida mínima cotizada
• Estado HTTP y X-Request-Id para cada respuesta que no sea 200

Solución de problemas comunes

La mayoría de los fallos de integración de la API de 1inch se dividen en cuatro categorías: autenticación, allowance, calldata obsoleto y envío por RPC. Los errores de autenticación suelen devolver 401 y significan un token de portador faltante o mal formado. Los errores de allowance se manifiestan como transacciones revertidas porque el router no puede extraer el token de entrada; verifica allowance en el contrato del token antes de hacer swap.

El calldata obsoleto ocurre cuando cotizas, esperas y luego firmas. El mercado se movió y la salida mínima ya no es alcanzable. Vuelve a cotizar inmediatamente antes de firmar. Los fallos de envío por RPC son independientes: nonce too low, replacement transaction underpriced o tiempos de espera suelen indicar un problema de nonce o precio del gas en tu nodo, no un problema de la API de 1inch. La explicación sobre nonces es útil aquí.

Si la API devuelve 429, estás alcanzando un límite de tasa. Retrocede con jitter y considera si los límites de tu plan coinciden con tu tráfico. Si una respuesta es 5xx, captura el X-Request-Id y reintenta de forma idempotente para endpoints de solo lectura; nunca reintentes a ciegas el envío de un swap.

Cobertura de cadenas y la capa RPC que controlas

1inch documenta soporte de swap en una larga lista de redes, incluyendo Ethereum, BNB Chain, Polygon, Optimism, Arbitrum, Gnosis, Avalanche, zkSync Era, Base, Linea, Unichain, Sonic, Solana, Cronos, Monad, HyperEVM y Arc, con cobertura que se expande con el tiempo. La disponibilidad varía según el endpoint y el producto, así que consulta la documentación actual en lugar de asumir que una cadena es compatible.

Para cada cadena que habilites, necesitas un endpoint RPC correspondiente. Esa es una decisión de proveedor separada de la API de 1inch. Si estás eligiendo endpoints, el directorio de redes enumera las cadenas compatibles, y la descripción general del servicio API describe el acceso gestionado. Para una recomendación concreta de endpoint por cadena, usa RPC Assistant en lugar de codificar un proveedor aquí.

• Coincide el ID de cadena en la solicitud de cotización con el ID de cadena de tu endpoint RPC
• Mantén credenciales y límites de tasa separados por cadena
• Monitorea la latencia de confirmación por cadena; varía ampliamente

Limitaciones y compensaciones

La API de 1inch es una dependencia alojada. No controlas su tiempo de actividad, cambios de precios ni adiciones de cadenas. El modo agregador depende de la liquidez en la cadena y los contratos del router; los modos intents y cross-chain dependen de la participación de los solvers. Ninguno de estos es una garantía de una ejecución específica.

También hay una dimensión de privacidad y cumplimiento. Algunos equipos han planteado preguntas sobre los requisitos de KYC para el acceso a la API; los términos actuales los establece 1inch Business y deben revisarse directamente. Si tu aplicación no puede aceptar una dependencia de agregador alojado, leer el estado del pool directamente desde un endpoint RPC es una alternativa, pero entonces asumes el enrutamiento, la estimación de gas y la exposición a MEV.

Finalmente, la API no sustituye a un nodo. Sigues necesitando acceso RPC fiable para saldos, allowances, nonces y recibos. Presupuesta ambas capas por separado.

Próximos pasos

Comienza con una integración de solo lectura: metadatos de tokens y precios spot, luego cotizaciones sin firmar. Una vez que esos sean estables, agrega el calldata de swap y la difusión en una testnet. Instrumenta la latencia y las tasas de error por etapa para que puedas distinguir un problema de API de un problema de RPC.

Cuando estés listo para pasar a producción, revisa las opciones de precios de RPC y nodo dedicado, y usa RPC Assistant para elegir endpoints para cada cadena que admitas. Para obtener antecedentes más amplios, la guía de alojamiento de nodos blockchain cubre el lado operativo de ejecutar o alquilar nodos.