EOA Swap example

EOA Swap flow

A standard wallet swap (MetaMask, WalletConnect, or any EOA signer) in six steps:

1. Fetch supported networks and tokens

2. Find a route

3. Approve token spending (ERC-20 only)

4. Send swap transaction

5. Extract requestId from receipt

6. Poll for completion

Step 1: Get Networks and Tokens

GET /networks

Returns an object keyed by network name. Each entry contains the chain configuration and supported tokens.

{
  "sepolia": {
    "name": "sepolia",
    "chainId": 11155111,
    "router": "0x...",
    "tokens": [
      {
        "chainId": 11155111,
        "address": "0x...",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "tags": ["erc20", "stable"],
        "permit": false
      }
    ]
  }
}

Use chainId and token address values from this response when building a scan request.

Step 2: Find a Route

POST /routing/scan/stream

Request body:

{
  "from": "0xYOUR_WALLET_ADDRESS",
  "recipient": "0xRECIPIENT_ADDRESS",
  "params": {
    "tokenIn": "0xTOKEN_IN",
    "amountIn": "1000000",
    "chainIdIn": 11155111,
    "tokenOut": "0xTOKEN_OUT",
    "chainIdOut": 64165
  },
  "slippage": 1
}

Field	Type	Required	Description
from	string	Yes	Sender address
recipient	string	No	Recipient address (defaults to sender)
params.tokenIn	string	Yes	Input token address
params.amountIn	string	Yes	Amount in smallest token units
params.chainIdIn	number	Yes	Source chain ID
params.tokenOut	string	Yes	Output token address
params.chainIdOut	number	Yes	Destination chain ID
slippage	number	Yes	Slippage tolerance in percent
feeShareBps	number	No	Partner fee in basis points (100 = 1%)
providers	string[]	No	Filter by provider: "cross-curve", "rubic", "bungee"

The response is NDJSON — each line is a separate JSON object:

Success line:

{ "route": [...], "simulation": { /* route object — see Routing Response */ } }

Error line (route could not be evaluated):

{ "route": [...], "error": "error message" }

Collect the simulation objects from success lines. Routes arrive in arbitrary order, so sort by amountOut descending to find the best route and pass it to the next step.

You can also use POST /routing/scan which returns all routes as a single JSON array. The request body is the same. Each array item has the same shape as the simulation object above.

Step 3: Build the Transaction

POST /tx/create

Request body:

{
  "from": "0xYOUR_WALLET_ADDRESS",
  "recipient": "0xRECIPIENT_ADDRESS",
  "routing": { },
  "buildCalldata": true
}

Field	Type	Required	Description
from	string	Yes	Sender address
recipient	string	Yes	Recipient address
routing	object	Yes	The simulation object from /routing/scan/stream (or array item from /routing/scan)
buildCalldata	boolean	No	When true, returns encoded calldata ready to send

Pass the entire route object as routing. Do not modify or cherry-pick fields from it.

Response when buildCalldata is true:

{
  "to": "0xROUTER_ADDRESS",
  "data": "0xENCODED_CALLDATA...",
  "value": "0"
}

Response when buildCalldata is false or omitted:

{
  "to": "0xROUTER_ADDRESS",
  "abi": "[...]",
  "args": [...],
  "value": "0"
}

Step 3: Approve Token Spending (ERC-20 only)

If the input token is an ERC-20 (not the native token), approve the router contract to spend your tokens before sending the swap transaction. The router address is the to field from the /tx/create response.

// Check current allowance
const allowance = await tokenContract.allowance(walletAddress, tx.to);

if (allowance < BigInt(route.amountIn)) {
  await tokenContract.approve(tx.to, route.amountIn);
}

Skip this step if the input token is the chain's native token (ETH, MATIC, etc.) — native tokens do not require approval.

For ERC-4337 and EIP-7702 wallets, the approval is already included in the calls[] array returned by /tx/create. This step applies only to EOA transactions.

Step 4: Send Swap Transaction

Send the transaction on-chain using your wallet or signer.

Step 5: Extract requestId

After the transaction is confirmed, extract the requestId from the ComplexOpProcessed event in the receipt:

const COMPLEX_OP_TOPIC = "0x830adbcf80ee865e0f0883ad52e813fdbf061b0216b724694a2b4e06708d243c";
const log = receipt.logs.find((l) => l.topics[0] === COMPLEX_OP_TOPIC);
const requestId = log.topics[2]; // currentRequestId (bytes32)

Step 6: Poll for Completion

Poll GET /transaction/{requestId} until the status reaches a final state.

See Transaction Tracking for response format and polling recommendations.

Full Example (JavaScript + ethers.js)

import { ethers } from "ethers";

const API = "https://api.crosscurve.fi";
const API_KEY = "YOUR_API_KEY";

const provider = new ethers.JsonRpcProvider("https://YOUR_RPC_URL");
const signer = new ethers.Wallet("0xYOUR_PRIVATE_KEY", provider);
const WALLET_ADDRESS = signer.address;

const TOKEN_IN = "0xTOKEN_IN";
const TOKEN_OUT = "0xTOKEN_OUT";
const CHAIN_ID_IN = 11155111;
const CHAIN_ID_OUT = 64165;
const AMOUNT_IN = "1000000"; // in smallest token units

const ERC20_ABI = [
  "function approve(address spender, uint256 amount) returns (bool)",
  "function allowance(address owner, address spender) view returns (uint256)",
];

// Helper: parse NDJSON stream into an array of route objects
async function scanRoutes(body) {
  const response = await fetch(`${API}/routing/scan/stream`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/x-ndjson",
      "api-key": API_KEY,
    },
    body: JSON.stringify(body),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  const routes = [];
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    let idx;
    while ((idx = buffer.indexOf("\n")) >= 0) {
      const line = buffer.slice(0, idx).trim();
      buffer = buffer.slice(idx + 1);
      if (!line) continue;
      const parsed = JSON.parse(line);
      if (parsed.simulation) routes.push(parsed.simulation);
    }
  }
  if (buffer.trim()) {
    const parsed = JSON.parse(buffer);
    if (parsed.simulation) routes.push(parsed.simulation);
  }

  return routes;
}

// Step 1: Find a route
const routes = await scanRoutes({
  from: WALLET_ADDRESS,
  recipient: WALLET_ADDRESS,
  params: {
    tokenIn: TOKEN_IN,
    amountIn: AMOUNT_IN,
    chainIdIn: CHAIN_ID_IN,
    tokenOut: TOKEN_OUT,
    chainIdOut: CHAIN_ID_OUT,
  },
  slippage: 1,
});
routes.sort((a, b) => {
  if (BigInt(a.amountOut) > BigInt(b.amountOut)) return -1;
  if (BigInt(a.amountOut) < BigInt(b.amountOut)) return 1;
  return 0;
});
const route = routes[0];

// Step 2: Build the transaction
const txRes = await fetch(`${API}/tx/create`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    from: WALLET_ADDRESS,
    recipient: WALLET_ADDRESS,
    routing: route,
    buildCalldata: true,
  }),
});
const tx = await txRes.json();

// Step 3: Approve router if input is ERC-20 (skip for native token)
const tokenContract = new ethers.Contract(TOKEN_IN, ERC20_ABI, signer);
const allowance = await tokenContract.allowance(WALLET_ADDRESS, tx.to);
if (allowance < BigInt(route.amountIn)) {
  const approveTx = await tokenContract.approve(tx.to, route.amountIn);
  await approveTx.wait();
}

// Step 4: Send swap on-chain
const swapTx = await signer.sendTransaction({
  to: tx.to,
  data: tx.data,
  value: tx.value,
});
const receipt = await swapTx.wait();

// Step 5: Extract requestId from receipt
const COMPLEX_OP_TOPIC = "0x830adbcf80ee865e0f0883ad52e813fdbf061b0216b724694a2b4e06708d243c";
const log = receipt.logs.find((l) => l.topics[0] === COMPLEX_OP_TOPIC);
const requestId = log.topics[2]; // currentRequestId (bytes32)

// Step 6: Poll for completion
async function pollStatus(requestId) {
  while (true) {
    const res = await fetch(`${API}/transaction/${requestId}`);
    const status = await res.json();

    console.log("Status:", status.status);

    if (["completed", "failed", "reverted", "canceled"].includes(status.status)) {
      return status;
    }

    await new Promise((r) => setTimeout(r, 12000));
  }
}

const result = await pollStatus(requestId);
console.log("Final status:", result.status);

