Integration Guide

Base URL: https://api.crosscurve.fi Swagger UI: https://api.crosscurve.fi/api-docs/ General Documentation: https://docs.crosscurve.fi

Quick Start

Minimum Integration Flow

Follow these steps to perform a cross-chain swap.

GET /networks — Get list of networks and contract addresses
GET /tokenlist — Get list of tokens (filter: can_swap)
POST /routing/scan — Find swap route
POST /estimate — Get estimate and signature
POST /tx/create — Build transaction
[Approve token] — Allow contract to use tokens (if not already done)
[Send TX] — Sign and send via ethers/web3
GET /search?search= — Get requestId by hash (wait ~3 sec)
GET /transaction/{id} — Track status until completed

Example: Swap CRV (Ethereum) → CRV (Arbitrum)

Example for understanding the flow. Verify current addresses via /tokenlist.

import { ethers } from 'ethers';

const API_BASE = 'https://api.crosscurve.fi';

// Initialize provider and signer (example for browser with MetaMask)
const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();

// 1. Find route
const routeResponse = await fetch(`${API_BASE}/routing/scan`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    params: {
      chainIdIn: 1,           // Ethereum
      chainIdOut: 42161,      // Arbitrum
      tokenIn: '0xD533a949740bb3306d119CC777fa900bA034cd52',   // CRV on Ethereum
      tokenOut: '0x11cDb42B0EB46D95f990BeDD4695A6e3fA034978',  // CRV on Arbitrum
      amountIn: '1000000000000000000000'  // 1000 CRV (18 decimals)
    },
    slippage: 1  // 1%
  })
});

const routes = await routeResponse.json();
if (!routes.length) {
  throw new Error('No routes available for this pair');
}

const selectedRoute = routes[0]; // first route from list
console.log(`Expected output: ${selectedRoute.amountOut}`);
console.log(`Price impact: ${selectedRoute.priceImpact}%`);
console.log(`Fee: ${selectedRoute.totalFee.percent}%`);

// 2. Get estimate
const estimateResponse = await fetch(`${API_BASE}/estimate`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(selectedRoute)
});

const estimate = await estimateResponse.json();

// 3. Build transaction
// buildCalldata: true — returns ready calldata for sendTransaction
const txResponse = await fetch(`${API_BASE}/tx/create`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from: '0xYourWalletAddress',      // With correct checksum!
    recipient: '0xRecipientAddress',  // Can match from
    routing: selectedRoute,
    estimate: estimate,
    buildCalldata: true               // Get ready calldata
  })
});

const txData = await txResponse.json();
// txData: { to, value, data } — ready for sendTransaction

// 4. Approve tokens (check allowance to avoid unnecessary TX)
const tokenContract = new ethers.Contract(
  '0xD533a949740bb3306d119CC777fa900bA034cd52', // CRV token
  ['function approve(address spender, uint256 amount) returns (bool)',
   'function allowance(address owner, address spender) view returns (uint256)'],
  signer
);
const ownerAddress = await signer.getAddress();
const allowance = await tokenContract.allowance(ownerAddress, txData.to);
if (allowance.lt('1000000000000000000000')) { // if allowance < amountIn
  await tokenContract.approve(txData.to, ethers.constants.MaxUint256);
  console.log('Token approved');
}

// 5. Send transaction to blockchain
const tx = await signer.sendTransaction({
  to: txData.to,
  data: txData.data,
  value: txData.value || '0'
});
console.log(`TX sent: ${tx.hash}`);

const receipt = await tx.wait();
console.log(`TX confirmed in block: ${receipt.blockNumber}`);

// 6. Get requestId
// Option A: via API (wait for indexing ~3 sec)
await new Promise(r => setTimeout(r, 3000));
const searchResponse = await fetch(`${API_BASE}/search?search=${tx.hash}`);
const searchResult = await searchResponse.json();
let requestId = searchResult.result[0]?.requestId;

// Option B: from transaction events (faster, no waiting)
if (!requestId) {
  const COMPLEX_OP_TOPIC = '0x830adbcf80ee865e0f0883ad52e813fdbf061b0216b724694a2b4e06708d243c';
  const log = receipt.logs.find(l => l.topics[0] === COMPLEX_OP_TOPIC);
  if (log) {
    // Decode event to get nextRequestId
    const iface = new ethers.utils.Interface([
      'event ComplexOpProcessed(uint64 indexed currentChainId, bytes32 indexed currentRequestId, uint64 nextChainId, bytes32 nextRequestId, uint8 result, uint8 lastOp)'
    ]);
    const decoded = iface.parseLog(log);
    requestId = decoded.args.nextRequestId;
  }
}

