UniswapX Protocol: Architecture, Integration, and Order Execution

UniswapX is an innovative protocol designed to facilitate token swaps by leveraging third-party liquidity providers through a unique auction mechanism. This system resembles a traditional order book filled with user limit orders but distinguishes itself by processing orders via a Dutch auction, where the execution cost decreases over time.

As the complexity of asset swap routing increases, UniswapX provides a streamlined solution. It allows the task of building swap routes to be delegated to specialized third-party protocols. These protocols, which manage liquidity, compete to offer users the best possible execution prices. The entire process remains seamlessly integrated within the main Uniswap application interface, ensuring a consistent user experience.

The protocol operates with two primary participants:

• Swapper: The initiator of the swap who creates a signed order to exchange one asset for another.
• Filler: The entity that fulfills the order created by the swapper by providing the required asset.

In this context, the swapper acts as the maker, while the filler takes on the role of the taker.

How UniswapX Works

To execute a token swap, the swapper creates a specific type of order known as an "Exclusive Dutch Order." This order includes several key parameters:

• endAmount: The amount at the end of the auction, representing the minimum amount the swapper is willing to receive.
• startAmount: The amount at the beginning of the auction, representing the maximum amount the swapper can receive.
• timePeriod: The designated time window for order execution, during which the exchange rate decreases from the startAmount to the endAmount.

This structure initiates a Dutch auction for the user’s order, with the execution cost diminishing over time. Practically, this means that the longer an order remains unfulfilled, the less the swapper will receive, making it increasingly attractive for fillers to execute.

After creating the order, the swapper signs it using Permit2, granting approval for UniswapX contracts to transfer assets necessary for order execution. Information about the created order becomes available to any party willing to act as a filler.

The workflow can be broken down into three main steps:

1. The Swapper submits an order to UniswapX and grants approval via the Permit2 service.
2. The Filler receives the user's order and executes it on the UniswapX contracts, known as Reactors.
3. The Reactors contracts validate the order for executability and facilitate the physical asset exchange between the filler and swapper.

Integrating with UniswapX

Integration with the UniswapX protocol requires three core capabilities:

1. Retrieving a list of all available orders ready for execution.
2. Selecting orders that can be executed by a managed filler.
3. Executing the chosen orders.

At a high level, this process involves using UniswapX's API to retrieve orders, implementing a custom matching system to select them, and interacting with UniswapX smart contracts for execution.

API Access

UniswapX provides several API endpoints for retrieving order lists. These endpoints allow integrators to fetch open orders based on various criteria, such as chain ID and order status.

A sample API request to retrieve a Dutch auction order might look like this:

GET https://api.uniswap.org/v2/orders?orderStatus=open&chainId=1&limit=1

The response typically includes order details such as inputs, outputs, encoded order data, signatures, and status. The encodedOrder field requires decoding using the protocol's ABI specifications.

While polling the API is one method for order retrieval, it is not the most efficient. UniswapX also supports webhooks for real-time order notifications. Integrators can contact the UniswapX team to gain access to this more private and efficient notification system.

Matching System

The matching system is arguably the most critical component from a business perspective. It involves selecting which orders to execute based on factors like protocol goals, execution amounts, and market conditions. The algorithm for this system can vary widely depending on specific use cases and strategies, making it a customizable black box for each integrator.

Smart Contracts and Order Execution

The smart contract that fillers interact with is called a reactor. The Reactor.sol contract processes and validates user orders, determines input and output assets, and can make callbacks to the caller's address if necessary.

UniswapX offers several implementations of the Reactor.sol contract:

• LimitOrderReactor.sol: For executing simple limit orders.
• DutchOrderReactor.sol: For executing orders where the price decreases via a Dutch auction.
• ExclusiveDutchOrderReactor.sol: Extends Dutch auction functionality with an exclusiveFiller concept, allowing specific participants to join the auction.

All implementations share common code housed in the abstract BaseReactor.sol contract.

The IReactor interface defines the functions available for order execution:

• execute(SignedOrder calldata order): Executes a single order.
• executeWithCallback(SignedOrder calldata order, bytes calldata callbackData): Executes a single order with a callback.
• executeBatch(SignedOrder[] calldata orders): Executes multiple orders in a batch.
• executeBatchWithCallback(SignedOrder[] calldata orders, bytes calldata callbackData): Executes multiple orders with callbacks for each.

