Command Line Interface (CLI)

uniswap-python ships with unipy, a powerful command-line interface. It is designed for developers and system administrators who want to query market prices, check token metadata, or integrate Uniswap data into bash scripts and CI/CD pipelines without writing full Python applications.

Global Setup & Usage

To use unipy, you need an RPC provider. The CLI automatically loads environment variables from a .env file in your current directory, or you can export it directly in your shell.

export PROVIDER="https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID"

The basic syntax is: 

unipy [OPTIONS] COMMAND [ARGS]...

Global Options:

  • -v, --verbose: Enable verbose logging to see Web3 debug output.
  • --version [1|2|3]: Specify which version of the Uniswap contracts to query. Defaults to 3 (or the UNISWAP_VERSION environment variable).

Commands

price

Returns the spot price of an asset. It calculates how many token_out you will receive for a given quantity of token_in.

unipy contains a built-in database of common shorthand token tickers (e.g., ETH, WETH, DAI, USDC). You can use these shorthands, or provide a full 0x... contract address.

Basic Quote: 

# Get the price of 1 WETH quoted in DAI
$ unipy price WETH DAI
3350.883387688622

# Get the price of 1 WETH quoted in USDT (using USDT's contract address)
$ unipy price WETH 0xdac17f958d2ee523a2206206994597c13d831ec7
3348.128969

Custom Quantity: By default, the CLI requests the price for exactly 1 full unit of the input token (automatically resolving decimals, e.g., 10**18 for ETH). Use --quantity to specify a custom amount in the token's smallest unit (Wei).

# Query the price for 0.5 WETH (500000000000000000 Wei)
$ unipy price WETH DAI --quantity 500000000000000000

Raw Output: By default, the CLI normalizes the output by the token_out decimals to provide a human-readable float. If you are feeding this output into another script or smart contract, use --raw to get the exact integer value.

$ unipy price --raw WETH DAI
3350883387688622003541

token

Retrieves and displays on-chain metadata for a given token contract. It queries the contract's name(), symbol(), and decimals() functions.

$ unipy token 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2
{'name': 'Wrapped Ether', 'symbol': 'WETH', 'decimals': 18}

tokendb

Lists the built-in shorthand tokens available in the CLI's internal database. This is useful to see which tokens you can query without looking up their contract addresses.

$ unipy tokendb
BaseToken(ETH, '0x0000000000000000000000000000000000000000')
BaseToken(WETH, '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2')
BaseToken(DAI, '0x6B175474E89094C44Da98b954EedeAC495271d0F')
...

Options:

  • --metadata: Actively queries the blockchain to fetch the full metadata (Name, Decimals) for every token in the database, verifying their integrity.
$ unipy tokendb --metadata
{'name': 'Wrapped Ether', 'symbol': 'WETH', 'decimals': 18}
{'name': 'Dai Stablecoin', 'symbol': 'DAI', 'decimals': 18}
...

Troubleshooting the CLI

  • Command returns ValueError: token was not an address...: The shorthand you used is not in the internal database. Pass the full 0x checksummed address instead.
  • Command hangs indefinitely: Your RPC provider might be rate-limiting you, or the connection is blocked. Try using -v to debug Web3 connection issues.