console.log(`RequestId: ${requestId}`);

// 7. Track status (polling every 5 sec)
let status;
for (let i = 0; i < 60; i++) { // max 5 minutes
  const statusResponse = await fetch(`${API_BASE}/transaction/${requestId}`);
  status = await statusResponse.json();
  console.log(`Status: ${status.status}`);

  if (status.status === 'completed') {
    console.log('Swap completed!');
    break;
  }
  if (status.inconsistency) {
    console.log('Refund required, see /inconsistency');
    break;
  }
  if (status.destination?.emergency) {
    console.log('Recovery required, see /tx/create/emergency');
    break;
  }

  await new Promise(r => setTimeout(r, 5000)); // wait 5 sec
}

Important: Addresses must be in checksum format (EIP-55). Use ethers.utils.getAddress(address) for conversion.

Test Examples

Source Network

Target Network

Token In

Token Out

Ethereum (1)

Arbitrum (42161)

CRV

Optimism (10)

Arbitrum (42161)

USDC

Arbitrum (42161)

Polygon (137)

USDT

Get token addresses from /tokenlist.

If No Route Found

If /routing/scan returns an empty array []:

Check that tokens have the can_swap tag
Try changing the amount (too small/large)
Try a different token pair
Route requires liquidity in supported pools

cURL Examples for Quick Testing

Test the API without writing code:

# 1. Get list of networks
curl -s "https://api.crosscurve.fi/networks?type=0" | jq 'keys'

# 2. Get tokens
curl -s "https://api.crosscurve.fi/tokenlist" | jq '.ethereum.tokens[:3]'

# 3. Find route (Ethereum CRV → Arbitrum CRV)
curl -X POST "https://api.crosscurve.fi/routing/scan" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "chainIdIn": 1,
      "chainIdOut": 42161,
      "tokenIn": "0xD533a949740bb3306d119CC777fa900bA034cd52",
      "tokenOut": "0x11cDb42B0EB46D95f990BeDD4695A6e3fA034978",
      "amountIn": "1000000000000000000000"
    },
    "slippage": 1
  }' | jq '.[0] | {amountIn, amountOut, priceImpact}'

# 4. Get estimate (substitute result from routing/scan)
curl -X POST "https://api.crosscurve.fi/estimate" \
  -H "Content-Type: application/json" \
  -d '<ROUTE_FROM_STEP_3>' | jq '{deadline, fee, slippage}'

# 5. Check transaction status
curl -s "https://api.crosscurve.fi/transaction/<REQUEST_ID>" | jq '{status, inconsistency}'

# 6. Get token price
curl -s "https://api.crosscurve.fi/prices/0xD533a949740bb3306d119CC777fa900bA034cd52/1"

Integration Architecture

Process Diagram

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│     Your     │────▶│  CrossCurve  │────▶│  Blockchain  │
│ Application  │◀────│     API      │◀────│   (Source)   │
└──────────────┘     └──────────────┘     └──────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │    Oracle    │
                     │   Network    │
                     └──────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │  Blockchain  │
                     │ (Destination)│
                     └──────────────┘

Cross-Chain Swap Stages

Stage

Description

API / Action

Discovery

Get reference data

GET /networks, GET /tokenlist

Routing

Find available routes

POST /routing/scan

Estimation

Calculate fees and signature

POST /estimate

Transaction

Build calldata

POST /tx/create

Approval

Allow token spending

token.approve() (ERC-20)

Execution

Send transaction

signer.sendTransaction()

Lookup

Get requestId

GET /search?search={txHash}

Tracking

Track status

GET /transaction/{requestId}

Supported Networks

Get current list via GET /networks. Examples:

Network

Chain ID

API Name

Ethereum

ethereum

Arbitrum

42161

arbitrum

Optimism

optimism

Polygon

137

polygon

BSC

bsc

20+ EVM networks supported. See /networks for current list.

Reference Data

GET /networks

Get list of supported blockchain networks.

Query Parameters:

Parameter

Type

Description

type

number

