Uniswap Universal Router Decoder

Uniswap Universal Router Decoder & Encoder

Many thanks to everyone who has ☕️ offered some coffees! ☕️

or ⭐ starred this project! ⭐

It is greatly appreciated! :)

Project Information

Code Quality

Release Notes

See the release notes page

v4.0.0 - breaking changes

• Update COMMAND_TYPE_MASK to 0x7f to match UR
• Add support for the PAY_PORTION_FULL_PRECISION command (0x07)
• Add support for the BALANCE_CHECK_ERC20 command (0x0e)
• Add support for the V3_POSITION_MANAGER_PERMIT command (0x11)
• Add support for the V3_POSITION_MANAGER_CALL command (0x12)
• Add support for the EXECUTE_SUB_PLAN command (0x21)
• Add revert_on_fail to the encoder methods for the commands whose failure the UR can tolerate
• Capture the bytes some callers append after the UR arguments as trailing_data, and re-append them when rebuilding the calldata, so a decoded call can be rebuilt byte-for-byte
• Make the chained function builders public and expose the encoder & decoder modules
• Reduce CI time
• Add a publish.yml GitHub Actions workflow that automatically publishes the package to PyPI and the MCP Registry with OIDC Trusted Publishing
• Agent-friendly changes:
• Add Encoder.function_input() / AsyncEncoder.function_input() to rebuild the calldata from a decoded call
• Add decoded_input_to_dict() and transaction_to_dict() to render the decoder output as JSON-friendly dicts
• Add the ur-decode and ur-encode command line tools, including ur-encode v3-path and its encode_v3_path MCP counterpart
• Add the ur-mcp MCP server (optional mcp extra) so AI agents can drive the codec, including encode_calldata to rebuild the calldata from a decoded call
• Annotate the MCP tools as read-only so a host can auto-approve them, and give them human-readable titles
• The command descriptions (ur-encode list / describe and the list_commands / describe_command MCP tools) now describe the decoded call format and its ABI parameters, instead of the encoder methods
• Add the MCP Registry metadata (server.json) to make the ur-mcp server discoverable
• Add AGENTS.md and llms.txt for AI agents, plus a mcp PyPI keyword
• Add tests/test_version_consistency.py to keep the packaging version, server.json and the README mcp-name: marker in sync

Overview and Points of Attention

The object of this library is to decode & encode transactions sent to the Uniswap Universal Router (UR) on Ethereum Mainnet, though it would work on any compatible chain where the UR is deployed. See Version Mapping below. This Python SDK is based on, and intended to be used with web3.py

The target audience is Python developers who are familiar with the Ethereum blockchain concepts and web3.py, and how DEXes work. The same codec is also available without Python, through the ur-decode / ur-encode command line tools and the optional ur-mcp MCP server (see "Command line interface" and "MCP server" below): both print JSON, so shell scripts and AI agents can drive it too.

⚠ Before using this library, ensure you are familiar with general blockchain concepts. The Python API also expects web3.py knowledge in particular.

⚠ Not all UR functions supported by this SDK are available through the CLI or MCP tools: run ur-encode list and look for the "rebuildable" flag.

List of supported Uniswap Universal Router Functions

All the ✅ commands can be decoded and encoded. V4_SWAP, V4_POSITION_MANAGER_CALL and EXECUTE_SUB_PLAN can also be decoded, but they cannot be rebuilt from a decoded call (see "How to rebuild the calldata from a decoded call").

Version Mapping

Here is the mapping between the Universal Router versions and the SDK ones

Installation

A good practice is to use Python virtual environments, here is a tutorial.

The library can be pip installed from pypi.org as usual:

# update pip to latest version if needed

pip install -U pip

install the decoder from pypi.org

pip install uniswap-universal-router-decoder

To install it from source:

pip install .

or for contributors:

pip install -e '.[mc