1inch API Integration: Swap, Auth, and RPC Architecture

What the 1inch API actually is

The 1inch API is a set of hosted REST and WebSocket services operated by 1inch Business. It is not a node provider and it is not a blockchain. It is an off-chain aggregation and data layer: you send it a request describing a token pair and amount, and it returns a route, a quote, and usually ready-to-sign transaction calldata. Your wallet or backend then signs that calldata and submits it to an RPC endpoint of your choosing.

That separation matters for architecture. The 1inch API decides what transaction to build; your RPC endpoint decides whether and how fast that transaction reaches the chain. Teams that treat both as one vendor often end up debugging the wrong layer when a swap fails. The RPC endpoints guide explains the node side in more depth.

The suite is broader than swaps. Public documentation lists Swap, Orderbook, Balance, Spot Price, Token, Transaction, Portfolio, Gas Price, NFT, Traces, History, Web3 RPC, Domain, Token Details, and Charts APIs. Most integrations only need Swap plus one or two data endpoints.

• Swap API: quotes, calldata, and three modes (aggregator, intents, cross-chain)
• Data APIs: token metadata, spot prices, balances, gas price, transaction history
• Auth: bearer API key or OAuth 2.1 (client credentials or authorization code with PKCE)
• Transport: HTTPS REST plus WebSocket for some streaming endpoints

Prerequisites and assumptions

This guide assumes you have a 1inch Business account with at least one application and API key, a funded wallet on a supported chain, and an RPC URL for that chain. It also assumes Node.js 18+ or Python 3.10+ if you want to run the code samples. Nothing here requires a specific RPC vendor; placeholders like RPC_URL are intentional.

You should also know which chain ID you are targeting. The 1inch API is chain-scoped in most endpoints, and mixing chain IDs between the quote request and the RPC submission is one of the most common integration bugs. If you are new to node access, the multi-chain RPC endpoints guide covers how to organize endpoints per chain.

Authentication: API keys versus OAuth 2.1

Documented behavior: the 1inch Business API supports two authentication methods. API keys are simple bearer tokens intended for direct integrations. OAuth 2.1 is intended for user-consent flows and server-to-server access, with client credentials and authorization code plus PKCE as supported grant types. Both resolve to the same Authorization: Bearer {TOKEN} header, and API keys can alternatively be passed as an apiKey query parameter.

Recommendation: use API keys for backend services and scripts, and OAuth 2.1 when a third party needs scoped access to a user's resources without sharing a long-lived secret. Never ship either credential in client-side code or commit it to a repository. The 1inch documentation explicitly warns against exposing keys in public places such as GitHub.

Every response includes an X-Request-Id header. Save it. When you contact support or correlate logs, that identifier lets the provider locate the exact request without guessing a time window.

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

Mental model: quote, calldata, signature, broadcast

A classic aggregator swap through the 1inch API has four stages. First, you request a quote for a token pair and amount; the API returns expected output, a route, and price impact. Second, you request swap calldata, which encodes the router call, the path, and the minimum output. Third, your wallet signs the transaction. Fourth, you broadcast the signed transaction through an RPC endpoint and wait for a receipt.

The intents mode changes the shape: instead of an on-chain router call, you sign an order that solvers fill, which is gasless from the user's perspective and MEV-protected by design. The cross-chain mode similarly uses order settlement rather than a bridge contract. In both cases the 1inch API still returns something you sign, and you still need an RPC endpoint to read chain state, check allowances, and confirm balances.

Keep the stages separate in your code. A quote is not a commitment; calldata can go stale if the market moves. Re-quote immediately before signing, and treat the minimum output as the only hard guarantee.

Runnable procedure: quote and build a swap

The following Node.js script requests a quote and swap calldata for a fixed amount on Ethereum mainnet. It does not sign or broadcast; that is deliberate so you can inspect the response first. Replace ONEINCH_API_KEY and the token addresses with your own values.

Note the from parameter: it must be the address that will sign the transaction. If you pass a different address, the allowance check and calldata may not match your wallet.

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