Filter: 0 - mainnet, 1 - testnet

Example Request:

curl "https://api.crosscurve.fi/networks?type=0"

Example Response:

{
  "ethereum": {
    "name": "ethereum",
    "chainId": 1,
    "symbol": "ETH",
    "portal": "0x...",
    "synthesis": "0x...",
    "router": "0x...",
    "tokens": [...]
  }
}

Important: Keys are network names (ethereum), not chainId.

GET /tokenlist

Get list of tokens.

Example Request:

curl "https://api.crosscurve.fi/tokenlist"

Example Response:

{
  "ethereum": {
    "tags": ["erc20", "native", "stable", "can_swap", ...],
    "tokens": [
      {
        "chainId": 1,
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "symbol": "USDC",
        "decimals": 6,
        "tags": ["erc20", "stable", "can_swap"],
        "permit": false
      }
    ]
  }
}

Important: Keys are network names. For swaps, check that token has can_swap tag.

Main Token Tags:

Tag

Description

can_swap

Available for cross-chain swap

stable

Stablecoin

native

Native network token (ETH, BNB...)

wrapped_native

Wrapped version (WETH, WBNB...)

curve_lp

Curve LP token

GET /prices/{token}

Get token price in USD.

Path Parameters:

Parameter

Type

Description

token

string

Token address (checksum)

Important: Use token address, not symbol. Symbols (USDC, CRV) are not supported. Recommended to use /prices/{token}/{chainId} for unambiguity.

Example:

curl "https://api.crosscurve.fi/prices/0xD533a949740bb3306d119CC777fa900bA034cd52"

# Response: "0.360043"

GET /prices/{token}/{chainId}

Get token price in specific network.

Example:

curl "https://api.crosscurve.fi/prices/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/1"

Example Response: 0.999827 (number, price in USD)

POST /prices

Batch get prices for multiple tokens.

Request Body:

{
  "tokens": [
    {"address": "0xD533a949740bb3306d119CC777fa900bA034cd52", "chainId": 1},
    {"address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "chainId": 42161}
  ]
}

Response:

[
  {"address": "0xD533a949740bb3306d119CC777fa900bA034cd52", "price": 0.35226},
  {"address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "price": 0.999835}
]

Executing Cross-Chain Swaps

POST /routing/scan

Find available routes for swap.

Request Body:

{
  "params": {
    "chainIdIn": 1,
    "chainIdOut": 42161,
    "tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "tokenOut": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "amountIn": "1000000000"
  },
  "slippage": 0.5
}

Parameters:

Field

Type

Required

Description

params.chainIdIn

number

Yes

Source chain ID

params.chainIdOut

number

Yes

Target chain ID

params.tokenIn

string

Yes

Source token address

params.tokenOut

string

Yes

Target token address

params.amountIn

string

Yes

Amount in smallest units

slippage

number

Yes

Allowed slippage (%)

Response:

[
  {
    "query": {
      "params": { ... },
      "slippage": 0.5
    },
    "route": [...],
    "amountIn": "1000000000",
    "amountOut": "998500000",
    "amountOutWithoutSlippage": "1003500000",
    "tokenInPrice": 1.0,
    "tokenOutPrice": 0.9998,
    "priceImpact": 0.15,
    "totalFee": {
      "type": "aggregation",
      "amount": "1500000",
      "percent": "0.15"
    },
    "txs": [
      {
        "chainId": 1,
        "gasFeeNative": "0.005",
        "gasFeeUsd": 12.5,
        "gasConsumption": 250000
      }
    ],
    "expectedFinalitySeconds": "180"
  }
]

Empty array [] — no route found. See If No Route Found.

POST /estimate

Get operation estimate with signature for execution.

Request Body: Route object from /routing/scan

Response:

{
  "priceInDollars": "1000.00",
  "stablePrice": "1000000000",
  "executionPrice": "998500000",
  "workerFee": "1500000",
  "deadline": "1703001600",
  "signature": "0x..."
}

POST /tx/create

Build transaction data for blockchain submission.

Request Body:

{
  "from": "0xYourAddress",
  "recipient": "0xRecipientAddress",
  "routing": { /* object from /routing/scan */ },
  "estimate": { /* object from /estimate */ },
  "permit": {
    "v": 28,
    "r": "0x...",
    "s": "0x..."
  },
  "buildCalldata": true
}

Parameters:

Field

Type

Required

Description

from

string

Yes

Sender address

recipient

string

Yes

Recipient address

routing

object

Yes

Route from /routing/scan

estimate

object

Yes

Estimate from /estimate

permit

object

EIP-2612 permit signature

buildCalldata

boolean

Build calldata

Response (with buildCalldata: true): — recommended

{
  "to": "0xContractAddress",
  "value": "0",
  "data": "0x..."
}

Ready for sendTransaction({ to, data, value }).

Response (without buildCalldata):

{
  "to": "0xContractAddress",
  "value": "0",
  "args": [["LM", "S", "BU"], ["0x...", ...], { executionPrice, deadline, v, r, s }],
  "abi": "function start(string[],bytes[],tuple(...)) payable"
}

Requires call via ethers.Contract.

Token Approval

Before executing a swap, you must allow the CrossCurve contract to use your tokens.

Where to get spenderAddress? Use txData.to from /tx/create response — this is the contract address that will spend your tokens.

Standard Approve (ERC-20)

import { ethers } from 'ethers';

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

async function approveToken(
  tokenAddress: string,
  spenderAddress: string,  // txData.to from /tx/create
  amount: string,
  signer: ethers.Signer
) {
  const token = new ethers.Contract(tokenAddress, ERC20_ABI, signer);
  const ownerAddress = await signer.getAddress();

  // Check current allowance
  const currentAllowance = await token.allowance(ownerAddress, spenderAddress);

  if (currentAllowance.gte(amount)) {
    console.log('Allowance already sufficient');
    return;
  }

  // Approve maximum amount (or specific)
  const tx = await token.approve(spenderAddress, ethers.constants.MaxUint256);
  await tx.wait();

  console.log('Token approved');
}

Permit (EIP-2612) - Approve via Signature

If token supports EIP-2612 (permit: true field in tokenlist), you can use a signature instead of approve transaction.

async function signPermit(
  tokenAddress: string,
  spenderAddress: string,
  amount: string,
  deadline: number,
  signer: ethers.Signer
) {
  const token = new ethers.Contract(tokenAddress, [
    'function name() view returns (string)',
    'function nonces(address owner) view returns (uint256)',
    'function DOMAIN_SEPARATOR() view returns (bytes32)'
  ], signer);

  const owner = await signer.getAddress();
  const nonce = await token.nonces(owner);
  const name = await token.name();
  const chainId = await signer.getChainId();

  const domain = {
    name: name,
    version: '1',
    chainId: chainId,
    verifyingContract: tokenAddress
  };

  const types = {
    Permit: [
      { name: 'owner', type: 'address' },
      { name: 'spender', type: 'address' },
      { name: 'value', type: 'uint256' },
      { name: 'nonce', type: 'uint256' },
      { name: 'deadline', type: 'uint256' }
    ]
  };

  const value = {
    owner: owner,
    spender: spenderAddress,
    value: amount,
    nonce: nonce.toNumber(),
    deadline: deadline
  };

  const signature = await signer._signTypedData(domain, types, value);
  const { v, r, s } = ethers.utils.splitSignature(signature);

  return { v, r, s };
}

// Using permit in /tx/create
// deadline taken from /estimate response
const permit = await signPermit(tokenIn, txData.to, amountIn, Number(estimate.deadline), signer);

const txResponse = await fetch(`${API_BASE}/tx/create`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from: walletAddress,
    recipient: walletAddress,
    routing: route,
    estimate: estimate,
    permit: permit  // <-- Pass permit signature
  })
});

Transaction Tracking

GET /transaction/{requestId}

Get cross-chain transaction status.

Parameters:

Parameter

Type

Description

requestId

string

Unique operation ID

Response:

{
  "status": "completed",
  "inconsistency": false,
  "source": { "status": "completed", "chainId": 1, "transactionHash": "0x..." },
  "oracle": { "status": "completed", "requestId": "0x..." },
  "destination": { "status": "completed", "chainId": 42161, "emergency": false }
}

Possible Statuses:

Status

Description

in progress

Operation in progress

completed

Successfully completed

failed

Execution error

reverted

Reverted (requires inconsistency)

canceled

Canceled

Status Handling Algorithm:

