Quick Start

Complete your first cross-chain trade with WheelX API in a few minutes.

This guide walks you through a cross-chain trade from USDC on Ethereum to USDT on Soneium, from quote to final status.

Before You Start

Base URL:

https://api.wheelx.fi/v1

Requirements:

• Node.js 18+
• an Ethereum RPC URL
• an EVM wallet address
• a signer or wallet client that can send transactions on Ethereum
• a wallet that holds USDC on Ethereum mainnet
• a small amount of ETH for gas

System Flow

This is the execution flow for a standard WheelX cross-chain trade.

Try It Step by Step

Install the dependencies

This example uses axios to call the API and viem to check allowance, approve the token, and send the transaction. viem is not required by WheelX itself. It is included here because the sample script uses it end to end.

npm install axios viem

pnpm add axios viem

yarn add axios viem

Configure your environment

Set the RPC endpoint and the wallet address before running the script.

export RPC_URL="https://your-ethereum-rpc"
export WALLET_ADDRESS="0xyourwalletaddress"

Request a quote

This example performs a bridge-and-swap flow from Ethereum USDC to Soneium USDT.

{
  "from_chain": 1,
  "to_chain": 1868,
  "from_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "to_token": "0x3A337a6adA9d885b6Ad95ec48F9b75f197b5AE35",
  "from_address": "0x1111111111111111111111111111111111111111",
  "to_address": "0x1111111111111111111111111111111111111111",
  "amount": "100000000",
  "affiliation": null,
  "to_platform_id": 0,
  "quote_only": true
}

You can use the placeholder address above to try the quote request first. Replace both address fields with your own EVM address before sending a real transaction. In the full script below, this value is read from WALLET_ADDRESS.

Review the response

A successful quote returns the transaction payload, the approval requirement, and the order identifier you will use later for status tracking.

{
  "request_id": "0x00000000000000000000000000000000019ce54ecf0a7cd3a9cc98cc2b805241",
  "amount_out": "99324911",
  "tx": {
    "to": "0x7eC9672678509a574F6305F112a7E3703845a98b",
    "value": "0",
    "data": "0xb3c8c6da..."
  },
  "approve": {
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "spender": "0x7eC9672678509a574F6305F112a7E3703845a98b",
    "amount": 100000000
  },
  "min_receive": "94358665",
  "estimated_time": 10.0,
  "router": "Pancakeswap + WheelX + Uniswap"
}

Key fields to check:

• request_id: save this value for order polling
• tx.to: contract address for the source-chain transaction
• tx.data: calldata to submit
• tx.value: native token value to include with the transaction
• approve: approval instructions for the input token; if not null, approve before the main transaction
• amount_out: quoted destination amount
• min_receive: minimum receive amount after slippage
• estimated_time: rough route duration
• router: readable route summary

The quote already contains the transaction payload needed for execution. You do not need to build calldata yourself.

Execute the trade

Create a file named wheelx-quickstart.mjs, paste the script below, and connect your own signer before running it. The script focuses on the WheelX flow and leaves wallet setup to your application.

Run it:

node wheelx-quickstart.mjs

Check the order status

For this flow, the order status is simple:

• Open: the order has started and is still in progress
• Filled: the cross-chain trade is complete
• Failed: the order did not complete successfully

Use this rule in your application:

1. Submit the source-chain transaction
2. Keep the request_id
3. Poll /order/{request_id}
4. Mark the trade as complete only when the order reaches Filled

For cross-chain flows, the source-chain transaction receipt is not the final completion signal. Use the order status.