Order Execution Strategies

Fillers can choose between two primary strategies for order execution: Direct Filler and Fill Contracts.

Direct Filler Strategy

The Direct Filler strategy assumes the filler already holds sufficient assets to fulfill the swapper's order at the time of execution. The filler can call either execute() or executeWithCallback() directly on the Reactor.sol contract.

To use this strategy, the filler must first grant approval to the Reactor contract and ensure they have the required asset amount available.

Fill Contracts Strategy

The Fill Contracts strategy offers greater flexibility by allowing fillers to use an intermediary smart contract, often referred to as UniswapXExecutor.sol. This contract must implement the IReactorCallback interface.

The execution process under this strategy involves:

1. The filler calls the execute() function on their UniswapXExecutor.sol contract, which in turn calls executeWithFallback() on the Reactor.sol contract.
2. executeWithFallback() validates the order via the _prepare() function. If valid, it deducts tokens from the swapper and sends them to the filler's contract, then triggers a callback.
3. The callback allows the filler to perform custom token manipulations, such as swapping assets on another DEX to obtain the required token. The filler must then deposit the assets back to the contract.
4. The _fill() function transfers assets from the UniswapXExecutor.sol contract to the swapper. If insufficient tokens are available, the transaction reverts.

This entire process occurs within a single transaction, with the filler bearing the gas costs.

The Fill Contracts strategy enables various advanced use cases:

• Liquidity Aggregation: Managing multiple fillers through a single entry point, allowing collective liquidity provision.
• Asset Conversion: Converting held assets (e.g., ETH) into required assets (e.g., USDT) during order execution via integrated DEX swaps.

UniswapX provides a basic implementation of an executor contract, which can be customized to suit specific needs.

Benefits of Using UniswapX

1. Improved Swap Rates: Fillers benefit from the auction mechanism, which decreases execution costs over time, potentially leading to better rates.
2. Gasless Swaps: Swappers only need to sign orders; fillers cover all gas costs. This eliminates the need for swappers to hold the network's native token.
3. MEV Protection: Users are guaranteed specified amounts under predefined conditions, reducing exposure to MEV attacks. Fillers are encouraged to use private nodes for additional protection.
4. Cross-Chain Potential: UniswapX is designed with cross-chain swaps in mind, with ongoing developments aimed at expanding its capabilities across networks like Arbitrum.

👉 Explore more strategies for efficient token swapping and liquidity management.

Frequently Asked Questions

What is the main advantage of UniswapX over traditional swapping?
UniswapX delegates swap routing to third-party liquidity providers who compete via Dutch auctions. This often results in better prices for users and allows swappers to avoid gas fees since fillers cover transaction costs.

How do fillers make a profit in the UniswapX system?
Fillers profit by executing orders when the auction price is favorable. They provide the required asset to the swapper and typically obtain it at a better rate through their own liquidity sources or aggregated routes.

Is UniswapX available on all Ethereum Virtual Machine (EVM) chains?
While initially launched on Ethereum, UniswapX is expanding to other EVM-compatible chains. A pilot version for Arbitrum has been announced, with cross-chain functionality being a key focus for future development.

What are the risks for swappers using UniswapX?
Swappers risk receiving less than the maximum potential amount if their order fills later in the auction. However, they are protected by setting a minimum acceptable amount (endAmount) and benefit from gasless transactions.

Can anyone become a filler on UniswapX?
Yes, any entity with the technical capability to integrate with the API, run a matching system, and interact with the smart contracts can participate as a filler. This openness encourages competition and liquidity.

How does UniswapX handle protocol fees?
Like other Uniswap versions, UniswapX includes a protocol fee switch. However, this can only be activated through Uniswap Governance, ensuring decentralized control over fee structures.

Conclusion

UniswapX introduces an elegant solution for delegating swap routing to competitive third-party fillers. Its Dutch auction mechanism, gasless swaps for users, and flexibility in execution strategies make it a powerful addition to the decentralized exchange landscape. The protocol's potential for cross-chain expansion and its ability to attract diverse fillers will be crucial to its long-term success and adoption.

For those looking to integrate, the combination of API access, customizable matching systems, and well-documented smart contracts provides a solid foundation. Whether using the Direct Filler or Fill Contracts strategy, participants can leverage UniswapX to optimize their trading and liquidity provision activities.