Check status:
├── "completed" → Done ✅
├── "in progress" → Continue polling
└── "failed" / "reverted" → Check flags:
    ├── destination.emergency === true → POST /tx/create/emergency
    └── inconsistency === true → POST /inconsistency

GET /search

Search transactions by hash or requestId.

Parameters:

Parameter

Type

Required

Description

search

string

Yes

Transaction hash or requestId

limit

number

Results limit

offset

number

Offset

Example:

curl "https://api.crosscurve.fi/search?search=0xTransactionHash"

GET /history

User transaction history.

Parameters:

Parameter

Type

Required

Description

address

string

Yes

Wallet address

Example:

curl "https://api.crosscurve.fi/history?address=0xYourAddress"

Error Handling

Scenarios

Flag

Action

inconsistency: false, emergency: false

Operation completed

inconsistency: true

Call /inconsistency for refund

emergency: true

Call /tx/create/emergency for recovery

GET /inconsistency/{requestId}

Get parameters for refund on inconsistency.

Example:

curl "https://api.crosscurve.fi/inconsistency/0xRequestId"

POST /inconsistency

Create refund transaction.

Call GET /inconsistency/{requestId} — get parameters (tokenIn, tokenOut, chainIdIn, chainIdOut, amountIn)

Sign refund data with user wallet (EIP-712 or personal_sign)

Pass signature and original route to this endpoint

Request Body:

{
  "requestId": "0x...",
  "signature": "0x...",
  "routing": { /* original route from /routing/scan */ },
  "permit": {
    "v": 28,
    "r": "0x...",
    "s": "0x...",
    "deadline": 1703001600
  }
}

Parameters:

Field

Type

Required

Description

requestId

string

Yes

Operation ID with inconsistency

signature

string

Yes

User signature (65 bytes hex)

routing

object

Yes

Original route from /routing/scan

permit

object

EIP-2612 permit (if token supports)

POST /tx/create/emergency

Emergency recovery of locked funds.

When to use: When destination.emergency: true in transaction status — funds are locked on destination chain and require manual recovery.

Request Body:

{
  "requestId": "0x...",
  "signature": "0x..."
}

Parameters:

Field

Type

Required

Description

requestId

string

Yes

Locked operation ID

signature

string

Yes

User signature (65 bytes hex)

Response: Returns transaction data for fund recovery.

Creating Signature for Emergency/Inconsistency

For /tx/create/emergency and /inconsistency endpoints, a signature confirming wallet ownership is required.

Hash requestId as string

const messageHash = ethers.utils.solidityKeccak256(['string'], [requestId]);

Convert to bytes

const messageHashBinary = ethers.utils.arrayify(messageHash);

Sign (adds Ethereum prefix)

const signature = await signer.signMessage(messageHashBinary);
return signature; // 132 characters (0x + 65 bytes)

// Usage
const signature = await createRecoverySignature(requestId, signer);

// For emergency:
await fetch(`${API_BASE}/tx/create/emergency`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ requestId, signature })
});

// For inconsistency:
await fetch(`${API_BASE}/inconsistency`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ requestId, signature, routing: selectedRoute })
});

Common API Errors

Error

Cause

Solution

Can't find receiveRequest

requestId not found

Verify requestId

Can't find paymentTx

Transaction not found

Verify requestId

Routing signature not valid

Route expired or changed

Repeat /routing/scan + /estimate

Already completed

Transaction completed

No action required

Not an emergency

Emergency conditions not met

Wait or check status

Uncorrect user address

Signature not from owner

Sign with wallet from from

invalid signature string

Invalid signature format

Verify 65-byte hex signature

API Reference

Endpoint List

Reference Data

Method

Endpoint

Description

GET

/networks

List of networks

GET

/tokenlist

List of tokens

GET

/validators

Validator status

GET

/ready

Service readiness

GET

/prices/{token}

Token price

GET

/prices/{token}/{chainId}

Price in network

POST

/prices

Batch prices

Routing and Swap

Method

Endpoint

Description

POST

/routing/scan

Find routes

POST

/estimate

Operation estimate

POST

/tx/create

Create transaction

Monitoring

Method

Endpoint

Description

GET

/transaction/{requestId}

Transaction status

GET

/search

Search transactions

GET

/history

User history

GET

/transactions

Transaction list

Error Handling

Method

Endpoint

Description

GET

/inconsistency/{requestId}

Refund parameters

POST

/inconsistency

Refund transaction

POST