Full Example (TypeScript + viem)

import { createWalletClient, createPublicClient, http, parseAbi, parseEventLogs } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";

const API = "https://api.crosscurve.fi";
const API_KEY = "YOUR_API_KEY";

const TOKEN_IN = "0xTOKEN_IN";
const TOKEN_OUT = "0xTOKEN_OUT";
const CHAIN_ID_IN = 11155111;
const CHAIN_ID_OUT = 64165;
const AMOUNT_IN = "1000000";

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const walletClient = createWalletClient({
  account,
  chain: sepolia,
  transport: http(),
});

// Helper: parse NDJSON stream into an array of route objects
async function scanRoutes(body: Record<string, unknown>) {
  const response = await fetch(`${API}/routing/scan/stream`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/x-ndjson",
      "api-key": API_KEY,
    },
    body: JSON.stringify(body),
  });

  const reader = response.body!.getReader();
  const decoder = new TextDecoder();
  const routes: unknown[] = [];
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    let idx: number;
    while ((idx = buffer.indexOf("\n")) >= 0) {
      const line = buffer.slice(0, idx).trim();
      buffer = buffer.slice(idx + 1);
      if (!line) continue;
      const parsed = JSON.parse(line);
      if (parsed.simulation) routes.push(parsed.simulation);
    }
  }
  if (buffer.trim()) {
    const parsed = JSON.parse(buffer);
    if (parsed.simulation) routes.push(parsed.simulation);
  }

  return routes;
}

// Step 1: Find a route
const routes = await scanRoutes({
  from: account.address,
  recipient: account.address,
  params: {
    tokenIn: TOKEN_IN,
    amountIn: AMOUNT_IN,
    chainIdIn: CHAIN_ID_IN,
    tokenOut: TOKEN_OUT,
    chainIdOut: CHAIN_ID_OUT,
  },
  slippage: 1,
});
routes.sort((a: any, b: any) => {
  if (BigInt(a.amountOut) > BigInt(b.amountOut)) return -1;
  if (BigInt(a.amountOut) < BigInt(b.amountOut)) return 1;
  return 0;
});
const route = routes[0];

// Step 2: Build the transaction
const txRes = await fetch(`${API}/tx/create`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    from: account.address,
    recipient: account.address,
    routing: route,
    buildCalldata: true,
  }),
});
const tx: { to: string; data: string; value: string } = await txRes.json();

// Step 3: Approve router if input is ERC-20 (skip for native token)
const erc20Abi = parseAbi([
  "function approve(address,uint256) returns (bool)",
  "function allowance(address,address) view returns (uint256)",
]);
const allowance = await publicClient.readContract({
  address: TOKEN_IN as `0x${string}`,
  abi: erc20Abi,
  functionName: "allowance",
  args: [account.address, tx.to as `0x${string}`],
});
if (allowance < BigInt(route.amountIn)) {
  await walletClient.writeContract({
    address: TOKEN_IN as `0x${string}`,
    abi: erc20Abi,
    functionName: "approve",
    args: [tx.to as `0x${string}`, BigInt(route.amountIn)],
  });
}

// Step 4: Send swap on-chain
const hash = await walletClient.sendTransaction({
  to: tx.to as `0x${string}`,
  data: tx.data as `0x${string}`,
  value: BigInt(tx.value),
});

console.log("Transaction sent:", hash);

// Step 5: Extract requestId from receipt
const receipt = await publicClient.waitForTransactionReceipt({ hash });
const complexOpAbi = parseAbi([
  "event ComplexOpProcessed(uint64 indexed currentChainId, bytes32 indexed currentRequestId, uint64 indexed nextChainId, bytes32 nextRequestId, uint8 result, uint8 lastOp)",
]);
const events = parseEventLogs({ abi: complexOpAbi, logs: receipt.logs, eventName: "ComplexOpProcessed" });
const requestId = events[0].args.currentRequestId;

// Step 6: Poll for completion
async function pollStatus(requestId: string) {
  while (true) {
    const res = await fetch(`${API}/transaction/${requestId}`);
    const status = await res.json();

    console.log("Status:", status.status);

    if (["completed", "failed", "reverted", "canceled"].includes(status.status)) {
      return status;
    }

    await new Promise((r) => setTimeout(r, 12000));
  }
}

---