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
Demo Guide
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 confirmationcompleted— Funds successfully delivered to destinationfailed— Deposit failed, refund initiatedrefunded— 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
GET /v1/order/{request_id}
Get Order
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.
GET /v1/chain-info
Chain Info
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
Ethereum
ETH
0x0000000000000000000000000000000000000000
Ethereum
USDC
0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
Ethereum
USDT
0xdac17f958d2ee523a2206206994597c13d831ec7
Base
ETH
0x0000000000000000000000000000000000000000
Base
USDC
0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
BNB Chain
BNB
0x0000000000000000000000000000000000000000
BNB Chain
USDT
0x55d398326f99059ff775485246999027b3197955
Solana
USDC
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Solana
USDT
Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB
Tron
USDT
TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
Last updated
Was this helpful?