/tx/create/emergency

Emergency recovery

Supply and Statistics

Values are dynamic, examples current at time of testing.

Method

Endpoint

Description

Response Format

GET

/supply/eywa/ts

Total Supply EYWA

number

GET

/supply/eywa/ms

Max Supply EYWA

number

GET

/supply/eywa/cmc

Data for CoinMarketCap

number

GET

/supply/eywa/cg

Data for CoinGecko

{"result":"..."}

GET

/points/multipliers

Points multipliers

object

NFT Operations

Method

Endpoint

Description

Required Parameters

GET

/nft/rarity

NFT rarity

tokens (query, string) ⚠️

POST

/nft/estimate

NFT operation estimate

wallet, tokenIds (array of numbers)

POST

/nft/tx

Create NFT transaction

wallet, tokenIds, estimate

POST

/nft/emergency

NFT emergency operation

requestId, signature

⚠️ Known bug: GET /nft/rarity does not parse tokens query parameter. Endpoint temporarily unavailable.

POST /nft/estimate { wallet, tokenIds: [1,2,3] } → estimate

POST /nft/tx { wallet, tokenIds, estimate } → tx data

Code Examples

Main flow in Quick Start section.

TypeScript: Types and Polling

interface SwapParams {
  chainIdIn: number;
  chainIdOut: number;
  tokenIn: string;
  tokenOut: string;
  amountIn: string;
  slippage: number;
  from: string;
  recipient: string;
}

interface TransactionStatus {
  status: 'in progress' | 'completed' | 'failed';
  inconsistency: boolean;
  source: { status: string; chainId: number; transactionHash: string };
  destination?: { status: string; emergency: boolean };
}

// Polling with timeout
async function trackTransaction(requestId: string, maxAttempts = 60): Promise<TransactionStatus> {
  const API_BASE = 'https://api.crosscurve.fi';

  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`${API_BASE}/transaction/${requestId}`);
    const data: TransactionStatus = await res.json();

    if (data.status === 'completed') return data;
    if (data.inconsistency) return data; // requires /inconsistency
    if (data.destination?.emergency) return data; // requires /tx/create/emergency

    await new Promise(r => setTimeout(r, 5000));
  }
  throw new Error('Timeout: transaction not completed');
}

JavaScript: Getting Networks and Tokens

async function getNetworksAndTokens() {
  const networks = await fetch('https://api.crosscurve.fi/networks?type=0').then(r => r.json());
  const tokensByNetwork = await fetch('https://api.crosscurve.fi/tokenlist').then(r => r.json());
  return { networks, tokensByNetwork };
}

function getSwappableTokens(tokensByNetwork, networkName) {
  const networkData = tokensByNetwork[networkName];
  if (!networkData) return [];

  return networkData.tokens.filter(token =>
    token.tags.includes('can_swap')
  );
}

Python: Finding Route

import requests

API_BASE = 'https://api.crosscurve.fi'

def find_route(chain_in: int, chain_out: int,
               token_in: str, token_out: str,
               amount: str, slippage: float = 0.5):

    response = requests.post(f'{API_BASE}/routing/scan', json={
        'params': {
            'chainIdIn': chain_in,
            'chainIdOut': chain_out,
            'tokenIn': token_in,
            'tokenOut': token_out,
            'amountIn': amount
        },
        'slippage': slippage
    })

    routes = response.json()

    if not routes:
        raise Exception('No routes available')

    selected = routes[0]  # first route from list
    print(f"Amount In: {selected['amountIn']}")
    print(f"Amount Out: {selected['amountOut']}")
    print(f"Price Impact: {selected['priceImpact']}%")
    print(f"Total Fee: {selected['totalFee']['percent']}%")

    return selected

# Example usage
route = find_route(
    chain_in=1,          # Ethereum
    chain_out=42161,     # Arbitrum
    token_in='0xD533a949740bb3306d119CC777fa900bA034cd52',   # CRV on Ethereum
    token_out='0x11cDb42B0EB46D95f990BeDD4695A6e3fA034978',  # CRV on Arbitrum
    amount='1000000000000000000000'  # 1000 CRV (18 decimals)
)

Route Operation Codes

Code

Description

A

Add liquidity

S

Swap

R

Remove liquidity

LM

Lock/Mint

BU

Burn/Unlock

BM

Burn/Mint

Uw

