# What is WheelX
### Overview **WheelX** is a leading AI-powered aggregation protocol built to make digital asset movement across blockchain ecosystems faster, smarter, and more efficient. Supporting **50+ blockchain networks**, WheelX aggregates liquidity, evaluates execution paths, and simplifies cross-chain interactions through intelligent routing. By abstracting the complexity of fragmented blockchain infrastructure, WheelX enables users, developers, wallets, and enterprises to move capital across multiple ecosystems through a unified experience. Today, WheelX's core offerings include **cross-chain swaps** and **on-chain payment infrastructure**, while continuously expanding into next-generation financial solutions such as **stablecoins**, **Real World Assets (RWA)**, and **tokenized U.S. equities**. Our mission is simple: > **Faster. Cheaper. Smarter. Safer.** These four principles define how WheelX designs its products and optimizes every transaction.
*** ### Core Products #### Cross-Chain Swaps Protocol Cross-chain interoperability is fundamental to the future of Web3, yet fragmented liquidity and complex bridging experiences continue to create friction for users. WheelX addresses these challenges through its [Cross-Chain Swaps Protocol](/solutions/cross-chain-swaps-protocol), which uses a routing engine to aggregate liquidity across multiple chains and protocols. Each transaction is evaluated using real-time factors, including: * Execution cost * Transaction speed * Liquidity availability * Slippage * Network conditions Based on these factors, WheelX selects an execution path designed to balance cost, speed, liquidity, and reliability for users and applications. *** #### Payment Infrastructure Beyond cross-chain asset transfers, WheelX provides [Payment Infrastructure](/solutions/payment-infrastructure) for the multi-chain ecosystem. Our payment solutions enable wallets, dApps, merchants, and enterprises to send, receive, and settle digital assets across multiple blockchain networks through a single integration. By simplifying blockchain payments and improving settlement efficiency, WheelX helps accelerate the adoption of digital assets in real-world use cases. *** ### Building the Next Generation of On-Chain Finance As blockchain technology evolves beyond DeFi, WheelX is expanding its infrastructure to support the next generation of digital financial services. Our strategic focus includes: * Stablecoin infrastructure * Real-world assets (RWAs) * Tokenized U.S. equities * AI-powered financial automation * Cross-chain capital allocation We believe the future of finance will combine traditional financial assets with decentralized infrastructure. WheelX is building the intelligent connectivity layer that enables capital to move efficiently across chains, protocols, and real-world financial ecosystems. *** ### Industry Recognition WheelX has received recognition from organizations across the blockchain industry. WheelX is a member of the [Circle Alliance Program](https://www.circle.com/alliance-program) and is listed in the official [Circle Alliance Directory](https://partners.circle.com/partner/wheelx), reflecting its commitment to secure blockchain payments and the global adoption of stablecoins. Circle's official WheelX partner profile also notes weekly recommendations by several Web3 wallets, including: * Binance Wallet * OKX Wallet * Bitget Wallet These wallet listings help users discover and access WheelX services. *** ### Ecosystem Partnerships WheelX works with blockchain ecosystems in different capacities, including ecosystem collaboration, technical integration, and cross-chain liquidity support. The networks WheelX supports or collaborates with include: * BNB Chain * Avalanche * Arbitrum * Linea * Morph * Soneium * MegaETH * Arc * Scroll * Taiko The scope of WheelX's work varies by ecosystem and may include product integration, infrastructure support, and cross-chain functionality. As the multi-chain ecosystem continues to expand, WheelX remains committed to supporting emerging networks and advancing interoperability across Web3. *** ### Our Vision The future of blockchain should be connected, not fragmented. Users should not need to understand bridges, compare liquidity sources, or manually determine the best execution path. Developers should not need to integrate multiple protocols simply to support cross-chain functionality. WheelX uses AI-powered aggregation to reduce these complexities, allowing users and businesses to focus on moving capital efficiently and securely. Our vision is to become the intelligent infrastructure layer for global digital asset movement, connecting blockchains, applications, and financial ecosystems through interoperability. Across cross-chain swaps, digital payments, stablecoin adoption, RWAs, and tokenized financial assets, WheelX focuses on making digital asset movement more efficient, accessible, and secure. By continuously optimizing how capital flows across blockchain networks, WheelX enables users and enterprises to participate in a more connected and efficient on-chain economy. # Overview WheelX provides infrastructure for moving digital assets across blockchain networks and for building programmable payment experiences. Choose the solution that best matches your product and integration goals. ### Choose a Solution * **For wallets, dApps, exchanges, and trading platforms** — [Cross-Chain Swaps Protocol](/solutions/cross-chain-swaps-protocol): Access intelligent routing and best execution for same-chain and cross-chain asset swaps. * **For payment providers, fintech platforms, merchants, and treasury teams** — [Payment Infrastructure](/solutions/payment-infrastructure): Build address-based payments, cross-chain collection, settlement, and treasury workflows. # Cross-Chain Swaps Protocol WheelX Cross-Chain Swaps Protocol is an AI-powered aggregation infrastructure that enables seamless, one-click token swaps, bridging, and onboarding across 50+ blockchains. It solves liquidity fragmentation and the complexity of traditional bridging by intelligently combining multiple bridges, DEXs, and liquidity sources into optimized single transactions.
### High-Level Overview WheelX acts as the central aggregation layer connecting major blockchains (Ethereum, Solana, Arbitrum, Base, BNB Chain, Tron, Bitcoin ecosystems, and more) through an AI routing engine. It selects the optimal paths by integrating leading bridges and DEXs for superior execution. ### Key Value Proposition * **Best Execution**: AI router dynamically selects the optimal path for the best price, lowest total cost, minimal slippage, and fastest settlement. * **Native Asset Swaps**: Direct transfers using native tokens on both source and destination chains — no wrapped assets. * **Unified Experience**: Users simply specify what they have and what they want; WheelX handles everything in between. ### Business Benefits * Dramatically improves user experience and conversion rates for wallets, dApps, and trading platforms. * Increases cross-chain liquidity flow and capital efficiency for ecosystems and protocols. * Provides enterprises and merchants with reliable, low-cost multi-chain payment rails. * Reduces operational complexity for developers through simple SDK and API integration. ### Core Capabilities * Support for **50+ blockchain networks** (EVM, Solana, Tron, Bitcoin ecosystems, etc.). * Real-time aggregation across leading bridges and DEXs. * Advanced AI-powered routing optimized for cost, speed, and liquidity depth. * High-volume order handling with intelligent splitting. * Enterprise-grade reliability and security. ### Instant Bridging & Onboarding WheelX enables instant bridging and seamless onboarding across 50+ blockchains. By combining high-speed cross-chain liquidity with intelligent swap aggregation, users can deposit, withdraw, or onboard any token onto any supported chain quickly and efficiently. #### Key Features * **Ultra-Fast Bridging** — Median bridge times of just a few seconds across major networks. * **Multi-VM & Broad Coverage** — Full support for leading EVM chains, Solana, Tron, Bitcoin ecosystems, and more. * **WheelX Payment** — Onboard via direct transfers from centralized exchanges (CEX) or any wallet — no wallet connection required. * **App & Partner Revenue** — Easy-to-implement fee system with automatic collection in stablecoins (USDC/USDT). #### How It Works WheelX uses intelligent cross-chain intents and AI-powered routing for low-cost, low-latency transfers. Users receive a real-time quote with exact time and cost. Upon acceptance, the transaction is validated and executed. Funds arrive instantly on the destination chain while source assets are handled securely in the background. ### Instant Same-Chain & Cross-Chain Swaps WheelX delivers best-in-class same-chain and cross-chain swaps across 50+ networks. It combines powerful meta-aggregation of top DEXs and liquidity pools with intelligent AI routing and high-speed bridging to ensure users always get the optimal price, lowest cost, and fastest execution for any-to-any token swaps. #### Key Features * **Smart Meta-Aggregation** — Aggregates the best on-chain swap providers and liquidity pools for superior routes. * **Instant Cross-Chain Swaps** — Ultra-fast execution with median times of just a few seconds. * **Multi-VM Support** — Comprehensive coverage across EVM, Solana, Tron, Bitcoin ecosystems, and beyond. * **App & Partner Revenue** — Flexible fee system with automatic collection in stablecoins (USDC/USDT). #### How It Works Users receive a real-time quote detailing the expected output, time, and cost. Upon acceptance, WheelX validates the order and executes the optimal route — whether a simple same-chain swap or a complex cross-chain operation. Funds are delivered efficiently with native assets on the destination chain. ### Integration Options * **Bridging & Onboarding**: Add cross-chain transfers and CEX-to-chain deposits to wallets, dApps, or trading interfaces. * **Swaps**: Seamlessly integrate both same-chain and cross-chain swaps. Both are available via WheelX's Quote API and SDK. For technical details, refer to the Quickstart Guide. ### Strategic Impact As the core engine of WheelX, the Cross-Chain Swaps Protocol (with integrated Bridging & Onboarding) serves as essential infrastructure for the multi-chain economy — empowering faster adoption, better liquidity, enhanced user experience, and new cross-ecosystem opportunities for users, partners, and enterprises. # Payment Infrastructure Seamless Cross-Chain Payments for Users and Merchants WheelX provides robust cross-chain payments infrastructure that enables instant, low-cost payments between users and merchants across any supported blockchain. Users can pay with any token on any chain, while merchants receive settlement in their preferred token — whether a stablecoin, native asset, or any other supported token. One integration. Any-to-any payments. Instant and transparent.
### Key Highlights * **50+ Chains** — Connect users across all major networks * **Ultra-Fast Settlement** — Sub-3-second median fill time on most routes * **High Reliability** — Battle-tested infrastructure trusted by growing numbers of partners * **Revenue Opportunities** — Flexible App Fees automatically settled in USDC or USDT ### Who Benefits from WheelX Payment * **Payment Processors** — Add multi-chain acceptance to your stack with a single integration. * **Wallets & Neobanks** — Let users pay merchants directly from any token or chain without bridging or switching networks. * **Commerce Platforms** — Enable merchants to accept payments from any buyer across the entire on-chain ecosystem, regardless of the token or chain they hold. ### Integration Options **WheelX Payment** — No wallet connection needed. Generate a unique deposit address or QR code for users to send funds from any wallet or exchange. ### Powerful Commerce Features * **Exact Output Settlement** — Guarantee merchants receive the precise amount requested (no slippage risk for the receiver). * **Fee Sponsorship & Gasless Payments** — Offer frictionless checkout by covering gas fees or enabling fully gasless transactions. * **App Fees** — Earn revenue on every transaction, automatically collected in USDC or USDT. * **Real-Time Tracking** — Full visibility into transaction status, routes, and settlement via API and WebSockets. WheelX handles the complex cross-chain routing, settlement guarantees, and technical infrastructure — allowing you to focus on building great merchant tools, order management, invoicing, and customer experiences on top. ### Ready to Integrate? Add powerful cross-chain payments to your platform with one integration. Check out our Quickstart Guide or contact us at **** to discuss your specific use case. # Overview
WheelX is an AI-powered aggregation and execution layer designed to unify fragmented liquidity across decentralized exchanges (DEXs), cross-chain bridges, and multiple blockchain ecosystems.\ By abstracting the complexity of routing, bridging, and liquidity sourcing, WheelX enables users to execute transactions efficiently across chains and asset types. ### Explore the Transaction Flow * **For readers learning how WheelX finds execution routes** — [Aggregating](/how-it-works/aggregating): See how WheelX combines liquidity and quotes from decentralized exchanges and cross-chain bridges. * **For users moving assets between networks** — [Bridging](/how-it-works/bridging): Learn how WheelX executes transfers across blockchain ecosystems. * **For users exchanging one asset for another** — [Swapping](/how-it-works/swapping): Understand same-chain and cross-chain token swaps. * **For users exploring WheelX utilities** — [Tools](/how-it-works/tools): Review the supporting tools available across the WheelX product experience. * **For first-time users** — [Tutorial](/how-it-works/tutorial): Follow a step-by-step cross-chain transaction flow. # Aggregating #### What is Aggregation? Aggregation is the process of sourcing liquidity from multiple protocols and determining the most efficient way to execute a transaction.Instead of executing trades through a single DEX or bridge, WheelX evaluates multiple options simultaneously and selects, or constructs, the best possible route.This may include: * Selecting a single optimal source * Splitting orders across multiple DEXs * Combining swap and bridge steps across chains Routing decisions are optimized to minimize slippage, reduce costs, and ensure fast execution by leveraging the best available liquidity across protocols. In more complex scenarios, WheelX can split orders, use multi-hop paths, or combine bridging and swapping into a single, unified execution flow.
# Bridging #### Cross-Chain Execution WheelX enables seamless cross-chain transactions by integrating multiple bridge protocols directly into its routing system. Instead of relying on a single bridge, WheelX continuously evaluates different options and selects the most efficient route based on real-time conditions.
In practice, a cross-chain transaction may involve several coordinated steps, such as swapping into a bridge-compatible asset on the source chain, transferring it across chains, and then swapping into the desired token on the destination chain. All of these steps are automatically combined and optimized into a single execution flow, so users don’t need to manage them manually. To ensure reliability and efficiency, WheelX connects with leading cross-chain infrastructure providers. The routing engine continuously monitors factors like bridge performance, fees, and execution conditions to determine the optimal path for each transaction. At the same time, WheelX maintains a strong focus on security and user ownership. The protocol is fully non-custodial, meaning users always retain control over their assets. Funds are not locked within the system, and every execution path is selected with both safety and efficiency in mind. # Swapping #### Token Swaps WheelX supports both single-chain and cross-chain token swaps, allowing users to trade assets seamlessly across different environments. * **For single-chain swaps**
Users can exchange tokens within the same blockchain by leveraging aggregated liquidity from multiple DEXs. This ensures that trades are executed with optimal pricing and minimal slippage without requiring users to manually compare different platforms. For cross-chain swaps
WheelX extends this capability across networks by combining swapping and bridging into a unified flow. Instead of handling multiple steps manually, users can swap assets from one chain to another in a single transaction, with the routing system automatically determining the most efficient path. # Tools In addition to core execution features, WheelX provides a set of supporting tools designed to enhance user experience, asset management, and ecosystem participation. #### GM GM is a daily check-in feature that allows users to engage with the WheelX ecosystem through simple, recurring interactions.By checking in regularly, users may unlock rewards, track engagement, or participate in ongoing campaigns. This feature is designed to encourage consistent activity while providing additional incentives within the platform.
#### Deploy Deploy allows users to launch smart contracts directly on supported networks without requiring advanced technical knowledge or development experience.This feature simplifies the process of interacting with blockchain infrastructure, enabling users to deploy contracts on the mainnet in a more accessible and user-friendly way.
#### Portofolio Portfolio provides a unified dashboard that displays the balance of your connected wallet across supported chains. It allows users to easily monitor their assets, track holdings, and get a clear overview of their positions in one place.
#### Tracker Tracker is a tool designed to monitor balances across multiple wallets and networks. It enables users to view asset distribution across different chains without needing to switch between platforms.This is especially useful for users managing assets in multiple wallets or operating across various blockchain ecosystems.
# Tutorial Step-by-step guide to using WheelX for cross-chain transactions. ### Prerequisites * A Web3 wallet (MetaMask, OKX Wallet, etc.) * Tokens on at least one supported chain * Enough native tokens for gas fees ### Basic Cross-Chain Swap 1. Connect your wallet to [wheelx.fi](https://wheelx.fi) 2. Select source chain and token 3. Select destination chain and token 4. Enter the amount to swap 5. Review the quote and confirm 6. Wait for transaction confirmation ### Advanced Operations * **WheelX Payment**: Create a new payment address for each WheelX Payment transaction * **Multi-hop**: Route through intermediate chains for better rates * **Batch operations**: Execute multiple swaps in sequence
# Overview Explore the capabilities that power WheelX transactions, integrations, and payment flows. This section covers the execution engine, smart-contract architecture, network support, token coverage, and user-facing transaction features. ### Start by Goal * **Build address-based payment and settlement flows** — [WheelX Payment](/features/wheelx-payment): Generate payment addresses and monitor cross-chain payment execution. * **Review protocol architecture and deployments** — [Smart Contracts](/features/smart-contracts): Explore contract design, architecture, and deployment addresses. * **Understand route selection** — [AI Route Optimization](/features/ai-route-optimization): Learn how WheelX evaluates and optimizes transaction routes. * **Compare available execution providers** — [Multi-Router Quote Comparison](/features/multi-router-quote-comparison): Review quote comparison and route-selection modes. * **Understand transaction costs** — [Gas Fee Estimation](/features/gas-fee-estimation): See how fees are estimated across routes and networks. * **Check network availability** — [Supported Chains](/features/supported-chains): Review supported blockchain networks and native assets. * **Check asset availability** — [Supported Tokens](/features/supported-tokens): Review supported crypto assets, stablecoins, tokenized assets, and other markets. # WheelX Payment ### WheelX Payment — Technical Documentation ### Overview WheelX Payment is a core primitive of the WheelX cross-chain bridging protocol. It enables users to bridge or swap assets across blockchains by simply sending funds to a generated address — no wallet connection, no transaction signing, and no smart contract interaction required. This makes WheelX Payment ideal for CEX withdrawals, fiat onramps, and headless systems where the sender cannot sign transactions. The user only needs to perform a standard token transfer to the generated address. WheelX automatically detects the deposit, processes the cross-chain transfer, and delivers funds to the specified destination on the target network. **Key benefits:** * No wallet connection required * No approval transactions or calldata needed * Works with any wallet or CEX supporting standard transfers * Deterministic address generation with complete refund handling #### Demo Link {% embed url="" %} #### Demo Guide {% embed url="" %} #### How It Works The WheelX Payment flow consists of three phases: The integrator requests a deposit address via the WheelX API, specifying the deposit network, deposit token, recipient address on the destination network, and the desired output token. WheelX returns a unique deposit address deterministically generated for the request. The user sends the specified token amount to the deposit address using a standard token transfer from any wallet or exchange. No special transaction data is required. WheelX monitors the deposit address on the source chain. Upon detecting a valid deposit, the system processes the cross-chain transfer and delivers funds to the recipient on the destination chain. Funds are credited in the specified output token. #### Core Features **Configurable Source Network and Token** Merchants can fully customize the deposit side of the transaction. The API allows specification of: * Source (deposit) network — the blockchain where the user will send funds * Source token — the asset accepted at the deposit address This flexibility enables merchants to accept deposits in the assets and networks most convenient for their users, while maintaining control over their treasury management. **Configurable Destination Network and Token** Similarly, merchants define where and how funds are received: * **Destination network** — the blockchain where funds will be delivered * **Destination token** — the asset received by the merchant on the target chain WheelX handles all cross-chain conversion and bridging automatically, allowing merchants to receive a single, predictable asset on a single chain regardless of where the deposit originated. **Fee Configuration** WheelX provides comprehensive fee management options tailored to the merchant’s business model. **Fixed Fee (WheelX fee)** WheelX charges a fixed service fee per transaction. This fee is transparent and predictable, making it suitable for standard integration scenarios. **Split Fee (Revenue Share)** Merchants can optionally enable a split-fee arrangement with WheelX. In this model, the base WheelX fee and the merchant’s markup are configured separately, allowing for customized revenue sharing agreements. **Merchant Markup** Merchants may add an additional fee on top of the WheelX base fee. This markup is deducted from the deposit amount before final crediting. The merchant markup can be configured at the account level via the WheelX dashboard or programmatically through the API. **Optional Fee Sponsorship** Merchants have the choice to: * **Pass through fees** — End users pay standard WheelX fees plus any merchant markup * **Absorb fees** — Merchant sponsors the entire fee, offering a fee-free experience to end users This B-side fee flexibility allows merchants to optimize their pricing strategy based on user acquisition costs and competitive positioning. **Refund Handling** When a deposit fails to complete successfully for any reason, WheelX implements a robust refund mechanism. The refund address is specified at deposit address creation time. Refunds are processed automatically, returning the original deposited funds to the designated refund address on the source chain. Key refund scenarios include: * Insufficient deposited amount * Unsupported token deposit * Chain congestion exceeding processing time limits * Router-level failures Refund transactions are tracked and can be monitored through the Deposit API and webhook notifications. **Deposit Status Tracking** WheelX provides comprehensive deposit status information to integrators. The status can be polled via the API or received in real-time through webhook events. Status values: * `pending` — Deposit detected, awaiting confirmation * `completed` — Funds successfully delivered to destination * `failed` — Deposit failed, refund initiated * `refunded` — Refund completed The Deposit API returns detailed information including: * Transaction hash on source chain * Source token and amount * Destination network * Destination token and received amount * Fee breakdown * Final status with timestamp **Exception Handling** WheelX includes robust exception handling for edge cases: **On-chain congestion** When a target network experiences high traffic, WheelX automatically monitors for confirmation and retries fills with appropriate gas adjustments. Merchants can also trigger the acceleration feature for immediate expedited processing. **Router stalling** In the rare event that a route becomes temporarily unresponsive, WheelX automatically contacts the route provider to resolve the issue. The system maintains redundancy across multiple routing partners to minimize disruption. **Invalid deposits** Deposits that do not match the configured token (e.g., sending ETH when USDC is expected) are automatically rejected and refunded to the specified refund address. **Balance Reconciliation and Sweeping** After deposits are processed and credited on the destination chain, deposit addresses are periodically swept to consolidate remaining balances. This maintains monitoring efficiency and ensures no funds are left stranded on source chain addresses. *** #### API Reference ### POST /v1/quote > Quote ```json {"openapi":"3.1.0","info":{"title":"API Reference","version":"0.1.0"},"tags":[{"name":"API Reference"}],"servers":[{"url":"https://api.wheelx.fi","description":"Production"}],"paths":{"/v1/quote":{"post":{"summary":"Quote","operationId":"quote_v1_quote_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["API Reference"]}}},"components":{"schemas":{"QuoteRequest":{"properties":{"from_chain":{"type":"integer","title":"From Chain"},"to_chain":{"type":"integer","title":"To Chain"},"from_token":{"type":"string","title":"From Token"},"to_token":{"type":"string","title":"To Token"},"from_address":{"type":"string","title":"From Address"},"to_address":{"type":"string","title":"To Address"},"amount":{"type":"integer","title":"Amount"},"slippage":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Slippage"},"affiliation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Affiliation"},"external_bridge":{"type":"boolean","title":"External Bridge","default":false},"to_platform_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"To Platform Id"},"select_route":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Select Route"},"sponsor_gas":{"type":"boolean","title":"Sponsor Gas","default":false},"use_deposit_address":{"type":"boolean","title":"Use Deposit Address","default":false}},"type":"object","required":["from_chain","to_chain","from_token","to_token","from_address","to_address","amount"],"title":"QuoteRequest"},"QuoteResponse":{"properties":{"request_id":{"type":"string","title":"Request Id"},"amount_out":{"type":"string","title":"Amount Out"},"fee":{"type":"string","title":"Fee"},"tx":{"anyOf":[{"$ref":"#/components/schemas/Tx"},{"$ref":"#/components/schemas/SolanaTx"},{"type":"null"}],"title":"Tx"},"approve":{"anyOf":[{"$ref":"#/components/schemas/ApproveAction"},{"type":"null"}]},"slippage":{"type":"integer","title":"Slippage"},"min_receive":{"type":"string","title":"Min Receive"},"estimated_time":{"type":"number","title":"Estimated Time","default":10},"recipient":{"type":"string","title":"Recipient"},"router_type":{"$ref":"#/components/schemas/RouterType","default":"swap"},"price_impact":{"$ref":"#/components/schemas/PriceImpactFormatted"},"router":{"type":"string","title":"Router","default":"wheelx"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"points":{"type":"string","title":"Points"},"quote_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Message"},"routes":{"items":{"$ref":"#/components/schemas/RouteInfo"},"type":"array","title":"Routes"},"deposit_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Address"},"gas_fee":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gas Fee"},"bridge_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bridge Order Id"},"quotes":{"anyOf":[{"items":{"$ref":"#/components/schemas/QuoteItem"},"type":"array"},{"type":"null"}],"title":"Quotes"}},"type":"object","required":["request_id","amount_out","fee","slippage","min_receive","recipient","price_impact","created_at","points"],"title":"QuoteResponse"},"Tx":{"properties":{"to":{"type":"string","title":"To"},"value":{"type":"string","title":"Value"},"data":{"type":"string","title":"Data"},"chainId":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chainid"},"gas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gas"},"maxFeePerGas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Maxfeepergas"},"maxPriorityFeePerGas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Maxpriorityfeepergas"}},"type":"object","required":["to","value","data"],"title":"Tx"},"SolanaTx":{"properties":{"tx":{"type":"string","title":"Tx"},"sender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender"},"gas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gas"}},"type":"object","required":["tx"],"title":"SolanaTx"},"ApproveAction":{"properties":{"token":{"type":"string","title":"Token"},"spender":{"type":"string","title":"Spender"},"amount":{"type":"integer","title":"Amount"}},"type":"object","required":["token","spender","amount"],"title":"ApproveAction"},"RouterType":{"type":"string","enum":["swap","bridge","wrap","unwrap"],"title":"RouterType"},"PriceImpactFormatted":{"additionalProperties":{"type":"string"},"type":"object","title":"PriceImpactFormatted"},"RouteInfo":{"properties":{"name":{"type":"string","title":"Name"},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo"}},"type":"object","required":["name"],"title":"RouteInfo"},"QuoteItem":{"properties":{"request_id":{"type":"string","title":"Request Id"},"router":{"type":"string","title":"Router"},"amount_out":{"type":"string","title":"Amount Out"},"tx":{"anyOf":[{"$ref":"#/components/schemas/Tx"},{"$ref":"#/components/schemas/SolanaTx"},{"type":"null"}],"title":"Tx"},"routes":{"items":{"$ref":"#/components/schemas/RouteInfo"},"type":"array","title":"Routes"},"gas_fee":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gas Fee"}},"type":"object","required":["request_id","router","amount_out"],"title":"QuoteItem"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ### GET /v1/order/{request\_id} > Get Order ```json {"openapi":"3.1.0","info":{"title":"API Reference","version":"0.1.0"},"tags":[{"name":"API Reference"}],"servers":[{"url":"https://api.wheelx.fi","description":"Production"}],"paths":{"/v1/order/{request_id}":{"get":{"summary":"Get Order","operationId":"get_order_v1_order__request_id__get","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["API Reference"]}}},"components":{"schemas":{"OrderResponse":{"properties":{"order_id":{"type":"string","title":"Order Id"},"from_chain":{"type":"integer","title":"From Chain"},"from_token":{"type":"string","title":"From Token"},"from_token_info":{"anyOf":[{"$ref":"#/components/schemas/TokenInfo"},{"type":"null"}]},"from_address":{"type":"string","title":"From Address"},"from_amount":{"type":"string","title":"From Amount"},"to_chain":{"type":"integer","title":"To Chain"},"to_token":{"type":"string","title":"To Token"},"to_token_info":{"anyOf":[{"$ref":"#/components/schemas/TokenInfo"},{"type":"null"}]},"to_amount":{"type":"string","title":"To Amount"},"to_address":{"type":"string","title":"To Address"},"open_tx_hash":{"type":"string","title":"Open Tx Hash"},"open_block":{"type":"integer","title":"Open Block"},"open_timestamp":{"type":"string","format":"date-time","title":"Open Timestamp"},"fill_tx_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fill Tx Hash"},"fill_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fill Block"},"fill_timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Fill Timestamp"},"status":{"$ref":"#/components/schemas/OrderStatus"},"points":{"type":"string","title":"Points"},"reward_type":{"anyOf":[{"$ref":"#/components/schemas/RewardType"},{"type":"null"}]},"reward_value":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Reward Value"},"routes":{"items":{"type":"string"},"type":"array","title":"Routes"},"to_platform_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"To Platform Id"},"order_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Value"},"bridge_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bridge Order Id"},"deposit_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Address"}},"type":"object","required":["order_id","from_chain","from_token","from_address","from_amount","to_chain","to_token","to_amount","to_address","open_tx_hash","open_block","open_timestamp","status","points"],"title":"OrderResponse"},"TokenInfo":{"properties":{"symbol":{"type":"string","title":"Symbol"},"name":{"type":"string","title":"Name"},"decimals":{"type":"integer","title":"Decimals"},"address":{"type":"string","title":"Address"},"chain_id":{"type":"integer","title":"Chain Id"},"logo":{"type":"string","title":"Logo"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"listed":{"type":"boolean","title":"Listed","default":true},"fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]}},"type":"object","required":["symbol","name","decimals","address","chain_id","logo"],"title":"TokenInfo"},"FeeLevel":{"type":"string","enum":["Group1","Group2"],"title":"FeeLevel"},"OrderStatus":{"type":"string","enum":["Open","Filled","Failed","Refund"],"title":"OrderStatus"},"RewardType":{"type":"string","enum":["xp","usdt"],"title":"RewardType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ### Get Orders > Query cross-chain orders — acts as a transaction explorer.\ > Supports filtering by address, chain, token, status, bridge, tx hash, and time range.\ > \ > Table structure: Quote LEFT JOIN Transaction LEFT JOIN ExternalTransaction\ > \- Transaction/ExternalTransaction hold destination-chain fill info\ > \- fill\_tx\_hash = COALESCE(Transaction.tx\_hash, ExternalTransaction.tx\_hash)\ > \- Status: same-chain = filled; cross-chain depends on Transaction/ExternalTransaction state\ > \ > When an address filter is provided, relay deposit history from the Relay API is\ > also fetched and merged with local DB results (deduplicated by bridge\_order\_id).\ > \ > When \`use\_deposit\_address=True\`, only orders that went through a deposit address\ > flow (Quote.deposit is not null) are returned. The \`address\` parameter still\ > filters by sender. ```json {"openapi":"3.1.0","info":{"title":"API Reference","version":"0.1.0"},"tags":[{"name":"API Reference"}],"servers":[{"url":"https://api.wheelx.fi","description":"Production"}],"paths":{"/v1/orders":{"get":{"summary":"Get Orders","description":"Query cross-chain orders — acts as a transaction explorer.\nSupports filtering by address, chain, token, status, bridge, tx hash, and time range.\n\nTable structure: Quote LEFT JOIN Transaction LEFT JOIN ExternalTransaction\n- Transaction/ExternalTransaction hold destination-chain fill info\n- fill_tx_hash = COALESCE(Transaction.tx_hash, ExternalTransaction.tx_hash)\n- Status: same-chain = filled; cross-chain depends on Transaction/ExternalTransaction state\n\nWhen an address filter is provided, relay deposit history from the Relay API is\nalso fetched and merged with local DB results (deduplicated by bridge_order_id).\n\nWhen `use_deposit_address=True`, only orders that went through a deposit address\nflow (Quote.deposit is not null) are returned. The `address` parameter still\nfilters by sender.","operationId":"get_orders_v1_orders_get","parameters":[{"name":"address","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Address"}},{"name":"network","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Network","default":"mainnet"}},{"name":"from_chain","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"From Chain"}},{"name":"to_chain","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"To Chain"}},{"name":"from_token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Token"}},{"name":"to_token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To Token"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"bridge","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bridge"}},{"name":"deposit_tx_hash","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Tx Hash"}},{"name":"fill_tx_hash","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fill Tx Hash"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Date"}},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Date"}},{"name":"use_deposit_address","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Use Deposit Address"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","default":"request_id","title":"Sort By"}},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","default":"desc","title":"Sort Order"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrdersByAddressResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["API Reference"]}}},"components":{"schemas":{"Network":{"type":"string","enum":["mainnet","testnet"],"title":"Network"},"OrdersByAddressResponse":{"properties":{"orders":{"items":{"$ref":"#/components/schemas/OrderResponse"},"type":"array","title":"Orders"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["orders","total"],"title":"OrdersByAddressResponse"},"OrderResponse":{"properties":{"order_id":{"type":"string","title":"Order Id"},"from_chain":{"type":"integer","title":"From Chain"},"from_token":{"type":"string","title":"From Token"},"from_token_info":{"anyOf":[{"$ref":"#/components/schemas/TokenInfo"},{"type":"null"}]},"from_address":{"type":"string","title":"From Address"},"from_amount":{"type":"string","title":"From Amount"},"to_chain":{"type":"integer","title":"To Chain"},"to_token":{"type":"string","title":"To Token"},"to_token_info":{"anyOf":[{"$ref":"#/components/schemas/TokenInfo"},{"type":"null"}]},"to_amount":{"type":"string","title":"To Amount"},"to_address":{"type":"string","title":"To Address"},"open_tx_hash":{"type":"string","title":"Open Tx Hash"},"open_block":{"type":"integer","title":"Open Block"},"open_timestamp":{"type":"string","format":"date-time","title":"Open Timestamp"},"fill_tx_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fill Tx Hash"},"fill_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fill Block"},"fill_timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Fill Timestamp"},"status":{"$ref":"#/components/schemas/OrderStatus"},"points":{"type":"string","title":"Points"},"reward_type":{"anyOf":[{"$ref":"#/components/schemas/RewardType"},{"type":"null"}]},"reward_value":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Reward Value"},"routes":{"items":{"type":"string"},"type":"array","title":"Routes"},"to_platform_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"To Platform Id"},"order_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Value"},"bridge_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bridge Order Id"},"deposit_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Address"}},"type":"object","required":["order_id","from_chain","from_token","from_address","from_amount","to_chain","to_token","to_amount","to_address","open_tx_hash","open_block","open_timestamp","status","points"],"title":"OrderResponse"},"TokenInfo":{"properties":{"symbol":{"type":"string","title":"Symbol"},"name":{"type":"string","title":"Name"},"decimals":{"type":"integer","title":"Decimals"},"address":{"type":"string","title":"Address"},"chain_id":{"type":"integer","title":"Chain Id"},"logo":{"type":"string","title":"Logo"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"listed":{"type":"boolean","title":"Listed","default":true},"fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]}},"type":"object","required":["symbol","name","decimals","address","chain_id","logo"],"title":"TokenInfo"},"FeeLevel":{"type":"string","enum":["Group1","Group2"],"title":"FeeLevel"},"OrderStatus":{"type":"string","enum":["Open","Filled","Failed","Refund"],"title":"OrderStatus"},"RewardType":{"type":"string","enum":["xp","usdt"],"title":"RewardType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ### GET /v1/chain-info > Chain Info ```json {"openapi":"3.1.0","info":{"title":"API Reference","version":"0.1.0"},"tags":[{"name":"API Reference"}],"servers":[{"url":"https://api.wheelx.fi","description":"Production"}],"paths":{"/v1/chain-info":{"get":{"summary":"Chain Info","operationId":"chain_info_v1_chain_info_get","parameters":[{"name":"network","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Network","default":"mainnet"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChainInfoResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["API Reference"]}}},"components":{"schemas":{"Network":{"type":"string","enum":["mainnet","testnet"],"title":"Network"},"ChainInfoResponse":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/ChainInfo"},"type":"array","title":"Chains"},"tokens":{"items":{"$ref":"#/components/schemas/TokenInfo"},"type":"array","title":"Tokens"},"deposit_platforms":{"additionalProperties":{"$ref":"#/components/schemas/DepositPlatform"},"type":"object","title":"Deposit Platforms"},"slippage_policies":{"items":{"$ref":"#/components/schemas/SlippagePolicy"},"type":"array","title":"Slippage Policies"}},"type":"object","required":["chains","tokens","slippage_policies"],"title":"ChainInfoResponse"},"ChainInfo":{"properties":{"server_name":{"type":"string","title":"Server Name"},"name":{"type":"string","title":"Name"},"chain_id":{"type":"integer","title":"Chain Id"},"rpc_url":{"type":"string","title":"Rpc Url","default":""},"rpc_fallback":{"items":{"type":"string"},"type":"array","title":"Rpc Fallback"},"chain_icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chain Icon"},"is_testnet":{"type":"boolean","title":"Is Testnet","default":false},"is_popular":{"type":"boolean","title":"Is Popular","default":false},"eth_token":{"type":"string","title":"Eth Token","default":"0x0000000000000000000000000000000000000000"},"usdc_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdc Token"},"usdt_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdt Token"},"support_kline":{"type":"boolean","title":"Support Kline","default":false},"rpc_endpoints":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rpc Endpoints"},"is_evm":{"type":"boolean","title":"Is Evm","default":true},"inbound":{"type":"boolean","title":"Inbound","default":true},"outbound":{"type":"boolean","title":"Outbound","default":true},"support_sponsor_gas":{"type":"boolean","title":"Support Sponsor Gas","default":false}},"type":"object","required":["server_name","name","chain_id"],"title":"ChainInfo"},"TokenInfo":{"properties":{"symbol":{"type":"string","title":"Symbol"},"name":{"type":"string","title":"Name"},"decimals":{"type":"integer","title":"Decimals"},"address":{"type":"string","title":"Address"},"chain_id":{"type":"integer","title":"Chain Id"},"logo":{"type":"string","title":"Logo"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"listed":{"type":"boolean","title":"Listed","default":true},"fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]}},"type":"object","required":["symbol","name","decimals","address","chain_id","logo"],"title":"TokenInfo"},"FeeLevel":{"type":"string","enum":["Group1","Group2"],"title":"FeeLevel"},"DepositPlatform":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/DepositPlatformChain"},"type":"array","title":"Chains"},"tokens":{"items":{"$ref":"#/components/schemas/DepositPlatformToken"},"type":"array","title":"Tokens"}},"type":"object","title":"DepositPlatform"},"DepositPlatformChain":{"properties":{"server_name":{"type":"string","title":"Server Name"},"name":{"type":"string","title":"Name"},"chain_id":{"type":"integer","title":"Chain Id"},"rpc_url":{"type":"string","title":"Rpc Url","default":""},"rpc_fallback":{"items":{"type":"string"},"type":"array","title":"Rpc Fallback"},"chain_icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chain Icon"},"is_testnet":{"type":"boolean","title":"Is Testnet","default":false},"is_popular":{"type":"boolean","title":"Is Popular","default":false},"eth_token":{"type":"string","title":"Eth Token","default":"0x0000000000000000000000000000000000000000"},"usdc_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdc Token"},"usdt_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdt Token"},"support_kline":{"type":"boolean","title":"Support Kline","default":false},"rpc_endpoints":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rpc Endpoints"},"is_evm":{"type":"boolean","title":"Is Evm","default":true},"inbound":{"type":"boolean","title":"Inbound","default":true},"outbound":{"type":"boolean","title":"Outbound","default":true},"support_sponsor_gas":{"type":"boolean","title":"Support Sponsor Gas","default":false},"platform_id":{"type":"integer","title":"Platform Id"},"platform_type":{"items":{"type":"string"},"type":"array","title":"Platform Type"}},"type":"object","required":["server_name","name","chain_id","platform_id"],"title":"DepositPlatformChain"},"DepositPlatformToken":{"properties":{"symbol":{"type":"string","title":"Symbol"},"name":{"type":"string","title":"Name"},"decimals":{"type":"integer","title":"Decimals"},"address":{"type":"string","title":"Address"},"chain_id":{"type":"integer","title":"Chain Id"},"logo":{"type":"string","title":"Logo"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"listed":{"type":"boolean","title":"Listed","default":true},"fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]},"chain_icon":{"type":"string","title":"Chain Icon"},"platform_type":{"items":{"type":"string"},"type":"array","title":"Platform Type"},"platform_id":{"type":"integer","title":"Platform Id"}},"type":"object","required":["symbol","name","decimals","address","chain_id","logo","chain_icon","platform_id"],"title":"DepositPlatformToken"},"SlippagePolicy":{"properties":{"bridge":{"type":"boolean","title":"Bridge"},"from_fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]},"to_fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]},"default_slippage":{"type":"integer","title":"Default Slippage"},"min_slippage":{"type":"integer","title":"Min Slippage"},"max_slippage":{"type":"integer","title":"Max Slippage"},"refresh_interval":{"type":"integer","title":"Refresh Interval"},"notice_rounds":{"type":"integer","title":"Notice Rounds"}},"type":"object","required":["bridge","from_fee_level","to_fee_level","default_slippage","min_slippage","max_slippage","refresh_interval","notice_rounds"],"title":"SlippagePolicy"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` #### Use Cases **Centralized Exchange (CEX) Withdrawals** Allow users to withdraw funds from your exchange directly to a deposit address. WheelX automatically bridges the funds to the destination chain specified by the user. No additional wallet connection or signing is required from the end user. **Fiat Onramps** Accept fiat deposits, convert to crypto, and send funds to a deposit address. The onramp provider only needs to support standard token transfers — no smart contract integration is required. **Payment Processing** Generate unique deposit addresses for each customer or invoice. Accept payments in multiple cryptocurrencies across multiple chains while settling in a single asset on a single chain. **Cross-Chain Treasury Management** Collect funds from various blockchains and automatically consolidate them into a preferred asset on a preferred chain, simplifying treasury operations and reducing manual intervention. **B2B Settlement** Enable business partners to settle payments using their preferred blockchain and token, while receiving funds in your treasury asset of choice. The merchant markup feature allows you to pass settlement costs to payers or absorb them as a business incentive. #### Conclusion WheelX Payment provides a complete solution for cross-chain asset reception with flexible fee configuration, robust error handling, and comprehensive monitoring capabilities. The system is designed to integrate seamlessly into existing applications while providing enterprise-grade reliability for cross-chain payments. #### Supported Chains\&Tokens
NetworkTokenContract Address
EthereumETH0x0000000000000000000000000000000000000000
EthereumUSDC0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
EthereumUSDT0xdac17f958d2ee523a2206206994597c13d831ec7
BaseETH0x0000000000000000000000000000000000000000
BaseUSDC0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
BNB ChainBNB0x0000000000000000000000000000000000000000
BNB ChainUSDT0x55d398326f99059ff775485246999027b3197955
SolanaUSDCEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
SolanaUSDTEs9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB
TronUSDTTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
# Smart Contracts Explore WheelX's smart contract architecture and published deployment addresses. Use these resources to understand the protocol's core components and verify the addresses used by WheelX. # Architecture WheelX separates off-chain route discovery and transaction preparation from user-authorized on-chain execution. Users retain custody of their assets and approve or sign transactions through their own wallets.
This diagram is a conceptual overview of the EVM execution flow. Individual routes may use different external protocols and execution steps. ### Execution Flow 1. **Quote and route preparation**: WheelX's API or SDK evaluates available routes and prepares the transaction data required for execution. 2. **User authorization**: The transaction is returned to the user's wallet for approval and signature. 3. **On-chain execution**: Published WheelX EVM components support token approvals, DEX routing, and native-asset receiving flows. 4. **External protocol execution**: DEX liquidity and cross-chain transfers are executed through integrated external protocols according to the selected route. ### Published EVM Components * **ERC20 Approval Proxy**: Supports ERC20 token approval within applicable execution flows. * **Dex Router**: Executes authorized on-chain routing and DEX interactions. * **WheelX Native Token Receiver**: Receives native assets within supported transaction flows. * **Maker and Dispatcher**: Published EOA addresses used by the WheelX execution system. Contract and EOA addresses are listed on the [Deployment Addresses](/features/smart-contracts/deployment-addresses) page. ### Security Model * Users retain custody and authorize transactions from their own wallets. * Contract and execution addresses are published for independent verification. * Execution is separated from off-chain quote and route preparation. * Available security reviews are published under [Contract Audit Reports](/safety-and-security/contract-audits-reports). > # Deployment Addresses The Maker addresses for various platforms, chains, and products are listed for transparency. | Tag | Category | Address | | ---------------------------- | -------------- | ------------------------------------------ | | Maker | EOA Address | 0x4fd0FC39eb0d56FE8250496DbFC81c39B1021ac6 | | Dispatcher | EOA Address | 0xed650f0fb785f48ff2624d8ce027780d7c780288 | | ERC20 Approval Proxy | Smart contract | 0x7eC9672678509a574F6305F112a7E3703845a98b | | Dex Router | Smart contract | 0x6222f99443A0d75bd96d40F2904606f60f37cdc2 | | WheelX Native Token Receiver | Smart contract | 0xB10F9Ec04A66b69E3831e1e5b1E6B9D41081B6CC | # AI Route Optimization WheelX uses AI-driven algorithms to optimize transaction routes in real-time, selecting the best execution path across multiple dimensions — price, speed, slippage, gas cost, and liquidity depth.
#### How It Works When a user submits an intent (e.g., swap Token A on Chain X for Token B on Chain Y), the AI Router evaluates all available execution paths in parallel: 1. **Path discovery** — The router identifies every viable route across supported DEXs, bridges, and liquidity pools. 2. **Multi-dimensional scoring** — Each path is scored across five optimization dimensions: * **Price** — Best available output amount across aggregated liquidity sources * **Speed** — Estimated fill time based on current network congestion and bridge latency * **Slippage** — Predicted slippage based on trade size vs. pool depth * **Gas cost** — Total gas expenditure across all hops in the route * **Liquidity depth** — Available pool capacity to absorb the trade without adverse price impact 3. **Optimal selection** — The path with the highest composite score is selected and executed. Less optimal paths are discarded. 4. **Continuous learning** — Every executed transaction feeds back into the model, improving future routing decisions based on real-world performance data. #### Key Differentiator: Dynamic vs Static Routing | | Static Routing | AI Routing | | ------------------- | ------------------------------------- | -------------------------------------------------------------------- | | Path selection | Fixed pre-configured routes | Real-time dynamic evaluation | | Market response | Does not adapt to changing conditions | Instantly adjusts to price shifts, congestion, and liquidity changes | | Optimization scope | Single dimension (usually price) | Multi-dimensional (price, speed, slippage, gas, liquidity) | | Learning capability | No improvement over time | Continuously improves from every executed transaction | #### Benefits * **Better execution prices** — Aggregates liquidity from multiple DEXs and bridges to find the best available price * **Faster transaction completion** — Avoids congested chains and slow bridges in real time * **Reduced slippage** — Matches trade size to pool depth, routing large trades through deeper liquidity sources * **Lower gas costs** — Optimizes route structure to minimize total gas across all hops * **Adaptive to market conditions** — Responds instantly to price movements, network congestion, and liquidity shifts # Multi-Router Quote Comparison Get full visibility into every evaluated route — see quotes side-by-side before you commit.
### How It Works When you request a quote, the WheelX API doesn't just return one route — it returns **all viable routes** with complete metrics for each, so you can compare and choose with confidence. 1. **Submit a quote request** — Specify your source token, destination token, and amount via the Quote API. 2. **Receive multiple routes** — The API evaluates all available liquidity sources (DEXs, bridges, aggregators) and returns every viable path, each with its full cost breakdown. 3. **AI tags the optimal route** — The AI Router scores every route across Price, Speed, Slippage, Gas, and Liquidity, and marks the best one with an `optimal` tag. 4. **Choose your path** — Use the AI-recommended route, or select any alternative route manually via `select_route`. > **Multi-Router Quote Comparison is the transparency layer of AI Route Optimization** — while the AI Router automatically selects the optimal path, this feature gives developers full visibility into all evaluated routes and the reasoning behind each selection. *** ### What's Compared Each route in the quote response includes these metrics: | Metric | Description | | --------------------------- | ------------------------------------------------------------------------ | | **Output Amount** | The exact amount of destination tokens you'll receive | | **Fee** | Total fees (network gas + bridge fees + DEX fees), broken down by source | | **Time** | Estimated fill time in seconds, based on current network conditions | | **Slippage / Price Impact** | Expected price impact based on trade size vs. pool depth | | **Route Path** | The full execution path (e.g., DEX-A direct, or Bridge → DEX-B combined) | | **AI Recommendation** | Tag indicating whether the route is optimal, fastest, or lowest-gas | *** ### Two Selection Modes #### AI Auto-Select (Default) The AI Router evaluates all routes and automatically executes the one with the highest composite score across Price, Speed, Slippage, Gas, and Liquidity. No manual intervention needed. #### Manual Select Developers can inspect all route metrics and manually specify `select_route` to choose a specific path — for example, preferring the fastest route for time-sensitive trades, or the lowest-gas route for cost optimization. *** ### Benefits * **Full transparency** — Every route's cost, timing, and risk metrics are visible. No hidden fees or opaque routing. * **Developer control** — Inspect, compare, and manually override the AI's recommendation when your use case demands it. * **Better decision-making** — See exactly why the AI chose a route. If a slightly slower route yields 0.6% more output, you decide whether the extra wait is worth it. * **Auditable routing** — Track and log every evaluated route for compliance, reporting, or optimization analysis. * **Flexible integration** — Use the Quote API's `quotes` array to build custom route-selection UIs in your wallet or dApp. *** # Gas Fee Estimation Every cost is estimated upfront and included in the quoted output — no hidden fees, no surprises after signing.
### What Users See Before a user signs a transaction, WheelX shows a clear breakdown of the total cost impact. Instead of presenting a single opaque fee number, we break it into three transparent components: | Component | Description | Example | | ---------------------- | ---------------------------------------------------------- | ------------------------- | | **Swap Impact** | Price impact caused by moving through DEX liquidity | -$0.02 (-0.68%) | | **Dst Gas Fee** | Destination chain gas required to complete the transaction | **Free** (when sponsored) | | **WheelX Fee** | Platform service fee for using WheelX infrastructure | -$0.06 | | **Total Price Impact** | Sum of all cost components | **-$0.08** | **The output amount shown is already net of all fees.** The user receives exactly what the quote displays — no additional charges are deducted after confirmation. ### How It Works #### 1. Real-time price and gas data WheelX continuously pulls live data from every supported chain and liquidity source, including: * DEX pool prices and depth (for price impact) * Current gas prices on source and destination chains * Bridge relay costs and relayer availability #### 2. Multi-hop route simulation For routes that include multiple steps (e.g., bridge + swap), the system simulates each step and calculates the cumulative cost impact. This includes: * Price impact on each DEX leg * Gas cost on the destination chain * Any bridge or relay fees * The WheelX platform fee #### 3. Fee sponsorship layer Where enabled, WheelX can sponsor the destination gas fee so the user sees **Dst Gas Fee: Free**. This is especially important for payments and onboarding flows where users may not hold the destination chain's native token. *** ### Fee Components Explained #### Swap Impact Swap impact occurs when the trade size is large relative to the liquidity available in the DEX pool. It is expressed as both a dollar amount and a percentage of the trade. > **Example:** A -$0.02 impact on an $11.72 trade means the user receives 0.68% less than the mid-market price due to DEX slippage. #### Dst Gas Fee This is the gas required to execute the final transaction on the destination chain. Depending on configuration, it may be: * **Paid by user** — Deducted from the output or required as native gas token * **Sponsored** — Covered by the merchant, app, or WheelX fee system, shown as **Free** to the user #### WheelX Fee The platform service fee for routing, bridging, and executing the transaction through WheelX infrastructure. It is always shown in dollar terms and deducted from the output amount. *** ### Why It Matters * **No surprises** — All costs are visible before signing. Users know exactly what they will receive. * **No extra gas tokens needed** — Sponsored gas fees let users pay with any token from any chain. * **Better UX for payments** — Merchants can absorb gas costs so customers only see a clean final amount. * **Easy comparison** — Total price impact makes it simple to compare routes across different bridges or DEXs. * **Budget-friendly** — Large transactions are easy to plan because the full cost is quoted upfront. ### From Fee Estimation to Gasless Payments Gas fee estimation is the foundation for fully **gasless transactions**: 1. **Estimate** the destination gas fee accurately. 2. **Sponsor** that fee via the Fee Sponsorship system. 3. **Show users a clean quote** where the only visible cost is the platform fee and swap impact. This is how WheelX enables users to pay from any chain with any token — even if they don't hold ETH, BNB, or other native gas tokens on the destination chain. # Supported Chains * **Supported Blockchains**: The platform supports 50+ chains, including both EVM and non-EVM blockchains. | Chain Name | Native Token | | ------------- | ------------ | | Ethereum | ETH | | Base | ETH | | Arbitrum | ETH | | Optimism | ETH | | BNB Chain | BNB | | opBNB | BNB | | Linea | ETH | | Unichain | ETH | | Sonic | S | | Soneium | ETH | | Polygon | POL | | Ink | ETH | | Mantle | MNT | | Gravity | G | | Scroll | ETH | | zkSync Era | ETH | | Taiko | ETH | | BOB | ETH | | Blast | ETH | | Mode | ETH | | X Layer | OKB | | WorldChain | ETH | | Morph | ETH | | Hemi | ETH | | Celo | CELO | | Avalanche | AVAX | | Gnosis | GNO | | Abstract | ETH | | Zora | ETH | | Zircuit | ETH | | XDC | XDC | | Stable | gUSDT | | Sei | SEI | | Rootstock | RBTC | | Ronin | RON | | RARI | ETH | | Polygon zkEVM | ETH | | Plume | PLUME | | Plasma | XPL | | Monad | MON | | Metis | METIS | | MegaETH | ETH | | Manta | ETH | | Lisk | ETH | | Katana | ETH | | IOTA EVM | IOTA | | HyperEVM | HYPE | | HashKey Chain | HSK | | Flow EVM | FLR | | Flare | FLR | | Etherlink | XTZ | | Cronos | CRO | | Berachain | BERA | | Tempo | PathUSD | | Hyperliquid | USDC | | Robinhood | ETH | | Solana | SOL | | Tron | USDT | # Supported Tokens ## Supported Tokens WheelX supports a wide range of digital and tokenized assets, enabling seamless execution across multiple asset classes and blockchain ecosystems. From native crypto tokens to real-world assets such as tokenized stocks and metals, WheelX allows users to access and transact across different markets within a single unified interface. #### Crypto Tokens
WheelX supports a broad spectrum of crypto assets across multiple chains, providing deep liquidity and flexible execution options. **Major Assets** * BTC (Bitcoin) – Including native BTC and wrapped variants such as WBTC * ETH (Ethereum) – Native ETH and equivalent tokens on EVM-compatible chains #### Stable Coins Widely used for trading, bridging, and liquidity routing, for example : * USDT * USDC * USAT * USD1 * DAI **Altcoins** Includes a wide range of ecosystem tokens across supported chains, enabling diverse trading strategies and access to different protocols. Such as : $SOL (Solana), $ARB (Arbitrum), $BNB and others. **Meme Coins** WheelX also supports popular meme tokens, allowing users to trade and route liquidity even in highly volatile markets from ecosystems such as Solana, Base, Ethereum, Tempo and others. #### Tokenized Stocks WheelX enables access to tokenized representations of US equities, allowing users to interact with traditional financial assets in a blockchain environment. **Supported Environments** * **EVM-Based Networks** (e.g., Ethereum, BNB Chain)
* **Solana-Based Assets** (e.g., xStocks ecosystem)
These assets allow users to gain exposure to traditional markets while maintaining on-chain flexibility. #### Tokenized Metals WheelX supports tokenized metal assets, enabling users to gain exposure to commodities such as gold, silver, and copper directly on-chain. These assets can be used within swaps, cross-chain execution, and portfolio diversification strategies. **Gold** WheelX supports leading tokenized gold assets that are backed by physical reserves and widely used across DeFi ecosystems. * **Tether Gold (XAUt)**
Ethereum: `0x68749665FF8D2d112Fa859AA293F07A622782F38` BNB Chain: `0x21cAef8A43163Eea865baeE23b9C2E327696A3bf` * **Paxos Gold (PAXG)**
* Ethereum: `0x45804880de22913dafe09f4980848ece6ecbaf78` These assets provide a digital representation of gold while maintaining liquidity and composability within blockchain ecosystems. **Silver** Tokenized silver allows users to access another major precious metal in a programmable format. * **Kinesis Silver (KAG)**
* Ethereum: `0x56ba8b58b7d1f6d384a1c4dd553f39ebc8741b8e` **Copper** In addition to precious metals, WheelX also supports exposure to industrial metals through tokenized assets. * **Global X Copper Miners ETF (COPXon)**
* Ethereum: `0x423a63dfe8d82cd9c6568c92210aa537d8ef6885` #### Prediction Markets A prediction market is a type of marketplace where users can trade on the outcome of future events. Instead of buying traditional assets, participants take positions based on whether they believe a specific event will happen or not.Each outcome is typically represented as a tradable position, with prices reflecting the market’s collective probability of that event occurring.
Within WheelX, prediction markets can be integrated into the broader execution layer, allowing users to interact with outcome-based assets alongside crypto, tokenized metals, and tokenized equities.
# Overview Learn how WheelX reduces execution risk and provides transparency around its smart-contract security. This section is intended for users, developers, security reviewers, and integration teams evaluating the protocol. ### Review Security Controls * **For users evaluating transaction protection** — [MEV Protection](/safety-and-security/mev-protection): Understand how WheelX reduces exposure to Maximal Extractable Value during transaction execution. * **For developers, auditors, and risk teams** — [Contract Audit Reports](/safety-and-security/contract-audits-reports): Review audited contracts, independent audit reports, source code, and deployment references. # MEV Protection MEV Protection Protect your transactions from Maximal Extractable Value (MEV) attacks.
### What is MEV? Maximal Extractable Value (MEV) refers to the value that block producers or observers can extract by reordering, inserting, or censoring transactions within a block. The most common MEV attack is a **Sandwich Attack** — an attacker front-runs your trade (buys before you), pushes the price up, then back-runs (sells after you) to profit at your expense. ### Protection Mechanisms * **Private transaction submission** — Transactions are submitted through private channels where supported by the chain, bypassing the public mempool. Attackers cannot observe your trade before execution. * **Slippage protection** — Configurable thresholds ensure your trade only executes if the output amount is within your acceptable range. If price deviation exceeds your threshold, the transaction is automatically reverted. * **MEV-aware routing** — The AI Router evaluates candidate paths for MEV exposure and preferentially selects routes with lower extractable value, reducing attacker opportunity. * **Private relay integration** — For chains that support private relay infrastructure, transactions are submitted directly to block builders, completely bypassing the public mempool. ### Intent-Based Routing: Built-in MEV Resistance WheelX's Intent-based routing provides inherent MEV protection. You only submit the desired outcome ("I want Token B from Token A"), not the execution path. This means: * **No path details exposed** — attackers can't predict which route your trade will take * **Internal orchestration** — the AI Router selects and executes the path privately * **No manual multi-step signing** — each step is handled internally, not submitted to public mempools individually ### Benefits * **Prevent sandwich attacks** — Private submission and MEV-aware routing eliminate front-run/back-run opportunities * **Reduce value loss from front-running** — Transactions that can't be seen can't be exploited * **Fair execution for all transaction sizes** — Same protection regardless of trade size # Contract Audit Reports WheelX smart contracts have been reviewed by independent third-party security firms. All audit reports are publicly available. ### Audited Contracts The audit covers the core Solidity contracts in the [wheelx-contracts](https://github.com/wheelx-fi/wheelx-contracts/tree/main/src) repository: | Contract | Description | | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | [ApprovalProxy.sol](https://github.com/wheelx-fi/wheelx-contracts/blob/main/src/ApprovalProxy.sol) | Proxy contract handling token approvals and multicall operations | | [Multicall3Router.sol](https://github.com/wheelx-fi/wheelx-contracts/blob/main/src/Multicall3Router.sol) | Router contract integrating Multicall3 for batch operations and Permit2 for gas-efficient approvals | | [WheelxReceiver.sol](https://github.com/wheelx-fi/wheelx-contracts/blob/main/src/WheelxReceiver.sol) | Receiver contract for handling deposits and forwarding calls | | [MerkleWithdraw.sol](https://github.com/wheelx-fi/wheelx-contracts/blob/main/src/MerkleWithdraw.sol) | Merkle Tree-based withdrawal contract supporting multiple tokens | Supporting libraries in [`src/libs/`](https://github.com/wheelx-fi/wheelx-contracts/tree/main/src/libs): `IRouter.sol`, `Panic.sol`, `Revert.sol`, `SafeApproveLib.sol`. ### Audit Reports #### ABDK Consulting | | | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Auditor** | ABDK Consulting | | **Date** | September 3, 2025 | | **Scope** | WheelX Contracts v1.0 | | **Report** | [ABDK\_WheelX\_WheelXContracts\_v\_1\_0.pdf](https://github.com/abdk-consulting/audits/blob/main/wheelx/ABDK_WheelX_WheelXContracts_v_1_0.pdf) | | **Mirror** | [wheelx-contracts/audits/](https://github.com/wheelx-fi/wheelx-contracts/tree/main/audits) | ### Source Code All audited contract source code is open-source and publicly available: * **Repository**: [github.com/wheelx-fi/wheelx-contracts](https://github.com/wheelx-fi/wheelx-contracts) * **License**: MIT * **Build tooling**: Foundry ### Deployments Contracts are deployed with deterministic addresses across all supported chains: | Contract | Address | | ---------------- | -------------------------------------------- | | ApprovalProxy | `0x7eC9672678509a574F6305F112a7E3703845a98b` | | Multicall3Router | `0x6222f99443A0d75bd96d40F2904606f60f37cdc2` | | WheelxReceiver | `0xB10F9Ec04A66b69E3831e1e5b1E6B9D41081B6CC` | Supported networks include Ethereum, Optimism, Arbitrum, Base, Unichain, BNB Smart Chain, opBNB, Polygon, Linea, ZKSync, Mode, Lisk, Celo, Zora, Katana, Bob, Taiko, Scroll, HEMI, XLayer, HyperEVM, and Abstract. ### Responsible Disclosure If you discover a vulnerability in WheelX contracts, please report it responsibly to the team before public disclosure. # Overview Explore WheelX programs for users, partners, creators, and community contributors. Choose the program that matches how you want to participate in and grow the WheelX ecosystem. ### Find Your Program * **For active WheelX users** — [Community Dividend Program](/programs/community-dividend-program): Earn XP through eligible activity and learn how WheelX community rewards work. * **For referral partners and distribution channels** — [Affiliate Program](/programs/affiliate-program): Create referral channels and earn commissions from qualified activity. * **For creators and industry voices** — [Influencer Program](/programs/influencer-program): Review eligibility, benefits, responsibilities, and performance rewards. * **For long-term community contributors** — [Ambassador Program](/programs/ambassador-program): Explore ambassador roles, responsibilities, evaluation criteria, and benefits. # Community Dividend Program
WheelX is an AI-powered bridge & swap aggregator that helps and serves users in exploring DeFi with lower fees, faster speed, and stronger security — ultimately delivering and creating value for users. At the same time, WheelX is also a community-driven collective that represents connection, hope, and happiness. The growth of WheelX cannot happen without every member of the community, which is why we believe that each community member is an essential shareholder of WheelX. Every user who trades or engages on WheelX can earn XP, which represents the ‘options’ of being a shareholder. With these ‘options,’ once certain thresholds are met, users can redeem them for ‘dividends’ from the platform’s revenue. Additionally, every community member can invite others to join WheelX and earn generous referral rewards. The better WheelX grows, the more every community member — as a shareholder — will share in its abundant rewards. ## How to get XP? | | | | | -------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Source | Details | XP | | Bridge & Swap | Successfully complete a bridge or swap | Each transaction will earn a certain amount of XP | | Deploy | Successfully deploy a contract on the mainnet | 50 XP per deployment (no XP on testnet) | | GM | Successfully complete a check in with onchain GM | Fixed 3 XP per GM | | Referral | Successfully invite and the referee completes a transaction | The referee earns XP through Swap, Bridge, Deploy or GM. The referrer receives the same amount of XP at a 1:1 ratio. | | Social Task | Join the Discord server | 20 XP, limited to once | | Newcomer Bonus | First time connecting a wallet (not via an referral link) | Automatically receive 1,000 XP | | | First time connecting a wallet (via an refferal link) | Automatically receive 1,500 XP | | | First time connecting a wallet (via an Alpha refferal link) | Automatically receive 1,800 XP | | | First time connecting a wallet (via an Influencer referral link) | Automatically receive 2,000 XP | * Referral rewards and XP booster do not apply to social tasks or newcomer bouns. This means referrers will not receive the same XP rewards for social tasks and newcomer tasks fom referees. At the same time, XP from social tasks and newcomer bonus will only be granted at the base 1× rate. * To avoid data inconsistencies, XP will temporarily be based on EVM addresses. Swaps on Solana and bridges from Solana will not count toward XP for now. * Simply connecting a Solana wallet address will not automatically grant the newcomer bonus. ## XP Booster Upgrade As you earn more XP(options), accumulating into certain ranges, you will receive different booster levels. The more XP (options) you accumulate, the higher your XP booster becomes. For example, if your booster is 1x, a transaction earns 100 XP. If your booster is 1.2x, the same transaction will earn 120 XP. The specific levels are as follows: | | | | ---------------- | ------- | | Total XP | Booster | | 0 - 1500 XP | 1x | | 1501-3000 XP | 1.1x | | 3001 - 10000 XP | 1.2x | | 10001 - 20000 XP | 1.3x | | 20001-100000 XP | 1.4x | | 100000+ XP | 1.5x | ### **XP Booster Privileges for Special Users:** | | | | | ------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------- | | Special Users | Details | Starting Booster | | WheelX Alpha | Participated in the WheelX Alpha Galxe Campaign and are OAT holders: | 1.2X | | | | | | Influencer | X Blue Verified Accounts.How to verify your identity and address? Simply DM your address to on X. | 1.3X | * Special users get a unique icon on the dividends page to show off their status. * If a user has multiple roles, the highest booster applies by default. * To level up to the next booster, special users need to meet the cumulative XP thresholds. * To avoid data inconsistencies, XP will temporarily be based on EVM addresses. Swaps on Solana and bridges from Solana will not count toward XP for now. ## Dividend Mechanism ### Initial Dividend Rate：**2,800 XP = $1** * The redeemed dividends will be paid in USDT on the Base network. * Please note that this rate is not fixed. Since part of the XP calculation is based on ETH as the settlement token, fluctuations in the ETH price will affect the rate. Additionally, the rate will also be linked to WheelX’s business development, particularly its revenue. WheelX reserves the final right of interpretation for the dividend mechanism. ### Dividend Redemption/Withdrawal Requirements Users need to meet specific thresholds to redeem or withdraw dividends. A daily withdrawal limit is also enforced for risk management. | | | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Redemption/Withdrawal Limit | Detail | | $5 | Users can only start redeeming or withdrawing once their accumulated XP reaches the equivalent of $5. Users may also choose to accumulate more than $5 before redeeming or withdrawing. | | $1000 | Each user can redeem or withdraw up to $1,000 per day. This limit may be adjusted in the future based on risk control considerations. | ## **Q\&A** ### **About XP** * **Will my XP be consumed after redeeming dividends or making a withdrawal?** Yes, it will. We have designed XP as **redeemable XP** and **redeemed XP**. The XP spent will be recorded as redeemed XP. However, your total accumulated XP remains permanently valid. * **Does XP have any value besides redeeming dividends?** WheelX places great importance on the community. Although XP is somewhat similar to points in other projects, we provide real value by quickly converting it into dividends. In addition, XP will have more uses in the future, potentially including lotteries, gift redemptions, and more. Most importantly, we track each user’s total accumulated XP. Even if XP is spent through dividends, redemption, or other means, the total XP remains permanently valid. Total XP serves as a very important credential for every user. ### **About Dividends** * **I saw in the promotion that users can earn up to 30% cashback and commission. How is this calculated?** Based on the current rate, when a user’s booster is 1X, they can earn 10% cashback. If the user also invites other users who remain active, they can earn at least an additional 10% cashback plus commission. Since each user can have a maximum XP booster of 1.5X, the maximum a user can earn is 15% + 15% cashback and commission, totaling 30% in dividends. ### **About Referrals** * Are there any benefits to being a referee? Yes. If you join WheelX directly and connect your wallet, you will receive a 1,000 XP newcomer bonus. But if you join WheelX via someone else’s invitation, the newcomer bonus will be 1,500 XP — that’s 50% more. If you join via an influencer’s invitation, the newcomer bonus will be 2,000 XP — 100% more. In addition, every trade you make and every smart contract you deploy will earn you a certain amount of XP. Once your XP accumulates to a certain threshold, it can be redeemed for cashback. * **I became a WheelX user without using an invitation link. Can I still be invited later?** Yes. As long as you haven’t been invited before, you can become a referee at any time. * **I invited friend A. Can A invite me back?** If your address hasn’t been used as someone else’s referee, it’s possible. However, if you’ve already been successfully invited by another user, your friend A cannot invite you again. Generally, two “clean” addresses that haven’t been linked can invite each other. # Affiliate Program ## Affiliate Program
#### Background As WheelX continues to grow, partnering with protocols, expanding integrations, and building through market cycles, its mission remains clear: democratize access to decentralized liquidity, simplify cross-chain operations, and empower traders, developers, and communities in the multi-chain future.To accelerate adoption and reward contributors, WheelX introduced the Affiliate Program (accessible at offers both an affiliate program and an agent-based partnership model, allowing users and partners to participate in ecosystem growth and earn rewards.This initiative invites website owners, project developers, influencers, and dApp builders to integrate WheelX’s powerful API & SDK, share custom referral links, and earn high commissions (up to 15 — 20% on trading fees) from every transaction driven through their channels. It’s a true mutual benefit model: partners help expand WheelX’s reach while enjoying passive, performance-based income in ETH or USDT. WheelX is more than a tool’s infrastructure for the next era of DeFi. With the Affiliate Program now live, the opportunity to participate and profit is here. **Affiliate Program** The affiliate program allows users to earn commissions by referring new users to WheelX.Participants can share referral links and receive rewards based on the activity generated by their referrals. This model is simple, accessible, and does not require active user management.Link : **Agent Program** In addition to affiliates, WheelX also supports an agent (partner) model for users who want to play a more active role in ecosystem growth.Agents typically: * Bring in users, communities, or traffic * Support onboarding and engagement * May receive customized incentive structures or higher rewards This model is designed for partners, KOLs, and community leaders who want to build and scale within the WheelX ecosystem.Link : #### Key Benefits * Competitive Commissions start from 10% Commissions are calculated proportionally from the trading fees generated by users via your link/channel. * The rate is tiered (increases progressively as your channel’s cumulative trading volume grows). * Can start 20% for channels with unique value or special contributions (e.g., deep integration, high-quality traffic, or large-scale projects). This higher rate is typically negotiable/special, offering strong passive income potential for serious partners and needs to discuss it directly with our BD. * Focus on API & SDK Integration The program prioritizes partners with their own website or project. You can integrate WheelX by: * Creating a dedicated menu (e.g., “Bridge & Swap via WheelX”). * Adding a custom button or widget for swaps/bridges. * Using other methods, like embedding the SDK in your dApp. * API documentation is available at . * If you’re using the API/SDK and want to join the commission program, contact the team directly for custom setup. #### Channel Links & Customization * After registering (connect your wallet at affiliate.wheelx.fi), you’ll receive a referral link that can be customized with your brand or name. * Important: The link can be changed only once. Once updated, the new link takes effect, but transaction history from the old link remains tracked and continues to generate commissions. The original link stays valid even after customization. #### Commission Calculation & Settlement. * Valid transactions: Every trade, bridge, or swap made through your link generates fees shared as commission. * Higher trade frequency and volume lead to bigger commissions (and potential for higher tier rates). * Payments: In ETH (for ETH-anchored pairs) or USDT (for other pairs). * Schedule: On the 3rd of each following month (if it falls on a weekend, postponed to the next Monday). Commissions are claimable manually on the Base network. #### How to Join (3 Simple Steps) 1. Open.
2. Copy the link and embed it to your dedicated menu/button
3. You can also customize the code (1 time only)
#### Special Rates For further discussion, such as special rates (including potential 20%), technical integration, or any questions: Username : @Brian\_WheelX Link : # Influencer Program
WheelX is a community-driven Bridge & Swap DeFi platform, and we aim to build a closer connection with social platforms. As the most active social media platform in Web3, X — along with its Blue verified users — serves as the perfect bridge for this connection. In mid-September 2025, we launched a call for X Blue verified users, which received an enthusiastic response. Based on the valuable feedback and suggestions we received, we’ve now officially upgraded it to the WheelX Influencer Program. *** #### Who Is Eligible to Become a WheelX Influencer? As long as you’re an X Blue verified user, you can become a WheelX Influencer — no matter how many followers you have. *** #### What Are the Benefits of Being a WheelX Influencer? **🏆 1. Special Privileges in the Community Dividend Program** You’ll enjoy higher rewards and commissions as part of the community dividend program. * **1.3× XP Booster:** Instantly receive a 1.3× XP multiplier for trading and smart contract deployments (normally, boosters must be unlocked gradually). * **Referral Rewards:** Your referees will receive 2,000 XP (worth $2) as a newcomer bonus — that’s 100% more than usual! You’ll earn XP 1:1 with your referees’ trading and deployment activities. (e.g., if your referee earns 100 XP, you’ll also receive 100 XP.) 👉 Check details here: **💎 2. Exclusive Status** * Receive the Influencer role in the WheelX Discord server → * Get an exclusive blue verification icon on the WheelX platform to showcase your distinguished status → **🌐 3. Exclusive Community Privileges** * Be invited to the X private community exclusively for X Blue verified users. * Gain access to the Influencer-only channel on WheelX Discord for special updates and events. **⚙️ 4. Platform Perks** * Early access to new features. * Exclusive raffle opportunities. * Priority access to official merchandise and gifts. *** #### How to Become a WheelX Influencer **Step 1:** As an X Blue verified user, comment your address under the tweet or DM your address to @WheelX\_fi. (Your address is essential for verification and helps us confirm your X Blue status.) **Step 2:** We’ll add your address to the WheelX Influencer Address List and grant you the Influencer role on our Guild platform. **Step 3:** Once both steps are completed, we’ll DM you on X to confirm your status and invite you to the Influencer community. **Step 4:** You can verify your status and privileges at and claim your Influencer role at . *** #### Responsibilities of a WheelX Influencer * Actively promote and introduce WheelX to your followers — don’t forget to use the hashtag #WheelXInfluencer and include your referral link! * Participate in WheelX events and campaigns. * Grow your XP on — XP serves as a key metric for measuring your impact and performance. *** #### Extra Rewards for Top-Performing Influencers Every month, we’ll announce the Top 10 Influencers by new XP in our X community and Discord Influencer channel. 🏅 Top 10 Influencers will receive: * **Extra XP bonuses** (which increase your dividends and commissions). * **Greater exposure** — your posts will be amplified by the official WheelX account. * **Exclusive opportunities** to join AMAs as featured guests. # Ambassador Program
### Background As the Web3 ecosystem continues to mature, community-driven growth has become one of the most important factors behind successful protocols. At WheelX, we believe that real adoption doesn’t come from hype alone it comes from people who actively use the product, share knowledge, and connect ecosystems. That’s why we’re launching the WheelX Ambassador Program: an initiative designed to empower builders, creators, and connectors to grow alongside WheelX while earning long-term rewards. ### Why the WheelX Ambassador Program? WheelX has grown rapidly as a bridge & swap aggregator, integrating dozens of networks, wallets, DEXs, and DApps. But sustainable growth requires more than technology. It requires people who understand the product and can help onboard the next wave of users. The Ambassador Program is built to: * Encourage meaningful contributions instead of short-term shilling * Reward consistent, high-quality engagement * Create a global network of WheelX advocates across regions and platforms Whether you’re a content creator, community organizer, or ecosystem connector, there’s a role for you in shaping the future of WheelX. ### Ambassador Responsibilities As a WheelX Ambassador, you are expected to actively contribute to the growth of the WheelX ecosystem while representing the brand in a positive, authentic, and value-driven way. Ambassadors are encouraged to: * Develop a solid understanding of WheelX’s products, features, mission, and long-term vision * Represent and uphold the WheelX brand image across Web3 communities and social platforms * Actively support and amplify official WheelX content, announcements, and campaigns * Build and maintain strong connections between WheelX and your own Web3 community * Share updates about new features, integrations, partnerships, and incentive programs * Encourage community members to use WheelX, participate in campaigns, and explore cross-chain opportunities * Support or participate in online and offline community activities, such as AMAs, Spaces, workshops, or meetups From time to time, WheelX may assign optional tasks to ambassadors. These may include actions such as retweeting posts, writing educational articles, creating videos, hosting discussions, or assisting with campaign outreach. While not all tasks are mandatory, ambassadors are encouraged to contribute based on their strengths and availability. ### Structure for the Ambassador As interest in the program continues to grow, we have received thousands of applications from creators and community members around the world. To ensure a fair opportunity for high-impact contributors, we will be implementing a clearer and more structured evaluation system. ### Promotion & Relegation Structure The updated program will introduce a two-tier system: League 1 and League 2. * A promotion and relegation mechanism will be implemented between League 1 and League 2. * The bottom 20% of ambassadors in League 1 will be relegated to League 2. * The top 20% performers in League 2 will be promoted to League 1. * Only League 1 ambassadors will be eligible for the monthly reward pool. * League 2 will consist of selected candidates who will go through a one-month observation period, during which their ability to promote WheelX and generate measurable results will be evaluated. ### Ambassador Roles at WheelX To ensure clarity and fair evaluation, the program is structured into several specialized roles. Each role has its own focus, KPIs, and reward structure. #### Affiliate Ambassador Affiliate Ambassadors focus on user acquisition and product adoption by introducing new users to WheelX through referral-driven activities. Typical contributions include: * Sharing personal referral links across social platforms and communities * Educating new users on how to bridge, swap, or use WheelX features * Supporting onboarding during campaigns or migration incentive programs Each successful referral and on-chain activity generated through the affiliate link contributes to XP earnings, directly tying rewards to real user growth. This role is ideal for users who: * Actively use WheelX * Have access to active Web3 communities * Prefer growth-driven contributions over content creation By aligning incentives with real usage, the Affiliate Ambassador role helps ensure that WheelX grows through genuine demand and active participation. #### Content Ambassador Content Ambassadors focus on education and awareness. This includes creating tutorials, threads, articles, videos, or explainers about WheelX features, integrations, and use cases. Typical contributions: * Twitter/X threads and long-form posts * Medium articles or blog content * Short videos or visual explainers Impact is measured by consistency, clarity, and engagement, not just raw impressions. #### Connector Ambassador Connector Ambassadors help expand the WheelX ecosystem by building relationships with other projects, communities, and partners. Typical contributions: * Introducing WheelX to other protocols or communities * Supporting co-marketing or integration discussions * Helping WheelX reach new ecosystems and regions This role is ideal for those with strong Web3 networks and ecosystem experience. #### Space Host Ambassador Space Host Ambassadors lead conversations and community engagement through live sessions such as Twitter/X Spaces or AMAs. Typical contributions: * Hosting or co-hosting Spaces about WheelX * Inviting guests from partner projects * Moderating discussions and Q\&A sessions This role emphasizes communication skills and community leadership. ### What Ambassadors Receive As a WheelX Ambassador, you gain access to both tangible and long-term benefits, including: * Ambassador Role identity and recognition * A $1,000 monthly reward pool is allocated to support ambassador incentives * Extra XP can be earned through cross-role contribution * Referral and affiliate commissions, tied to real user activity * Early access to internal testing, beta features, or upcoming campaigns * Direct communication opportunities with other ambassadors and the WheelX team * Opportunities to represent WheelX in community events, Spaces, or partner activities ### Transparent KPIs and Fair Evaluation Each ambassador role has clearly defined KPIs, such as: * Content quality and engagement * Consistency over time * Community feedback and reach * Strategic value brought to WheelX Performance is reviewed periodically to ensure fairness, transparency, and sustainability. The KPIs will be explained if you successfully pass the interview. ### Product Experience & Content Authenticity We strongly encourage ambassadors to personally explore and experience the WheelX product and ecosystem before publishing promotional content. This helps ensure that the content remains authentic, informative, and aligned with the product itself. Please note that we are able to track on-chain activity and product interactions, and the depth of your exploration will be considered an important factor in our evaluation process. ### Referral Tracking & Performance Metrics In addition, the volume of transactions and number of referrals are also key indicators in our evaluation framework. When promoting WheelX, please make sure to include your referral link, so we can properly track and measure the real impact of your contributions. ### Who Should Apply? The WheelX Ambassador Program is open to: * Web3 creators and educators * Community managers and moderators * Ecosystem builders and connectors * Anyone who genuinely uses and believes in WheelX You don’t need to be famous you need to be consistent, authentic, and value-driven. WheelX reserves the right to review, suspend, or terminate an Ambassador’s role at its discretion should the Ambassador fail to meet the established performance standards, KPIs, or program expectations over time. **Apply here :** **** # Getting Started Use this section to integrate with the WheelX API from understanding the available capabilities to sending your first request and handling production issues. Developers new to WheelX should begin with the API Overview and Quick Start. ### Choose Your Starting Point * **New to the WheelX API** — [API Overview](/api-and-developer/getting-started/api-overview): Review the base URL, available capabilities, endpoints, and response model. * **Ready to make a first request** — [Quick Start](/api-and-developer/getting-started/quick-start): Configure your environment, request a quote, execute a transaction, and check its status. * **Looking for endpoint details** — [API Reference](/api-and-developer/getting-started/api-reference): Review request parameters, response schemas, and supported API operations. * **Preparing a production integration** — [Authentication & Rate Limits](/api-and-developer/getting-started/authentication-and-rate-limits): Understand API access, request limits, and recommended practices. * **Resolving an integration issue** — [Troubleshooting](/api-and-developer/getting-started/troubleshooting): Diagnose common API errors and transaction-processing scenarios. ### Recommended Integration Path 1. Read [API Overview](/api-and-developer/getting-started/api-overview). 2. Complete [Quick Start](/api-and-developer/getting-started/quick-start). 3. Use [API Reference](/api-and-developer/getting-started/api-reference) during implementation. 4. Review [Authentication & Rate Limits](/api-and-developer/getting-started/authentication-and-rate-limits) before production launch. # API Overview WheelX provides a RESTful API for programmatic access to cross-chain swap, bridge, and quote functionality. ### Base URL ``` https://api.wheelx.fi/v1 ``` ### Key Capabilities * Query supported chains and tokens * Get real-time swap and bridge quotes * Submit and track orders * Webhook integration for real-time updates ### Available Endpoints | Method | Endpoint | Description | | ------ | ---------------- | -------------------------------- | | GET | `/v1/chain-info` | List supported chains and tokens | | POST | `/v1/quote` | Get a swap or bridge quote | | GET | `/v1/order/{id}` | Get order details by ID | | GET | `/v1/orders` | List orders for an address | ### Response Format All responses use JSON. Success returns HTTP 200. Errors include an `error` object with details. # 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. # API Reference ## POST /v1/quote > Quote ```json {"openapi":"3.1.0","info":{"title":"WheelX SDK API","version":"0.1.0"},"servers":[{"url":"https://api.wheelx.fi"}],"paths":{"/v1/quote":{"post":{"summary":"Quote","operationId":"quote_v1_quote_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"QuoteRequest":{"properties":{"from_chain":{"type":"integer","title":"From Chain"},"to_chain":{"type":"integer","title":"To Chain"},"from_token":{"type":"string","title":"From Token"},"to_token":{"type":"string","title":"To Token"},"from_address":{"type":"string","title":"From Address"},"to_address":{"type":"string","title":"To Address"},"amount":{"type":"integer","title":"Amount"},"slippage":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Slippage"},"affiliation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Affiliation"},"external_bridge":{"type":"boolean","title":"External Bridge","default":false},"to_platform_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"To Platform Id"},"select_route":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Select Route"},"sponsor_gas":{"type":"boolean","title":"Sponsor Gas","default":false},"use_deposit_address":{"type":"boolean","title":"Use Deposit Address","default":false},"exact_out":{"type":"boolean","title":"Exact Out","default":false},"strict":{"type":"boolean","title":"Strict","default":false}},"type":"object","required":["from_chain","to_chain","from_token","to_token","from_address","to_address","amount"],"title":"QuoteRequest"},"QuoteResponse":{"properties":{"request_id":{"type":"string","title":"Request Id"},"amount_out":{"type":"string","title":"Amount Out"},"fee":{"type":"string","title":"Fee"},"tx":{"anyOf":[{"$ref":"#/components/schemas/Tx"},{"$ref":"#/components/schemas/SolanaTx"},{"$ref":"#/components/schemas/TronTx"},{"type":"null"}],"title":"Tx"},"approve":{"anyOf":[{"$ref":"#/components/schemas/ApproveAction"},{"type":"null"}]},"slippage":{"type":"integer","title":"Slippage"},"min_receive":{"type":"string","title":"Min Receive"},"estimated_time":{"type":"number","title":"Estimated Time","default":10},"recipient":{"type":"string","title":"Recipient"},"router_type":{"$ref":"#/components/schemas/RouterType","default":"swap"},"price_impact":{"$ref":"#/components/schemas/PriceImpactFormatted"},"router":{"type":"string","title":"Router","default":"wheelx"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"points":{"type":"string","title":"Points"},"quote_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Message"},"routes":{"items":{"$ref":"#/components/schemas/RouteInfo"},"type":"array","title":"Routes"},"deposit_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Address"},"approve_tx":{"anyOf":[{"$ref":"#/components/schemas/Tx"},{"$ref":"#/components/schemas/SolanaTx"},{"$ref":"#/components/schemas/TronTx"},{"type":"null"}],"title":"Approve Tx"},"swap_tx":{"anyOf":[{"$ref":"#/components/schemas/Tx"},{"$ref":"#/components/schemas/SolanaTx"},{"$ref":"#/components/schemas/TronTx"},{"type":"null"}],"title":"Swap Tx"},"gas_fee":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gas Fee"},"bridge_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bridge Order Id"},"amount_in":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Amount In"},"quotes":{"anyOf":[{"items":{"$ref":"#/components/schemas/QuoteItem"},"type":"array"},{"type":"null"}],"title":"Quotes"}},"type":"object","required":["request_id","amount_out","fee","slippage","min_receive","recipient","price_impact","created_at","points"],"title":"QuoteResponse"},"Tx":{"properties":{"to":{"type":"string","title":"To"},"value":{"type":"string","title":"Value"},"data":{"type":"string","title":"Data"},"chainId":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chainid"},"gas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gas"},"maxFeePerGas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Maxfeepergas"},"maxPriorityFeePerGas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Maxpriorityfeepergas"}},"type":"object","required":["to","value","data"],"title":"Tx"},"SolanaTx":{"properties":{"tx":{"type":"string","title":"Tx"},"sender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender"},"gas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gas"}},"type":"object","required":["tx"],"title":"SolanaTx"},"TronTx":{"properties":{"parameter":{"additionalProperties":true,"type":"object","title":"Parameter"},"type":{"type":"string","title":"Type","default":"TriggerSmartContract"},"gas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gas"},"chainId":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chainid"}},"type":"object","required":["parameter"],"title":"TronTx","description":"TRON TriggerSmartContract transaction from Relay API."},"ApproveAction":{"properties":{"token":{"type":"string","title":"Token"},"spender":{"type":"string","title":"Spender"},"amount":{"type":"integer","title":"Amount"}},"type":"object","required":["token","spender","amount"],"title":"ApproveAction"},"RouterType":{"type":"string","enum":["swap","bridge","wrap","unwrap"],"title":"RouterType"},"PriceImpactFormatted":{"additionalProperties":{"type":"string"},"type":"object"},"RouteInfo":{"properties":{"name":{"type":"string","title":"Name"},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo"}},"type":"object","required":["name"],"title":"RouteInfo"},"QuoteItem":{"properties":{"request_id":{"type":"string","title":"Request Id"},"router":{"type":"string","title":"Router"},"amount_out":{"type":"string","title":"Amount Out"},"tx":{"anyOf":[{"$ref":"#/components/schemas/Tx"},{"$ref":"#/components/schemas/SolanaTx"},{"$ref":"#/components/schemas/TronTx"},{"type":"null"}],"title":"Tx"},"routes":{"items":{"$ref":"#/components/schemas/RouteInfo"},"type":"array","title":"Routes"},"gas_fee":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gas Fee"},"points":{"type":"string","title":"Points","default":"0"}},"type":"object","required":["request_id","router","amount_out"],"title":"QuoteItem"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## GET /v1/order/{request\_id} > Get Order ```json {"openapi":"3.1.0","info":{"title":"WheelX SDK API","version":"0.1.0"},"servers":[{"url":"https://api.wheelx.fi"}],"paths":{"/v1/order/{request_id}":{"get":{"summary":"Get Order","operationId":"get_order_v1_order__request_id__get","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"OrderResponse":{"properties":{"order_id":{"type":"string","title":"Order Id"},"from_chain":{"type":"integer","title":"From Chain"},"from_token":{"type":"string","title":"From Token"},"from_token_info":{"anyOf":[{"$ref":"#/components/schemas/TokenInfo"},{"type":"null"}]},"from_address":{"type":"string","title":"From Address"},"from_amount":{"type":"string","title":"From Amount"},"to_chain":{"type":"integer","title":"To Chain"},"to_token":{"type":"string","title":"To Token"},"to_token_info":{"anyOf":[{"$ref":"#/components/schemas/TokenInfo"},{"type":"null"}]},"to_amount":{"type":"string","title":"To Amount"},"to_address":{"type":"string","title":"To Address"},"open_tx_hash":{"type":"string","title":"Open Tx Hash"},"open_block":{"type":"integer","title":"Open Block"},"open_timestamp":{"type":"string","format":"date-time","title":"Open Timestamp"},"fill_tx_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fill Tx Hash"},"fill_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fill Block"},"fill_timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Fill Timestamp"},"status":{"$ref":"#/components/schemas/OrderStatus"},"points":{"type":"string","title":"Points"},"reward_type":{"anyOf":[{"$ref":"#/components/schemas/RewardType"},{"type":"null"}]},"reward_value":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Reward Value"},"routes":{"items":{"type":"string"},"type":"array","title":"Routes"},"to_platform_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"To Platform Id"},"order_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Value"},"bridge_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bridge Order Id"},"deposit_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Address"}},"type":"object","required":["order_id","from_chain","from_token","from_address","from_amount","to_chain","to_token","to_amount","to_address","open_tx_hash","open_block","open_timestamp","status","points"],"title":"OrderResponse"},"TokenInfo":{"properties":{"symbol":{"type":"string","title":"Symbol"},"name":{"type":"string","title":"Name"},"decimals":{"type":"integer","title":"Decimals"},"address":{"type":"string","title":"Address"},"chain_id":{"type":"integer","title":"Chain Id"},"logo":{"type":"string","title":"Logo"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"listed":{"type":"boolean","title":"Listed","default":true},"fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]}},"type":"object","required":["symbol","name","decimals","address","chain_id","logo"],"title":"TokenInfo"},"FeeLevel":{"type":"string","enum":["Group1","Group2"],"title":"FeeLevel"},"OrderStatus":{"type":"string","enum":["Open","Filled","Failed","Refund"],"title":"OrderStatus"},"RewardType":{"type":"string","enum":["xp","usdt"],"title":"RewardType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Get Orders > Query cross-chain orders — acts as a transaction explorer.\ > Supports filtering by address, chain, token, status, bridge, tx hash, to\_address, and time range.\ > \ > Table structure: Quote LEFT JOIN Transaction LEFT JOIN ExternalTransaction\ > \- Transaction/ExternalTransaction hold destination-chain fill info\ > \- fill\_tx\_hash = COALESCE(Transaction.tx\_hash, ExternalTransaction.tx\_hash)\ > \- Status: same-chain = filled; cross-chain depends on Transaction/ExternalTransaction state\ > \ > When an address filter is provided, relay deposit history from the Relay API is\ > also fetched and merged with local DB results (deduplicated by bridge\_order\_id).\ > \ > When \`use\_deposit\_address=True\`, only orders that went through a deposit address\ > flow (Quote.deposit is not null) are returned. The \`address\` parameter still\ > filters by sender. ```json {"openapi":"3.1.0","info":{"title":"WheelX SDK API","version":"0.1.0"},"servers":[{"url":"https://api.wheelx.fi"}],"paths":{"/v1/orders":{"get":{"summary":"Get Orders","description":"Query cross-chain orders — acts as a transaction explorer.\nSupports filtering by address, chain, token, status, bridge, tx hash, to_address, and time range.\n\nTable structure: Quote LEFT JOIN Transaction LEFT JOIN ExternalTransaction\n- Transaction/ExternalTransaction hold destination-chain fill info\n- fill_tx_hash = COALESCE(Transaction.tx_hash, ExternalTransaction.tx_hash)\n- Status: same-chain = filled; cross-chain depends on Transaction/ExternalTransaction state\n\nWhen an address filter is provided, relay deposit history from the Relay API is\nalso fetched and merged with local DB results (deduplicated by bridge_order_id).\n\nWhen `use_deposit_address=True`, only orders that went through a deposit address\nflow (Quote.deposit is not null) are returned. The `address` parameter still\nfilters by sender.","operationId":"get_orders_v1_orders_get","parameters":[{"name":"address","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Address"}},{"name":"network","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Network","default":"mainnet"}},{"name":"from_chain","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"From Chain"}},{"name":"to_chain","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"To Chain"}},{"name":"from_token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Token"}},{"name":"to_token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To Token"}},{"name":"to_address","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To Address"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"bridge","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bridge"}},{"name":"deposit_tx_hash","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Tx Hash"}},{"name":"fill_tx_hash","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fill Tx Hash"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Date"}},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Date"}},{"name":"use_deposit_address","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Use Deposit Address"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","default":"request_id","title":"Sort By"}},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","default":"desc","title":"Sort Order"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrdersByAddressResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Network":{"type":"string","enum":["mainnet","testnet"],"title":"Network"},"OrdersByAddressResponse":{"properties":{"orders":{"items":{"$ref":"#/components/schemas/OrderResponse"},"type":"array","title":"Orders"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["orders","total"],"title":"OrdersByAddressResponse"},"OrderResponse":{"properties":{"order_id":{"type":"string","title":"Order Id"},"from_chain":{"type":"integer","title":"From Chain"},"from_token":{"type":"string","title":"From Token"},"from_token_info":{"anyOf":[{"$ref":"#/components/schemas/TokenInfo"},{"type":"null"}]},"from_address":{"type":"string","title":"From Address"},"from_amount":{"type":"string","title":"From Amount"},"to_chain":{"type":"integer","title":"To Chain"},"to_token":{"type":"string","title":"To Token"},"to_token_info":{"anyOf":[{"$ref":"#/components/schemas/TokenInfo"},{"type":"null"}]},"to_amount":{"type":"string","title":"To Amount"},"to_address":{"type":"string","title":"To Address"},"open_tx_hash":{"type":"string","title":"Open Tx Hash"},"open_block":{"type":"integer","title":"Open Block"},"open_timestamp":{"type":"string","format":"date-time","title":"Open Timestamp"},"fill_tx_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fill Tx Hash"},"fill_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fill Block"},"fill_timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Fill Timestamp"},"status":{"$ref":"#/components/schemas/OrderStatus"},"points":{"type":"string","title":"Points"},"reward_type":{"anyOf":[{"$ref":"#/components/schemas/RewardType"},{"type":"null"}]},"reward_value":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Reward Value"},"routes":{"items":{"type":"string"},"type":"array","title":"Routes"},"to_platform_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"To Platform Id"},"order_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Value"},"bridge_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bridge Order Id"},"deposit_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Address"}},"type":"object","required":["order_id","from_chain","from_token","from_address","from_amount","to_chain","to_token","to_amount","to_address","open_tx_hash","open_block","open_timestamp","status","points"],"title":"OrderResponse"},"TokenInfo":{"properties":{"symbol":{"type":"string","title":"Symbol"},"name":{"type":"string","title":"Name"},"decimals":{"type":"integer","title":"Decimals"},"address":{"type":"string","title":"Address"},"chain_id":{"type":"integer","title":"Chain Id"},"logo":{"type":"string","title":"Logo"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"listed":{"type":"boolean","title":"Listed","default":true},"fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]}},"type":"object","required":["symbol","name","decimals","address","chain_id","logo"],"title":"TokenInfo"},"FeeLevel":{"type":"string","enum":["Group1","Group2"],"title":"FeeLevel"},"OrderStatus":{"type":"string","enum":["Open","Filled","Failed","Refund"],"title":"OrderStatus"},"RewardType":{"type":"string","enum":["xp","usdt"],"title":"RewardType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## GET /v1/deposit-address-config > Get Deposit Address Config ```json {"openapi":"3.1.0","info":{"title":"WheelX SDK API","version":"0.1.0"},"servers":[{"url":"https://api.wheelx.fi"}],"paths":{"/v1/deposit-address-config":{"get":{"summary":"Get Deposit Address Config","operationId":"get_deposit_address_config_v1_deposit_address_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAddressConfigResponse"}}}}}}}},"components":{"schemas":{"DepositAddressConfigResponse":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/DepositChainConfig"},"type":"array","title":"Chains"},"tokens":{"items":{"$ref":"#/components/schemas/DepositTokenConfig"},"type":"array","title":"Tokens"}},"type":"object","required":["chains","tokens"],"title":"DepositAddressConfigResponse"},"DepositChainConfig":{"properties":{"id":{"type":"integer","title":"Id"},"from_enable":{"type":"boolean","title":"From Enable"},"to_enable":{"type":"boolean","title":"To Enable"},"chain":{"type":"integer","title":"Chain"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"chain_info":{"anyOf":[{"$ref":"#/components/schemas/ChainInfo"},{"type":"null"}]}},"type":"object","required":["id","from_enable","to_enable","chain"],"title":"DepositChainConfig"},"ChainInfo":{"properties":{"server_name":{"type":"string","title":"Server Name"},"name":{"type":"string","title":"Name"},"chain_id":{"type":"integer","title":"Chain Id"},"rpc_url":{"type":"string","title":"Rpc Url","default":""},"rpc_fallback":{"items":{"type":"string"},"type":"array","title":"Rpc Fallback"},"chain_icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chain Icon"},"is_testnet":{"type":"boolean","title":"Is Testnet","default":false},"is_popular":{"type":"boolean","title":"Is Popular","default":false},"eth_token":{"type":"string","title":"Eth Token","default":"0x0000000000000000000000000000000000000000"},"usdc_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdc Token"},"usdt_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdt Token"},"support_kline":{"type":"boolean","title":"Support Kline","default":false},"rpc_endpoints":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rpc Endpoints"},"is_evm":{"type":"boolean","title":"Is Evm","default":true},"inbound":{"type":"boolean","title":"Inbound","default":true},"outbound":{"type":"boolean","title":"Outbound","default":true},"support_sponsor_gas":{"type":"boolean","title":"Support Sponsor Gas","default":false}},"type":"object","required":["server_name","name","chain_id"],"title":"ChainInfo"},"DepositTokenConfig":{"properties":{"id":{"type":"integer","title":"Id"},"direction":{"type":"string","title":"Direction"},"token_name":{"type":"string","title":"Token Name"},"token_address":{"type":"string","title":"Token Address"},"enable":{"type":"boolean","title":"Enable"},"chain":{"type":"integer","title":"Chain"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"token_info":{"anyOf":[{"$ref":"#/components/schemas/TokenInfo"},{"type":"null"}]}},"type":"object","required":["id","direction","token_name","token_address","enable","chain"],"title":"DepositTokenConfig"},"TokenInfo":{"properties":{"symbol":{"type":"string","title":"Symbol"},"name":{"type":"string","title":"Name"},"decimals":{"type":"integer","title":"Decimals"},"address":{"type":"string","title":"Address"},"chain_id":{"type":"integer","title":"Chain Id"},"logo":{"type":"string","title":"Logo"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"listed":{"type":"boolean","title":"Listed","default":true},"fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]}},"type":"object","required":["symbol","name","decimals","address","chain_id","logo"],"title":"TokenInfo"},"FeeLevel":{"type":"string","enum":["Group1","Group2"],"title":"FeeLevel"}}}} ``` ## GET /v1/chain-info > Chain Info ```json {"openapi":"3.1.0","info":{"title":"WheelX SDK API","version":"0.1.0"},"servers":[{"url":"https://api.wheelx.fi"}],"paths":{"/v1/chain-info":{"get":{"summary":"Chain Info","operationId":"chain_info_v1_chain_info_get","parameters":[{"name":"network","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Network","default":"mainnet"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChainInfoResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Network":{"type":"string","enum":["mainnet","testnet"],"title":"Network"},"ChainInfoResponse":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/ChainInfo"},"type":"array","title":"Chains"},"tokens":{"items":{"$ref":"#/components/schemas/TokenInfo"},"type":"array","title":"Tokens"},"deposit_platforms":{"additionalProperties":{"$ref":"#/components/schemas/DepositPlatform"},"type":"object","title":"Deposit Platforms"},"slippage_policies":{"items":{"$ref":"#/components/schemas/SlippagePolicy"},"type":"array","title":"Slippage Policies"}},"type":"object","required":["chains","tokens","slippage_policies"],"title":"ChainInfoResponse"},"ChainInfo":{"properties":{"server_name":{"type":"string","title":"Server Name"},"name":{"type":"string","title":"Name"},"chain_id":{"type":"integer","title":"Chain Id"},"rpc_url":{"type":"string","title":"Rpc Url","default":""},"rpc_fallback":{"items":{"type":"string"},"type":"array","title":"Rpc Fallback"},"chain_icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chain Icon"},"is_testnet":{"type":"boolean","title":"Is Testnet","default":false},"is_popular":{"type":"boolean","title":"Is Popular","default":false},"eth_token":{"type":"string","title":"Eth Token","default":"0x0000000000000000000000000000000000000000"},"usdc_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdc Token"},"usdt_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdt Token"},"support_kline":{"type":"boolean","title":"Support Kline","default":false},"rpc_endpoints":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rpc Endpoints"},"is_evm":{"type":"boolean","title":"Is Evm","default":true},"inbound":{"type":"boolean","title":"Inbound","default":true},"outbound":{"type":"boolean","title":"Outbound","default":true},"support_sponsor_gas":{"type":"boolean","title":"Support Sponsor Gas","default":false}},"type":"object","required":["server_name","name","chain_id"],"title":"ChainInfo"},"TokenInfo":{"properties":{"symbol":{"type":"string","title":"Symbol"},"name":{"type":"string","title":"Name"},"decimals":{"type":"integer","title":"Decimals"},"address":{"type":"string","title":"Address"},"chain_id":{"type":"integer","title":"Chain Id"},"logo":{"type":"string","title":"Logo"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"listed":{"type":"boolean","title":"Listed","default":true},"fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]}},"type":"object","required":["symbol","name","decimals","address","chain_id","logo"],"title":"TokenInfo"},"FeeLevel":{"type":"string","enum":["Group1","Group2"],"title":"FeeLevel"},"DepositPlatform":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/DepositPlatformChain"},"type":"array","title":"Chains"},"tokens":{"items":{"$ref":"#/components/schemas/DepositPlatformToken"},"type":"array","title":"Tokens"}},"type":"object","title":"DepositPlatform"},"DepositPlatformChain":{"properties":{"server_name":{"type":"string","title":"Server Name"},"name":{"type":"string","title":"Name"},"chain_id":{"type":"integer","title":"Chain Id"},"rpc_url":{"type":"string","title":"Rpc Url","default":""},"rpc_fallback":{"items":{"type":"string"},"type":"array","title":"Rpc Fallback"},"chain_icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chain Icon"},"is_testnet":{"type":"boolean","title":"Is Testnet","default":false},"is_popular":{"type":"boolean","title":"Is Popular","default":false},"eth_token":{"type":"string","title":"Eth Token","default":"0x0000000000000000000000000000000000000000"},"usdc_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdc Token"},"usdt_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdt Token"},"support_kline":{"type":"boolean","title":"Support Kline","default":false},"rpc_endpoints":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rpc Endpoints"},"is_evm":{"type":"boolean","title":"Is Evm","default":true},"inbound":{"type":"boolean","title":"Inbound","default":true},"outbound":{"type":"boolean","title":"Outbound","default":true},"support_sponsor_gas":{"type":"boolean","title":"Support Sponsor Gas","default":false},"platform_id":{"type":"integer","title":"Platform Id"},"platform_type":{"items":{"type":"string"},"type":"array","title":"Platform Type"}},"type":"object","required":["server_name","name","chain_id","platform_id"],"title":"DepositPlatformChain"},"DepositPlatformToken":{"properties":{"symbol":{"type":"string","title":"Symbol"},"name":{"type":"string","title":"Name"},"decimals":{"type":"integer","title":"Decimals"},"address":{"type":"string","title":"Address"},"chain_id":{"type":"integer","title":"Chain Id"},"logo":{"type":"string","title":"Logo"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"listed":{"type":"boolean","title":"Listed","default":true},"fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]},"chain_icon":{"type":"string","title":"Chain Icon"},"platform_type":{"items":{"type":"string"},"type":"array","title":"Platform Type"},"platform_id":{"type":"integer","title":"Platform Id"}},"type":"object","required":["symbol","name","decimals","address","chain_id","logo","chain_icon","platform_id"],"title":"DepositPlatformToken"},"SlippagePolicy":{"properties":{"bridge":{"type":"boolean","title":"Bridge"},"from_fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]},"to_fee_level":{"anyOf":[{"$ref":"#/components/schemas/FeeLevel"},{"type":"null"}]},"default_slippage":{"type":"integer","title":"Default Slippage"},"min_slippage":{"type":"integer","title":"Min Slippage"},"max_slippage":{"type":"integer","title":"Max Slippage"},"refresh_interval":{"type":"integer","title":"Refresh Interval"},"notice_rounds":{"type":"integer","title":"Notice Rounds"}},"type":"object","required":["bridge","from_fee_level","to_fee_level","default_slippage","min_slippage","max_slippage","refresh_interval","notice_rounds"],"title":"SlippagePolicy"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` # Authentication & Rate Limits ### API Keys Currently, the WheelX API is publicly accessible. API key authentication will be introduced for: * Higher rate limits * Priority routing * Advanced features ### Rate Limits | Tier | Limit | Window | | ---------------- | ----------- | ----------- | | Public | 20 requests | Per minute | | API Key (future) | Coming soon | Coming soon | ### Rate Limit Response When rate limited, the API returns: ``` HTTP 429 Too Many Requests ``` #### Best Practices * Implement exponential backoff on 429 responses * Cache chain-info responses (change infrequently) * Use webhooks instead of polling for order status # Troubleshooting Common issues and solutions for WheelX API integration. ### HTTP Error Codes | Code | Meaning | Solution | | ---- | ------------ | ------------------------------------------------- | | 400 | Bad Request | Check request body format and required parameters | | 404 | Not Found | Verify order ID or endpoint path | | 429 | Rate Limited | Implement exponential backoff | | 500 | Server Error | Retry with backoff; contact support if persistent | ### Common Scenarios #### Quote Returns Empty * Verify chain IDs and token addresses are correct * Check that the token pair is supported * Try a smaller amount if liquidity is insufficient #### Order Stuck in Processing * Cross-chain transactions may take several minutes * Check the source chain block explorer * Contact support if pending > 30 minutes #### Webhook Not Firing * Verify webhook URL is accessible * Check webhook secret configuration * Ensure events are properly subscribed # Integration Notes Review network-specific behavior and integration considerations before enabling a WheelX route in production. These notes complement the API Reference by documenting requirements that vary across execution environments and product types. #### Choose an Environment * **For EVM-compatible networks** — [EVM Support](/api-and-developer/integration-notes/evm-support): Review transaction and quote considerations for EVM integrations. * **For Solana integrations** — [Solana Support](/api-and-developer/integration-notes/solana-support): Review Solana-specific transaction requirements and quote examples. * **For Tron integrations** — [Tron Support](/api-and-developer/integration-notes/tron-support): Review the network ID, TRC-20 USDT requirements, Tron address format, and source-chain considerations. * **For Hyperliquid integrations** — [Hyperliquid Support](/api-and-developer/integration-notes/hyperliquid-support): Understand the integration flow and supported transaction behavior. * **For prediction-market applications** — [Prediction Market Support](/api-and-developer/integration-notes/prediction-market-support): Review supported markets and market-specific quote examples. # EVM Support WheelX supports standard EVM trading flows with the same quote format used across the API. ### What to Know * Use regular `0x...` wallet addresses in `from_address` * EVM routes return a standard EVM transaction payload in `tx` * You can execute the returned transaction with any EVM-compatible wallet client ### Quote Example This example requests a cross-chain EVM route 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 } ``` > For EVM routes, the response includes the transaction payload you can send directly with an EVM wallet. # Solana Support WheelX supports Solana through the standard quote flow. ### What to Know * Solana uses chain ID `1151111081099710` * Use the Solana chain ID above whenever the route includes Solana * Use a Solana-format address on the Solana side of the request ### Quote Example This example shows a Solana quote request. ``` { "from_chain": 1151111081099710, "to_chain": 1, "from_token": "11111111111111111111111111111111", "to_token": "0x0000000000000000000000000000000000000000", "from_address": "MNvtmkCofjdfiyttxPX4mfUjuG8uBHtC3WELPpFiEYP", "to_address": "0x1111111111111111111111111111111111111111", "amount": "10000000000", "slippage": 200, "affiliation": null, "to_platform_id": 0, "quote_only": true } ``` > Use chain ID `1151111081099710` when quoting a route that includes Solana. # Tron Support WheelX supports Tron through the standard quote flow. ### What to Know * Tron uses chain ID `728126428` * Use the Tron chain ID above whenever the route includes Tron * Tron currently supports TRC-20 USDT at contract address `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` * Use a Tron-format address on the Tron side of the request * When Tron is the source network, use a source address that can receive refunds * For centralized exchange withdrawals, select the **TRON / TRC-20** network ### Quote Example This example shows a Tron quote request. ``` { "from_chain": 728126428, "to_chain": 1, "from_token": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "to_token": "0xdac17f958d2ee523a2206206994597c13d831ec7", "from_address": "TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV", "to_address": "0x1111111111111111111111111111111111111111", "amount": "10000000", "slippage": 200, "affiliation": null, "to_platform_id": 0, "quote_only": true } ``` > Use chain ID `728126428` when quoting a route that includes Tron. # Hyperliquid Support WheelX supports Hyperliquid through the standard quote flow. ### What to Know * Hyperliquid and HyperEVM are handled as separate destinations * Use chain ID `1337` for Hyperliquid * Use the standard `POST /quote` request format * Set `to_address` to the wallet that will receive the routed funds on Hyperliquid * Keep `to_platform_id` as `0` for standard Hyperliquid routes ### Quote Example This example routes funds from Base into Hyperliquid. ``` { "from_chain": 8453, "to_chain": 1337, "from_token": "0x0000000000000000000000000000000000000000", "to_token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "from_address": "0x1111111111111111111111111111111111111111", "to_address": "0x1111111111111111111111111111111111111111", "amount": "1000000000000000000", "affiliation": null, "to_platform_id": 0, "quote_only": true } ``` > Replace the placeholder address with your own destination wallet before executing a live trade. # Prediction Market Support WheelX supports prediction market routing through the standard quote flow. ### Currently Supported Prediction Markets ### What to Know * Use the standard quote flow * Set `to_platform_id` to the target prediction market * Set `to_address` to the wallet that will receive the routed funds ### Quote Example #### Opinion ``` { "from_chain": 8453, "to_chain": 56, "from_token": "0x0000000000000000000000000000000000000000", "to_token": "0x55d398326f99059fF775485246999027B3197955", "from_address": "0x1111111111111111111111111111111111111111", "to_address": "0x1111111111111111111111111111111111111111", "amount": "1000000000000000000", "slippage": 200, "affiliation": null, "to_platform_id": 1, "quote_only": true } ``` #### Polymarket ``` { "from_chain": 8453, "to_chain": 137, "from_token": "0x0000000000000000000000000000000000000000", "to_token": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", "from_address": "0x1111111111111111111111111111111111111111", "to_address": "0x1111111111111111111111111111111111111111", "amount": "1000000000000000000", "slippage": 200, "affiliation": null, "to_platform_id": 3, "quote_only": true } ``` > Replace the placeholder address with your own destination wallet before executing a live trade. # Overview Choose the integration layer that best fits your application. WheelX provides SDKs in three languages for programmatic transaction flows, an MCP Server for AI-agent integrations, and a Widget for a ready-to-embed user interface. #### Choose an Integration Method * **Building with Python** — [Python SDK](https://docs.wheelx.fi/sdk-and-widget/python-sdk): Install the SDK, request quotes, and execute transactions in Python applications. * **Building for web or Node.js** — [JavaScript SDK](https://docs.wheelx.fi/sdk-and-widget/js-sdk): Integrate WheelX into browser and server-side JavaScript applications. * **Building high-performance services** — [Go SDK](https://docs.wheelx.fi/sdk-and-widget/go-sdk): Use WheelX in Go services and backend infrastructure. * **Connecting AI agents** — [MCP Server](https://docs.wheelx.fi/sdk-and-widget/mcp-server): Expose WheelX tools and resources through the Model Context Protocol. * **Embedding a complete user experience** — [Widget](/sdk-and-widget/widget): Add a configurable WheelX transaction interface to a web application. #### Available SDKs | SDK | Language | Best For | | ---------- | --------------- | -------------------------------------- | | Python | Python 3.9+ | Backend applications and data analysis | | JavaScript | TypeScript 4.5+ | Web applications and Node.js | | Go | Go 1.21+ | High-performance services | | MCP Server | Python | AI-agent integrations | #### Feature Comparison | Feature | Python | TypeScript | Go | MCP | | ---------------- | ------ | ---------- | -- | --- | | `getQuote` | ✅ | ✅ | ✅ | ✅ | | `getOrderStatus` | ✅ | ✅ | ✅ | ✅ | | `getChainInfo` | ✅ | ✅ | ✅ | ✅ | | `getOrders` | ✅ | ✅ | ✅ | ✅ | | AI Agent Ready | ❌ | ❌ | ❌ | ✅ | #### Widget Guides * [Quick Start](https://docs.wheelx.fi/sdk-and-widget/widget/quick-start): Install and configure the Widget. * [Customization](https://docs.wheelx.fi/sdk-and-widget/widget/customization): Configure networks, tokens, behavior, and visual styles. * [Referral Commission](https://docs.wheelx.fi/sdk-and-widget/widget/referral-commission): Add a referral code and track commission-eligible activity. # Python SDK Developers can use the **Python SDK** to build backend services and automation scripts that interact with the **Multichain Bridge + DEX AI Aggregator** platform. ### Install ``` pip install wheelx-sdk ``` With Web3 support for transaction execution: ``` pip install wheelx-sdk[web3] ``` ### Quick Start ``` from wheelx_sdk import WheelXSDK, QuoteRequest sdk = WheelXSDK() quote_request = QuoteRequest( from_chain=1, to_chain=1, from_token="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", # USDC to_token="0xdAC17F958D2ee523a2206206994597C13D831ec7", # USDT from_address="0x742d35Cc6634C0532925a3b8Dc9F6A7c5D3a7C6a", to_address="0x742d35Cc6634C0532925a3b8Dc9F6A7c5D3a7C6a", amount=1000000, slippage=50 ) quote = sdk.get_quote(quote_request) print(f"Quote received: {quote.amount_out}") print(f"Request ID: {quote.request_id}") ``` ### Transaction Execution ``` from wheelx_sdk import TransactionExecutor executor = TransactionExecutor("https://mainnet.infura.io/v3/YOUR_PROJECT_ID") transaction = executor.build_transaction(quote.tx, quote_request.from_address) tx_hash = executor.sign_and_send_transaction(transaction, "YOUR_PRIVATE_KEY") print(f"Transaction sent: {tx_hash}") receipt = executor.wait_for_transaction(tx_hash) print(f"Confirmed in block: {receipt.blockNumber}") ``` ### API Reference #### WheelXSDK | Method | Description | | ------------------------------ | --------------------------------- | | `WheelXSDK(base_url?)` | Create new SDK instance | | `get_quote(quote_request)` | Get a quote for token swap/bridge | | `get_order_status(request_id)` | Get order status by request ID | #### TransactionExecutor | Method | Description | | -------------------------------------------- | ---------------------------------- | | `build_transaction(tx_data, address)` | Build transaction dict for signing | | `sign_and_send_transaction(tx, private_key)` | Sign and send transaction | | `wait_for_transaction(tx_hash, timeout=300)` | Wait for confirmation | # JavaScript SDK Developers can use the **JavaScript SDK** to build decentralized applications (dApps) that interact with the **Multichain Bridge + DEX AI Aggregator** platform. ### Install npm ``` npm install @wheelx/sdk ethers ``` yarn ``` yarn add @wheelx/sdk ethers ``` pnpm ``` pnpm add @wheelx/sdk ethers ``` ### Quick Start ``` import { WheelXSDK, QuoteRequest } from '@wheelx/sdk'; const sdk = new WheelXSDK(); const quoteRequest: QuoteRequest = { from_chain: 1, to_chain: 1, from_token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC to_token: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT from_address: '0x742d35Cc6634C0532925a3b8Dc9F6A7c5D3a7C6a', to_address: '0x742d35Cc6634C0532925a3b8Dc9F6A7c5D3a7C6a', amount: 1000000, slippage: 50, }; const quote = await sdk.getQuote(quoteRequest); console.log(`Quote received: ${quote.amount_out} tokens`); console.log(`Request ID: ${quote.request_id}`); ``` ### Browser Usage (MetaMask) ``` import { WheelXSDK, TransactionExecutor } from '@wheelx/sdk'; import { ethers } from 'ethers'; if (typeof window.ethereum !== 'undefined') { const provider = new ethers.BrowserProvider(window.ethereum); await window.ethereum.request({ method: 'eth_requestAccounts' }); const signer = await provider.getSigner(); const sdk = new WheelXSDK(); const executor = new TransactionExecutor(provider, signer); const fromAddress = await signer.getAddress(); const quote = await sdk.getQuote({ ...quoteRequest, from_address: fromAddress }); const result = await executor.executeQuoteTransaction(quote.tx, fromAddress); console.log(`Transaction sent: ${result.hash}`); } ``` ### API Reference #### WheelXSDK | Method | Description | | --------------------------- | --------------------------------- | | `new WheelXSDK(config?)` | Create new SDK instance | | `getQuote(request)` | Get a quote for token swap/bridge | | `getOrderStatus(requestId)` | Get order status by request ID | #### TransactionExecutor | Method | Description | | --------------------------------------------- | --------------------------------- | | `buildTransaction(txData, fromAddr, config?)` | Build transaction from quote data | | `signAndSendTransaction(tx)` | Sign and send transaction | | `executeQuoteTransaction(txData, fromAddr)` | Build + sign + send in one call | | `waitForTransaction(txHash)` | Wait for confirmation | # Go SDK Developers can use the **Go SDK** to build backend services and microservices that interact with the **Multichain Bridge + DEX AI Aggregator** platform. ### Install ``` go get github.com/wheelx-fi/wheelx-sdk/go/wheelx ``` Requires [go-ethereum](https://github.com/ethereum/go-ethereum) for transaction execution: ``` go get github.com/ethereum/go-ethereum ``` ### Quick Start ``` package main import ( "context" "fmt" "log" "github.com/wheelx-fi/wheelx-sdk/go/wheelx" ) func main() { // Initialize SDK sdk := wheelx.NewWheelXSDK("") // Create quote request req := wheelx.QuoteRequest{ FromChain: 1, ToChain: 1, FromToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC ToToken: "0xdAC17F958D2ee523a2206206994597C13D831ec7", // USDT FromAddress: "0x742d35Cc6634C0532925a3b8Dc9F6A7c5D3a7C6a", ToAddress: "0x742d35Cc6634C0532925a3b8Dc9F6A7c5D3a7C6a", Amount: 1000000, // 1 USDC (6 decimals) Slippage: &[]int{50}[0], } // Get quote ctx := context.Background() quote, err := sdk.GetQuote(ctx, req) if err != nil { log.Fatalf("Failed to get quote: %v", err) } fmt.Printf("Quote received: %s tokens\n", quote.AmountOut) fmt.Printf("Request ID: %s\n", quote.RequestId) } ``` ### Transaction Execution ``` import ( "github.com/ethereum/go-ethereum/common" ) // Initialize executor executor, err := wheelx.NewTransactionExecutor("https://mainnet.infura.io/v3/YOUR_PROJECT_ID") if err != nil { log.Fatalf("Failed to create executor: %v", err) } // Build and send EIP-1559 transaction fromAddress := common.HexToAddress(req.FromAddress) tx, err := executor.BuildEIP1559Transaction(ctx, quote.Tx, fromAddress) if err != nil { log.Fatalf("Failed to build transaction: %v", err) } txHash, err := executor.SignAndSendTransaction(ctx, tx, "YOUR_PRIVATE_KEY") if err != nil { log.Fatalf("Failed to send transaction: %v", err) } fmt.Printf("Transaction sent: %s\n", txHash.Hex()) ``` ### API Reference #### WheelXSDK | Method | Description | | -------------------------------------------------------- | --------------------------------- | | `NewWheelXSDK(baseURL string)` | Create new SDK instance | | `GetQuote(ctx, req) (*QuoteResponse, error)` | Get a quote for token swap/bridge | | `GetOrderStatus(ctx, requestID) (*OrderResponse, error)` | Get order status by request ID | #### TransactionExecutor | Method | Description | | --------------------------------------------------- | --------------------------------- | | `NewTransactionExecutor(rpcURL string)` | Create executor with RPC endpoint | | `BuildTransaction(ctx, txData, fromAddress)` | Build legacy transaction | | `BuildEIP1559Transaction(ctx, txData, fromAddress)` | Build EIP-1559 transaction | | `SignAndSendTransaction(ctx, tx, privateKey)` | Sign and send transaction | | `WaitForTransaction(ctx, txHash)` | Wait for confirmation | # MCP Server The WheelX **MCP (Model Context Protocol) Server** allows AI assistants and LLM-powered applications to interact with the WheelX DeFi platform — getting quotes, tracking orders, estimating gas, and comparing swap routes — all through a standardized protocol. Built with [FastMCP](https://github.com/jlowin/fastmcp), it exposes 6 tools and 3 resources for AI agents. ### What You Can Do #### Tools | Tool | Description | | ------------------------ | ------------------------------------------------- | | `get_quote` | Get swap/bridge quotes with transaction payload | | `get_order_status` | Check the status of submitted orders | | `get_supported_chains` | List all supported blockchain networks | | `calculate_token_amount` | Convert human-readable amounts to raw token units | | `estimate_gas_cost` | Estimate gas costs for transactions | | `compare_quotes` | Compare quotes with different slippage settings | #### Resources | Resource URI | Description | | ----------------------------------- | -------------------------------------------- | | `wheelx://chains/{chain_id}/tokens` | Get popular tokens for a specific chain | | `wheelx://status` | Check WheelX service status and availability | | `wheelx://docs/usage` | Usage documentation | ### Supported Chains Ethereum (1), Optimism (10), BNB Smart Chain (56), Polygon (137), Arbitrum One (42161), Base (8453), Avalanche C-Chain (43114) ### Install & Run ``` # Clone the SDK repo git clone https://github.com/wheelx-fi/wheelx-sdk cd wheelx-sdk/python # Install dependencies pip install fastmcp requests # Run the server python mcp_server.py ``` ### Configuration Set via environment variables: | Variable | Default | Description | | ----------------- | ----------------------- | ------------------------------------ | | `WHEELX_BASE_URL` | `https://api.wheelx.fi` | API base URL (planned) | | `WHEELX_TIMEOUT` | `30` | Request timeout in seconds (planned) | > Environment variable support is planned for a future release. Currently the server uses built-in defaults: `https://api.wheelx.fi` with a 30-second timeout. ### Usage Example ``` # An AI agent calls the get_quote tool: quote = await get_quote( from_chain=1, to_chain=1, from_token="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", to_token="0xdAC17F958D2ee523a2206206994597C13D831ec7", from_address="0x742d35Cc6634C0532925a3b8Dc9F6A7c5D3a7C6a", to_address="0x742d35Cc6634C0532925a3b8Dc9F6A7c5D3a7C6a", amount=1000000, slippage=50 ) # Returns: request_id, amount_out, min_receive, transaction payload, etc. ``` # Widget WheelX Widget is an embeddable Bridge & Swap widget for Next.js applications. It gives you a ready-to-use trading entry with a small integration surface, while still letting you control supported networks, default tokens, theme, and referral setup. Typical use cases: * wallet and dashboard integrations * trading or prediction-market products * partner sites that need a branded Bridge & Swap entry ### 🖼️ Preview {% embed url="" %} ### 🔗 Explore {% embed url="" %} {% embed url="" %} # Quick Start An open-source, framework-agnostic React widget for cross-chain token swaps and bridges. Built-in wallet connection support (EVM + Solana), configurable theme system, and ready-to-use demo application. ### Features * 🔄 **Cross-chain Swap & Bridge** — Full trading flow with quote polling, gas estimation, approval handling * 👛 **Built-in Wallet Connection** — Dynamic SDK + Wagmi v2 supporting EVM (MetaMask, OKX, etc.) and Solana (Phantom) * 🎨 **Configurable Theme** — 14 color tokens for custom skinning * ⚛️ **Framework Agnostic** — Works with any React framework (Next.js, Vite, Create React App, etc.) * 📦 **Tree-shakeable** — ESM + CJS builds with TypeScript declarations * 🔌 **Configurable Default Tokens** — Set default from/to chains and tokens * 📱 **Deep Link Support** — Wallet app launch support in WebView (React Native) — see Deep Link Guide ### Installation ``` npm install @wheelx-widget/widget @chakra-ui/react @emotion/react ``` Note: `@chakra-ui/react` and `@emotion/react` are required peer dependencies. ### Quick Start ``` // main.tsx — wrap with ChakraProvider import { ChakraProvider, defaultSystem } from '@chakra-ui/react' import { createRoot } from 'react-dom/client' import App from './App' createRoot(document.getElementById('root')!).render( ) ``` ``` // App.tsx // Import the CSS for animations (required!) import '@wheelx-widget/widget/dist/index.css' import { WheelXProvider, WheelXWidget } from '@wheelx-widget/widget' function App() { return ( ) } ``` ### Configuration #### Theme Customization Customize 14 visual tokens: ``` ``` #### Default Chain/Token Configuration ``` ``` #### Custom Dynamic Environment ID ``` ``` #### API Base URL Override the default WheelX API endpoint. Useful for testing against a staging or development environment. ``` ``` #### Fixed Recipient Address (Different Address) Configure fixed recipient addresses for EVM or Solana chains. When set, the widget will: * **Display the configured address** in the To field instead of showing "Connect Wallet" * **Query the token balance** of the configured address * **Skip wallet connection** for the target chain (only the source chain wallet is required for signing) * **Show GetGas** when the configured address has insufficient native token balance This is useful for exchange or merchant scenarios where funds should always be sent to a specific address regardless of which wallet the user connects. **Priority order for recipient address:** 1. Configured fixed address (`evmDifferentAddress` / `solanaDifferentAddress`) 2. User manually entered different address (via Different Address dialog) 3. Connected wallet address ``` ``` **Note:** You can configure one, both, or neither. The widget will only use the relevant one based on the selected To chain. ### API Reference #### `` The root provider component that sets up wallet connections, React Query, and theme. #### `` The main trading widget component. #### `WidgetConfig` ``` interface WidgetConfig { theme?: Partial /** API base URL. Default 'https://api.wheelx.fi' */ apiBaseUrl?: string from?: { chains?: number[] defaultChainId?: number chainTokens?: Record defaultToken?: { chainId: number; address: string } } to?: { chains?: number[] defaultChainId?: number chainTokens?: Record defaultToken?: { chainId: number; address: string } } routerCallback?: { onPathnameChange?: (pathname: string) => void onRouteLeave?: () => void getCurrentPathname?: () => string } dynamicEnvironmentId?: string onDeepLink?: (url: string) => void // See Deep Link Guide for WebView environments /** Fixed recipient address for EVM chains (0x format). Takes priority over wallet address and manual different address */ evmDifferentAddress?: string /** Fixed recipient address for Solana chains (base58 format). Takes priority over wallet address and manual different address */ solanaDifferentAddress?: string } ``` #### `WidgetTheme` ``` interface WidgetTheme { defaultTextColor: string highlightTextColor: string weakTextColor: string defaultBgColor: string highlightBgColor: string assistBgColor: string defaultBorderColor: string highlightBorderColor: string highlightButtonBg: string highlightButtonText: string normalButtonBg: string normalButtonText: string disabledButtonBg: string disabledButtonText: string /** Color palette for the GetGas switch component. e.g. 'purple', 'blue', 'green'. Default: 'purple' */ getGasSwitchColorPalette?: string } ``` ### Demo A demo `https://widget.wheelx.fi` ### API Endpoint This widget connects to the WheelX API at `https://api.wheelx.fi`. The API domain is not configurable. ### React Native / WebView Integration If you embed the Widget into a React Native WebView, additional configuration is required to properly launch wallet apps. Please refer to: **Mobile Wallet Launch Guide (DEEP\_LINK\_GUIDE.md)** In short, three things are required: 1. Add `onMessage` listener in the WebView 2. Configure `` declaration in Android's `AndroidManifest.xml` 3. Configure `LSApplicationQueriesSchemes` in iOS's `Info.plist` ### License MIT # Customization WheelX Widget supports both functional configuration and visual customization. If you want the fastest workflow, start from the hosted theme page: Recommended workflow: 1. Open the theme page 2. Adjust colors and typography 3. Copy the generated config 4. Paste it into your host app 5. Add functional restrictions such as networks or tokens ## 🧩 Configuration Overview The main config type is: ``` import type { WheelxWidgetConfig } from '@wheelx/widget' ``` Example: ``` const widgetConfig: WheelxWidgetConfig = { mode: 'bridge-and-swap', referralCode: 'your-affiliate-code', networks: { from: [1, 8453], to: [8453, 137] }, defaultTokens: { from: { chainId: 8453, address: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', symbol: 'USDT' }, to: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', symbol: 'USDC' } }, allowedTokens: { from: [ { chainId: 8453, tokens: ['0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2'] } ] }, styles: { formContainer: { backgroundColor: '#0f172a' } } } ``` ## 🔀 `mode` Controls the widget flow. Supported values: * `bridge-and-swap` Enables swap, bridge, and cross-chain routing. * `swap` Restricts the widget to same-chain swap flows. Example: ``` const widgetConfig: WheelxWidgetConfig = { mode: 'swap' } ``` Use `swap` when: * your product only supports a single chain * you want a simpler UI * you do not want users switching into bridge routes ## 💸 `referralCode` Adds your affiliate code to widget quote requests. ``` const widgetConfig: WheelxWidgetConfig = { referralCode: 'your-affiliate-code' } ``` Good to know: * the value is trimmed before use * the widget does not need a separate UI change for referral tracking * the same config can be combined with theme and token restrictions You can get your code here: ## 🌐 `networks` Restricts which chains users can choose. ``` const widgetConfig: WheelxWidgetConfig = { networks: { from: [1, 8453], to: [8453, 137] } } ``` Supported forms: * `'all'` * a single chain ID * an array of chain IDs Examples: Allow only Base: ``` const widgetConfig: WheelxWidgetConfig = { networks: { from: 8453, to: 8453 } } ``` Allow bridge from Ethereum or Base into Base or Polygon: ``` const widgetConfig: WheelxWidgetConfig = { networks: { from: [1, 8453], to: [8453, 137] } } ``` Use this when: * your app only supports a known list of chains * you want to avoid irrelevant routes * you want a smaller, more guided selection flow ## 🪙 `defaultTokens` Sets the initial token selection shown in the widget. ``` const widgetConfig: WheelxWidgetConfig = { defaultTokens: { from: { chainId: 8453, address: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', symbol: 'USDT' }, to: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', symbol: 'USDC' } } } ``` Recommended usage: * prefill the most common trading pair * match the primary network of your product * reduce the number of clicks before the user gets a quote Notes: * `chainId` and `address` are the real identifiers * `symbol` is optional, but helpful for readability * if a default token is not valid under the current restrictions, the widget falls back to the nearest valid option ## 🔐 `allowedTokens` Restricts the selectable tokens on a per-chain basis. ``` const widgetConfig: WheelxWidgetConfig = { allowedTokens: { from: [ { chainId: 8453, tokens: [ '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' ] } ], to: [ { chainId: 8453, tokens: [ '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' ] } ] } } ``` This is especially useful when: * your product should only expose approved assets * you want to guide users into a narrow route set * you are embedding the widget for a single token onboarding path Behavior notes: * restrictions are chain-scoped * addresses are normalized internally * **chains not listed remain unrestricted** ## 🎛️ `styles` Use `styles` to override the widget appearance with slot-based style objects. ``` const widgetConfig: WheelxWidgetConfig = { styles: { formContainer: { backgroundColor: '#081121', borderColor: '#24324c' }, formTitleText: { color: '#f8fafc' }, primaryButton: { background: 'linear-gradient(135deg, #38bdf8 0%, #7c3aed 100%)' } } } ``` ### Style Areas The widget supports a broad set of visual slots. In practice, the most useful groups are: * Form shell `formContainer`, `formTitleText`, `formFooterText` * Token and input area `sectionContainer`, `tokenSelector`, `amountInputContainer`, `amountInputText` * Buttons `primaryButton`, `primaryButtonText`, `quickHalfButton`, `quickMaxButton` * Token modal `tokenModalContent`, `tokenModalSearchInput`, `tokenModalChainPanel`, `tokenModalTokenPanel` * Slippage controls `slippageSettingsTrigger`, `slippagePopoverContent`, `slippageAutoButton`, `slippageCustomInput` * Quote and transaction status `quoteInfoContainer`, `quoteInfoCard`, `txStateCard`, `txStatePrimaryButton` ### Example: Branded Dark Theme ``` const widgetConfig: WheelxWidgetConfig = { referralCode: 'your-affiliate-code', styles: { formContainer: { backgroundColor: '#0b1220', borderColor: '#1e293b' }, sectionContainer: { backgroundColor: '#111c30', borderColor: '#334155' }, formTitleText: { color: '#f8fafc' }, tokenPrimaryText: { color: '#e2e8f0' }, tokenSecondaryText: { color: '#94a3b8' }, primaryButton: { background: 'linear-gradient(135deg, #38bdf8 0%, #7c3aed 100%)' }, primaryButtonText: { color: '#ffffff' } } } ``` # Referral Commission Integrate affiliate tracking into your widget integration using a **referral code in the URL path**. ### 1. Get Your Referral Code Go to the WheelX Affiliate portal and create or copy your referral code: 👉 affiliate.wheelx.fi In the dashboard, look at the **Channel referral link** panel. The **Code** value is your referral code. ### 2. Pass It via URL Path Add your referral code as a `/v/{code}` segment in the widget URL: ``` https://wheelx.fi/v/YOUR_REFERRAL_CODE?from_chain=8453&to_chain=1 ``` #### Combined with Short Links ``` https://wheelx.fi/v/YOUR_REFERRAL_CODE/from/8453&USDC/to/1&USDT ``` ### 3. Full Example #### Direct Link ``` https://wheelx.fi/v/WHEELX_PARTNER?from_chain=8453&to_chain=42161&from_symbol=USDC&to_symbol=USDT ``` #### iframe Embed ``` ``` ### Notes * The referral code is extracted from the `/v/{code}` path segment * The widget does not need a separate UI change for referral tracking * Referral attribution applies to all quotes and completed trades from that session * Check your earnings in the Affiliate Dashboard PreviousCustomization # Overview Access official WheelX brand materials, support channels, and community links. Use this section when publishing WheelX content, requesting technical assistance, or connecting with the team. ### Find the Right Resource * **For media partners and content teams** — [Media Kit](/resources/media-kit): Download official WheelX logos, symbols, and brand assets. * **For developers and integration teams** — [Technical Support](/resources/technical-support): Find support channels for API, SDK, widget, and integration questions. * **For users and community members** — [Find Us](/resources/find-us): Access official WheelX websites, social channels, and community links. # Media Kit ## Logo & Avatar
## Horizontal Version
## Symbol
# Technical Support ## Technical Support If you encounter issues such as delayed bridging, swapping, wallet connection problems, or any other related concerns, we highly recommend you provide feedback by joining our Discord server. **Step1** Visit **Step2** Enter the "Verify" channel and click on ✅ to proceed with verification.
**Step3** Go to the "SUPPORT" area, select the "open-tickets" channel, and open a ticket to submit your issue. We will process it as soon as possible within 24 hours.
# Find Us **Contact Information**: For support, business inquiries, or community engagement, please visit our contact page, email us at ****, or reach out on our social media channels.[X](https://x.com/intent/follow?screen_name=WheelX_fi) [Discord](https://discord.gg/GaqW8QEVTF) [Telegram](https://t.me/WheelX_official) [Medium](https://medium.com/@wheelx.fi) [Github](https://github.com/wheelx-fi) [Youtube](https://www.youtube.com/@wheelxfi)