dexamine is a Python package built to turn Uniswap event data stored in Ethereum transaction receipts into records of trades and liquidity changes. The library covers Uniswap v2 and v3 swaps, mints, and burns on Ethereum mainnet, and it attaches token quantities, pool state, transaction position, and gas fields to every event.
Version 1.1.0 installs from a GitHub repository and serves researchers who build datasets for empirical research on decentralized exchange activity.
Uniswap v2 and v3 operate as automated market makers: each trade changes the balances of liquidity pools, and contract rules set the price. One Ethereum transaction can contain several trades, and a block timestamp does not reveal their execution order.
Block builders and validators order the transactions inside a block, and studies of arbitrage and transaction ordering use trade position, execution fees, and post-trade pool state, which turns Uniswap event data into an input for market microstructure work.
How dexamine Organizes Uniswap Event Data in Four Layers
The package builds Uniswap event data in four stages: JSON-RPC retrieval, contract metadata resolution, protocol parsing, and output construction. A reusable session caches pool and token metadata across calls. The client built on Requests downloads transactions, receipts, and blocks, while web3.py runs contract calls for token symbols, decimals, and address checksum conversion. Protocol parsers perform the event decoding in Python by reading event topics and fixed-width data fields.
A researcher supplies a transaction position, defined by block number and transaction index, plus a protocol name and an optional pool address. The session fetches the receipt, decodes each log, and returns Uniswap event data for the supported events. Live parsing needs an endpoint serving historical blocks, receipts, and contract metadata calls. Batched requests return results incrementally, which avoids holding every record in memory.
The install requires Python 3.10 or newer, web3.py 6.15.0 or newer, and Requests 2.31.0 or newer. Users who need parallel processing assign one session to each worker process, and the metadata cache grows with the number of distinct contracts encountered. Processing rates depend on endpoint latency and capacity, and the project makes no throughput claim.
Pool State Recovery for Uniswap v3 Swap Events and v2 Reserves
Each protocol version exposes pool state differently, and the parsers handle both while they build Uniswap event data. Uniswap v2 reports updated reserves in a Sync event logged before the swap, mint, or burn it accompanies.
dexamine accepts a v2 event only when the preceding log is a Sync from the same pool, and it skips the event otherwise. For swaps, the reserve ratio gives the marginal price after the event and before fees.
Uniswap v3 swap logs carry the price as sqrtPriceX96, the current tick, and the active liquidity, and the parser derives the price and the virtual reserves from the three values. Virtual reserves describe the local trading curve around the current price and differ from the token balances held by the pool, and the parser reports them as missing when active liquidity is zero.
Mints and burns record liquidity additions as positive quantities and removals as negative quantities, while swap quantities show the net token flow of the pool.
Receipt Position, Gas Fields and Flat Output Rows
The output layer delivers Uniswap event data in two formats: the original node payloads kept next to the parsed events, or one flat row per event. Flat rows contain block index, transaction index, transaction hash, and a field named receipt_log_index, which stores the zero-based position of the event in the receipt’s log list. The field differs from the block-wide logIndex returned by Ethereum nodes, and the pair of transaction identity and receipt position identifies each source event.
Token amounts pass through decimal scaling and floating-point arithmetic, which can introduce rounding error in normalized quantities, and users who need exact integers recover them from the retained logs. Gas consumption and fee fields describe the whole transaction and repeat across its events, without assigning execution cost to individual trades.
A destination label sorts each transaction into contract_creation, uniswap_router, or other_contract by top-level destination address, and the label does not establish trader identity, arbitrage, or maximal extractable value.
Four Swaps in One Transaction at Block 12,561,528
The repository ships a recorded example of Uniswap event data: transaction index 31 in Ethereum block 12,561,528, dated 3 June 2021, containing four Uniswap v3 swaps across three pools. The parser returns the swaps at receipt positions 3, 6, 10, and 13, and the gaps correspond to token transfers and other unsupported logs. The first and last swaps touch the same USDC/WETH pool, yet each remains a separate observation.
The recorded quantities show the sign convention at each receipt position, starting with position 3, where the USDC/WETH pool took in 5.000000 WETH and paid out 14,008.253925 USDC. At position 6, the DAI/USDC pool took in 14,008.253925 USDC and paid out 13,983.724002 DAI. Position 10 moved 4.999395 WETH out of the DAI/WETH pool against 13,983.724002 DAI in, and position 13 returned to the USDC/WETH pool with 4.999395 WETH in and 14,003.702900 USDC out.
Each swap also reports a post-event price, a tick, and the active liquidity of the pool. Prices read 2,802.77 USDC per WETH at position 3, 0.9987 DAI per USDC at position 6, 2,800.00 DAI per WETH at position 10, and 2,802.19 USDC per WETH at position 13.
The values are marginal prices after each swap, not ratios of exchanged amounts. The DAI/USDC virtual reserves, near 94 billion units, describe curve depth and do not represent assets held by the pool.
Reproducibility, Verification and Related Extraction Tools
Reproducibility of Uniswap event data depends on the software version, the source responses, and the resolved metadata. dexamine queries pool and token metadata at the latest block and caches it, and a change in token metadata can alter repeated runs.
The MetadataResolver.seed method accepts recorded metadata and overwrites cache entries, while missing entries still trigger endpoint queries. Users should keep transaction hashes next to positions, because chain reorganizations can replace the transaction at a recent position.
The recorded example runs offline without a node, and the repository stores the Ethereum responses, the historical metadata, and the expected output for a check of the Uniswap event data. A check option compares all four rows with a committed JSON file, and a separate script verifies each swap through ABI decoding and high-precision decimal arithmetic.
dexamine leaves transaction discovery, storage, and statistical estimation to other tools and focuses on protocol interpretation and joins to execution metadata. Ethereum ETL exports blockchain records, cryo extracts data into tabular formats, Graph Node serves subgraph queries, and TrueBlocks indexes transactions by address.
A researcher can select transactions with one of the tools and pass their positions to dexamine, which produces Uniswap event data without calling any of them. Version 1 supports data construction for a study of price discovery in decentralized markets, a task dependent on event order and pool information.
Isai Alexei is a journalist and financial analyst covering cryptocurrency markets and traditional securities for Blockchaindose. He has spent ten years analyzing digital assets, trading activity, and market structure.