Unwrap (unwrap native token)

W

Wrap (wrap native token)

M

Emergency Mint

U

Emergency Unlock

Rate Limits and Best Practices

Rate Limits

Public rate limits are not documented. For stable operation:

Endpoint

Usage Example

/networks, /tokenlist

Cache locally

/routing/scan

On user request

/estimate

After route selection

/transaction/{id}

Polling with interval

/prices

Cache when needed

Best Practices

Cache /networks and /tokenlist — data changes rarely

let cache = { networks: null, tokens: null, time: 0 };
const TTL = 3600000; // 1 hour

async function getNetworks() {
  if (cache.networks && Date.now() - cache.time < TTL) return cache.networks;
  cache.networks = await fetch(`${API_BASE}/networks?type=0`).then(r => r.json());
  cache.time = Date.now();
  return cache.networks;
}

Checksum addresses — EIP-55 format recommended for compatibility

const address = ethers.utils.getAddress(userInput); // converts to checksum

Check can_swap before calling /routing/scan

if (!token.tags.includes('can_swap')) {
  throw new Error('Token not available for cross-chain swap');
}

Check deadline from /estimate before sending

const now = Math.floor(Date.now() / 1000);
if (Number(estimate.deadline) < now + 60) {
  // deadline expires in <1 min — get new estimate
}

Polling — 5-10 sec interval, handle inconsistency and emergency

Save requestId — store after sending transaction for tracking and recovery

Slippage — use appropriate values (0.5-1% for stables, 1-3% for volatile)

Use correct wallet for recovery signatures — must match from of original transaction

Account for token decimals — not all tokens have 18 decimals

// ❌ Wrong: hardcoded 18 decimals
const amount = parseFloat(value) / 1e18;

// ✅ Correct: use decimals from tokenlist
function formatAmount(rawAmount, decimals) {
  return parseFloat(rawAmount) / Math.pow(10, decimals);
}

// Decimals examples:
// USDC, USDT: 6
// WBTC: 8
// CRV, ETH, most tokens: 18

Limitations

Parameter

Description

Minimum amount

Depends on token pair and liquidity

Maximum amount

Limited by pool liquidity

Slippage

Specified in percent when calling /routing/scan

Execution time

Depends on networks and oracle network load

Contract Addresses

Contract addresses available via /networks:

Contract

Description

Field in /networks

Portal

Entry point for cross-chain operations

portal

Synthesis

Synthetic token contract

synthesis

Router

Swap router

router

// Getting contract addresses
const networks = await fetch('https://api.crosscurve.fi/networks?type=0').then(r => r.json());
const ethPortal = networks.ethereum.portal;
const ethRouter = networks.ethereum.router;
const ethSynthesis = networks.ethereum.synthesis;

Fee Structure

Fee information is returned in /routing/scan response:

Fee Type

Description

Response Field

dex

DEX/pool fee

In each route step

bridge

Bridge fee

In bridgeIn/bridgeOut steps

aggregation

Aggregation fee

Total CrossCurve fee

total

Total fee

totalFee in route

const route = routes[0];
console.log(`Total fee: ${route.totalFee.percent}%`);
console.log(`Fee in USD: $${route.totalFee.amount}`);

// Details by step
route.route.forEach(step => {
  step.fees?.forEach(fee => {
    console.log(`${fee.type}: ${fee.percent}%`);
  });
});

FAQ

Is an API key required?

A: At time of writing, the API does not require authentication.

Are there rate limits?

A: Public limits are not documented. Cache reference data and avoid frequent requests.

Which networks are supported?

A: Current list available via `GET /networks`. EVM-compatible networks are supported.

Why does `/routing/scan` return an empty array?

A: No route found. See If No Route Found section — check `can_swap`, try different amounts or pairs, ensure liquidity.

How to get requestId after sending transaction?

A: RequestId is emitted in Portal contract events. Use `GET /search?search={txHash}` to find it.

What to do with `inconsistency: true`?

A: Refund required: - Call `GET /inconsistency/{requestId}` — get parameters for signature - Sign data with user wallet - Call `POST /inconsistency` with `requestId`, `signature` and original `routing`

What to do with `emergency: true`?

A: Fund recovery required. Call `POST /tx/create/emergency` with `requestId` and `signature` (user signature).

How does permit (EIP-2612) work?