Broadcasting through your own RPC endpoint

Once you have calldata, the transaction goes to the chain through an RPC endpoint. The example below uses ethers.js with a placeholder RPC_URL. The same pattern works with viem, web3.py, or a raw eth_sendRawTransaction call.

If your application submits many swaps, the RPC endpoint becomes a throughput and latency bottleneck. A public endpoint may rate-limit or drop transactions during congestion. For production swap flows, a dedicated or managed endpoint with predictable limits is the safer default; see dedicated node options and RPC pricing when sizing.

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

Verification: what a correct integration looks like

A correct integration produces a receipt with status: 1, a toTokenAmount at or above the quoted minimum, and an X-Request-Id you can correlate with provider logs. Before mainnet, run the same flow on a testnet where the API and your RPC endpoint both support it. Record the following in a small table for each test run; do not guess values, measure them.

• Quote latency (ms) and swap-calldata latency (ms), measured client-side
• RPC broadcast latency (ms) from sendTransaction to transaction hash
• Confirmation time (s) from hash to receipt
• Slippage realized versus quoted minimum output
• HTTP status and X-Request-Id for every non-200 response

Troubleshooting common failures

Most 1inch API integration failures fall into four buckets: authentication, allowance, stale calldata, and RPC submission. Authentication errors usually return 401 and mean a missing or malformed bearer token. Allowance errors surface as reverted transactions because the router cannot pull the input token; check allowance on the token contract before swapping.

Stale calldata happens when you quote, wait, then sign. The market moved and the minimum output is no longer achievable. Re-quote immediately before signing. RPC submission failures are separate: nonce too low, replacement transaction underpriced, or timeouts usually indicate a nonce or gas-price problem on your node, not a 1inch API problem. The nonce explainer is useful here.

If the API returns 429, you are hitting a rate limit. Back off with jitter and consider whether your plan's limits match your traffic. If a response is a 5xx, capture the X-Request-Id and retry idempotently for read-only endpoints; never blindly retry a swap submission.

Chain coverage and the RPC layer you control

1inch documents swap support across a long list of networks, including Ethereum, BNB Chain, Polygon, Optimism, Arbitrum, Gnosis, Avalanche, zkSync Era, Base, Linea, Unichain, Sonic, Solana, Cronos, Monad, HyperEVM, and Arc, with coverage expanding over time. Availability differs by endpoint and by product, so check the current documentation rather than assuming a chain is supported.

For each chain you enable, you need a matching RPC endpoint. That is a separate vendor decision from the 1inch API. If you are choosing endpoints, the networks directory lists supported chains, and the API service overview describes managed access. For a concrete endpoint recommendation per chain, use RPC Assistant rather than hardcoding a provider here.

• Match chain ID in the quote request to the chain ID of your RPC endpoint
• Keep separate credentials and rate limits per chain
• Monitor confirmation latency per chain; it varies widely

Limitations and tradeoffs

The 1inch API is a hosted dependency. You do not control its uptime, pricing changes, or chain additions. The aggregator mode depends on on-chain liquidity and router contracts; the intents and cross-chain modes depend on solver participation. None of these are guarantees of a specific fill.

There is also a privacy and compliance dimension. Some teams have raised questions about KYC requirements for API access; the current terms are set by 1inch Business and should be reviewed directly. If your application cannot accept a hosted aggregator dependency, reading pool state directly from an RPC endpoint is an alternative, but you then own routing, gas estimation, and MEV exposure.

Finally, the API is not a substitute for a node. You still need reliable RPC access for balances, allowances, nonces, and receipts. Budget for both layers separately.

Next steps

Start with a read-only integration: token metadata and spot prices, then quotes without signing. Once those are stable, add swap calldata and broadcast on a testnet. Instrument latency and error rates per stage so you can tell an API problem from an RPC problem.

When you are ready to productionize, review RPC pricing and dedicated node options, and use RPC Assistant to pick endpoints for each chain you support. For broader background, the blockchain node hosting guide covers the operational side of running or renting nodes.