> For the complete documentation index, see [llms.txt](https://docs.wheelx.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wheelx.fi/api-and-developer/getting-started/quick-start.md).

# 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.

<figure><img src="https://4149802529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTtoew6SwbdqR04YafQFk%2Fuploads%2FgAoT5sYRyxpm1f9VvbOa%2Fc4c7ddcb-67e4-4fcb-b4ac-b46e5be92f33.jpeg?alt=media&amp;token=c98dccc0-01c4-459f-a39d-df67fffe2643" alt=""><figcaption></figcaption></figure>

### 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.