A: If token supports permit (`permit: true` in tokenlist), you can sign permission offchain instead of separate approve transaction. Pass signature `{v, r, s}` to `/tx/create`.

Glossary

Term

Description

Portal

Entry point contract for cross-chain operations

Synthesis

Contract for minting/burning synthetic tokens

Router

Swap routing contract

RequestId

Unique identifier for cross-chain operation

Inconsistency

State requiring fund refund

Emergency

State requiring fund recovery

can_swap

Token tag indicating cross-chain swap capability

Synth

Synthetic token representing asset from another network

bridgeIn

Token lock operation on source chain

bridgeOut

Token unlock operation on destination chain

Oracle

CrossCurve validator network

Slippage

Allowed deviation from expected price

Changelog

API change history. Follow updates in Swagger UI.

Date

Change

2025-12

Documentation created: Quick Start, API Reference, code examples

—

For current API changes, see Swagger UI

Support

Swagger UI: https://api.crosscurve.fi/api-docs/
Documentation: https://docs.crosscurve.fi

PreviousCrossCurve SuperDVN NextTechnical Documentation for CrossCurve DAO Smart Contracts

hashtagQuick Start

hashtagMinimum Integration Flow

hashtagExample: Swap CRV (Ethereum) → CRV (Arbitrum)

hashtagTest Examples

hashtagIf No Route Found

hashtagcURL Examples for Quick Testing

hashtagIntegration Architecture

hashtagProcess Diagram

hashtagCross-Chain Swap Stages

hashtagSupported Networks

hashtagReference Data

hashtagGET /networks

hashtagGET /tokenlist

hashtagGET /prices/{token}

hashtagGET /prices/{token}/{chainId}

hashtagPOST /prices

hashtagExecuting Cross-Chain Swaps

hashtagPOST /routing/scan

hashtagPOST /estimate

hashtagPOST /tx/create

hashtagToken Approval

hashtagStandard Approve (ERC-20)

hashtagPermit (EIP-2612) - Approve via Signature

hashtagTransaction Tracking

hashtagGET /transaction/{requestId}

hashtagGET /search

hashtagGET /history

hashtagError Handling

hashtagScenarios

hashtagGET /inconsistency/{requestId}

hashtagPOST /inconsistency

hashtagPOST /tx/create/emergency

hashtagCreating Signature for Emergency/Inconsistency

hashtagCommon API Errors

hashtagAPI Reference

hashtagEndpoint List

hashtagReference Data

hashtagRouting and Swap

hashtagMonitoring

hashtagError Handling

hashtagSupply and Statistics

hashtagNFT Operations

hashtagCode Examples

hashtagTypeScript: Types and Polling

hashtagJavaScript: Getting Networks and Tokens

hashtagPython: Finding Route

hashtagRoute Operation Codes

hashtagRate Limits and Best Practices

hashtagRate Limits

hashtagBest Practices

hashtagLimitations

hashtagContract Addresses

hashtagFee Structure

hashtagFAQ

hashtagGlossary

hashtagChangelog

hashtagSupport

Quick Start

Minimum Integration Flow

Example: Swap CRV (Ethereum) → CRV (Arbitrum)

Test Examples

If No Route Found

cURL Examples for Quick Testing

Integration Architecture

Process Diagram

Cross-Chain Swap Stages

Supported Networks

Reference Data

GET /networks

GET /tokenlist

GET /prices/{token}

GET /prices/{token}/{chainId}

POST /prices

Executing Cross-Chain Swaps

POST /routing/scan

POST /estimate

POST /tx/create

Token Approval

Standard Approve (ERC-20)

Permit (EIP-2612) - Approve via Signature

Transaction Tracking

GET /transaction/{requestId}

GET /search

GET /history

Error Handling

Scenarios

GET /inconsistency/{requestId}

POST /inconsistency

POST /tx/create/emergency

Creating Signature for Emergency/Inconsistency

Common API Errors

API Reference

Endpoint List

Reference Data

Routing and Swap

Monitoring

Error Handling

Supply and Statistics

NFT Operations

Code Examples

TypeScript: Types and Polling

JavaScript: Getting Networks and Tokens

Python: Finding Route

Route Operation Codes

Rate Limits and Best Practices

Rate Limits

Best Practices

Limitations

Contract Addresses

Fee Structure

FAQ

Glossary

Changelog

Support