# Bitquery Docs — full text: Ethereum > 69 pages. All parts and the curated entry points: https://docs.bitquery.io/llms.txt ## Analyze a Token ICO with the Transfers API: Mint, Distributor, Investors URL: https://docs.bitquery.io/docs/blockchain/Ethereum/transfers/ico-token-ownership-transfer/ Rebuild a token sale from Ethereum transfers with Bitquery GraphQL: find the mint, the distributor contract and every buyer, then count them. # Analyze a Token ICO with the Transfers API: Mint, Distributor, Investors A token sale leaves a clean trail in transfer data. The token is minted to a distributor contract, the contract sends tokens to each buyer as the sale's conditions are met, and the set of receivers is the investor list. Three `Transfers` queries on the `combined` dataset rebuild that trail for any ERC-20 sale: the mint from the zero address tells you where the supply went, transfers from that address list the buyers, and `count` with `uniq` size the sale. The worked example is the PEPU token, `0x906cc2ad139eb6637e28605f908903c8adce566a`, whose sale ran in 2024; put another token contract in its place for a current one. Every query runs in the [IDE](https://ide.bitquery.io). Queries on the `archive` or `combined` dataset need an archive add-on; the free trial is real-time only. ## Step 1: find where the supply was minted A mint is a transfer from the zero address. The `Receiver` of the mint is the contract that distributes the sale. Saved query [here](https://ide.bitquery.io/Get-Minted-Address-of-the-ICO-Token). ```graphql query MyQuery { EVM(network: eth, dataset: combined) { Transfers( where: {Transfer: {Currency: {SmartContract: {is: "0x906cc2ad139eb6637e28605f908903c8adce566a"}}, Success: true, Sender: {is: "0x0000000000000000000000000000000000000000"}}} ) { Transfer { Amount Currency { Name Symbol SmartContract } Receiver Sender } } } } ``` For PEPU the mint went to `0xf0163c18f8d3fc8d5b4ca15e07d0f9f75460335f`, the distributor used in the next two queries. ## Step 2: list the buyers Every transfer sent by the distributor is a delivery to a buyer. The `Receiver` column is the investor list, with the amount each one received. Saved query [here](https://ide.bitquery.io/Get-all-Holders-Address-of-the-ICO-Token_1). ```graphql query MyQuery { EVM(network: eth, dataset: combined) { Transfers( where: {Transfer: {Currency: {SmartContract: {is: "0x906cc2ad139eb6637e28605f908903c8adce566a"}}, Success: true, Sender: {is: "0xf0163c18f8d3fc8d5b4ca15e07d0f9f75460335f"}}} ) { Transfer { Amount Currency { Name Symbol SmartContract } Receiver Sender } count } } } ``` ## Step 3: size the sale The same filter with `count` and `uniq` gives the number of deliveries and the number of distinct buyers in one row. Saved query [here](https://ide.bitquery.io/Number-of-Purchasers-in-ICO#). ```graphql query MyQuery { EVM(network: eth, dataset: combined) { Transfers( where: {Transfer: {Amount: {gt: "0"}, Currency: {SmartContract: {is: "0x906cc2ad139eb6637e28605f908903c8adce566a"}}, Sender: {is: "0xf0163c18f8d3fc8d5b4ca15e07d0f9f75460335f"}}} ) { count buyers: uniq(of: Transfer_Receiver) Transfer { Currency { Name Symbol SmartContract } } } } } ``` ## Where to go from here - Did buyers hold or sell? Run the [Balances and Holders cubes](/docs/cubes/balances-cube) on the buyer list, or filter `DEXTrades` on the token to see the first sells. - What did the sale raise? The ETH or stablecoin transfers into the distributor, or the `Calls` into it with `Value`, give the other side of each purchase. - Watching a live sale: change `query` to `subscription`, drop the dataset argument, and keep the distributor as `Sender` to see each delivery as it happens. ## Video tutorial on analyzing the PEPU sale ## Related pages - [Ethereum transfers API](/docs/blockchain/Ethereum/transfers/erc20-token-transfer-api) - [Balances and Holders cubes](/docs/cubes/balances-cube) - [Transfers cube](/docs/cubes/transfers-cube) - [Ethereum API hub](/docs/blockchain/Ethereum/) --- ## Balances API Documentation URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/ Balances API Documentation: fetch current and historical Ethereum balances with Bitquery GraphQL balance queries. Great for bots, dashboards, and alerts. # Balances API Documentation This section covers how to fetch balance-related data on Ethereum via **Bitquery GraphQL APIs** and **Streams**. To get started, [signup](https://account.bitquery.io/user/account) with Bitquery and get your [Access Token](https://account.bitquery.io/user/api_v2/access_tokens) by following [these](/docs/authorization/how-to-generate/) steps. If you need help getting balance data, reach out to [support](https://t.me/Bloxy_info). ## Modes Supported - GraphQL API - GraphQL Stream - Kafka Stream ## Primary APIs | API | Documentation | Description | |-----|---------------|-------------| | **Balances** | [Address Balance API](/docs/blockchain/Ethereum/balances/balance-api/) | Current and historical token balances for wallet addresses (`EVM.Balances`). | | **Holders** | [Token Holders API](/docs/blockchain/Ethereum/token-holders/token-holder-api) | Top holders, holder counts, and holder activity (`EVM.Holders`). | | **TransactionBalances** | [Transaction Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/) | Per-transaction balance updates with supply, market cap, reason codes, and streams (`EVM.TransactionBalances`). | ## What is the Balance API? On Ethereum, use the **Balances** cube for address-level balances and the **Holders** cube for token holder lists and counts. Both support `dataset: combined` (realtime + archive) and `dataset: archive` (historical and inactive addresses). See the [Address Balance API](/docs/blockchain/Ethereum/balances/balance-api/), [Token Holders API](/docs/blockchain/Ethereum/token-holders/token-holder-api), and [Transaction Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/) for queries and IDE examples. The [Transaction Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/) section also covers validator, miner, MEV, gas, NFT, and self-destruct balance tracking. ## When to Use Which API or Stream? | Use Case | API/Stream | Description | |----------|------------|-------------| | **Latest wallet balances** | [Balances API](/docs/blockchain/Ethereum/balances/balance-api/#balance-of-an-address) | Token balances for an address (`dataset: combined`; use `Amount(selectWhere: { gt: "0" })` for non-zero). | | **Balance on a date** | [Balances API](/docs/blockchain/Ethereum/balances/balance-api/#balance-on-a-specific-date) | Point-in-time snapshot with `Block.Date.till` (`dataset: archive`). | | **Wallet balance for one token on a date** | [Balances API](/docs/blockchain/Ethereum/balances/balance-api/#wallet-balance-for-a-specific-token-on-a-date) | `Block.Date`, `limit: 1`, `orderBy: Block_Date`. | | **Balance history over time** | [Balances API](/docs/blockchain/Ethereum/balances/balance-api/#balance-history-by-date) | Snapshots ordered by `Block_Date`. | | **Top token holders** | [Holders API](/docs/blockchain/Ethereum/token-holders/token-holder-api#top-holders-of-a-currency-current) | `orderBy: Balance_Amount`, `limit`. | | **Token holder count** | [Holders API](/docs/blockchain/Ethereum/token-holders/token-holder-api#token-holder-count-for-an-erc-20-token) | `uniq(of: Holder_Address)` with `dataset: combined`. | | **Holders above a threshold** | [Holders API](/docs/blockchain/Ethereum/token-holders/token-holder-api#holder-count-with-balance-above-a-threshold) | `uniq` with `if: { Balance: { Amount: { gt: "..." } } } }`. | | **Token balance with supply and market cap** | [Transaction Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/) | `EVM.TransactionBalances` — post balance, supply, USD value per transaction. | | **Real-time balance change streams** | [Transaction Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/) | Subscribe to balance updates with reason codes. | | **Validator / miner / MEV balance tracking** | [Transaction Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/) | Specialized trackers for rewards and MEV. | --- ## BullX-style Trading Terminal Data on Ethereum: Pair Feeds, Prices, Traders URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/evm-bullx-api/ BullX-style terminal data on Ethereum via Bitquery GraphQL: live pair trades, token price and stats, top traders, a wallet's trades, whale swaps and new pools. # BullX-style Trading Terminal Data on Ethereum: Pair Feeds, Prices, Traders A trading terminal like BullX is built from a few feeds: the trades of the pair on screen, the token's price and stats, who the biggest traders are, what one wallet has been doing, and the large swaps hitting the chain. Each is one Bitquery query or subscription on Ethereum, and the same filters work on BSC, Base, Arbitrum and the other EVM chains by changing the network. The worked token is Mog, `0xaaee1a9723aadb7afa2810263653a34ba2c21c7a`, in its Uniswap v2 pool with WETH, `0xc2eab7d33d3cb97692ecb231a5d0e4a649cb539d`. Every example runs in the [IDE](https://ide.bitquery.io) on a free account. For pool-page analytics such as trending pools, candles and reserves, see the [GeckoTerminal-style page](/docs/blockchain/Ethereum/dextrades/evm-geckoterminal-api/); for token discovery, the [GMGN-style page](/docs/blockchain/Ethereum/dextrades/evm-gmgn-api/). ## Recommended: Trading API queries (real-time + last ~30 days) ### Live trades with USD price, market cap and supply Streams MEV-filtered trades across all 10 chains; the network filter scopes it to Ethereum. Run it [in the IDE](https://ide.bitquery.io/Trading-API-Live-Trades-All-Chains). ```graphql subscription { Trading { Trades(where: { Pair: { Market: { Network: { is: "Ethereum" } } } }) { Block { Time } Price PriceInUsd Amounts { Base Quote } AmountsInUsd { Base Quote } Trader { Address } Pair { Token { Symbol Network } QuoteToken { Symbol } Market { Protocol Network } } } } } ``` ### Most accurate token price with 1-minute OHLC (top market) Returns the token's price from its top-volume market via `Ranking: { Position: { eq: 1 } }`; swap the token address and network for your token. Run it [in the IDE](https://ide.bitquery.io/Trading-API-Token-Price-Top-Market-Rank-1). ```graphql { Trading { Pairs( where: { Token: {Address: {is: "0xaaee1a9723aadb7afa2810263653a34ba2c21c7a"}, Network: {is: "Ethereum"}} Ranking: {Position: {eq: 1}} Interval: {Time: {Duration: {eq: 60}}} Price: {IsQuotedInUsd: true} } limit: {count: 1} orderBy: {descending: Block_Time} ) { Token { Symbol Address } QuoteToken { Symbol } Market { Protocol Address Network } Price { IsQuotedInUsd Ohlc { Open High Low Close } Average { Mean } } Volume { Base Usd } Block { Time } } } } ``` ## Live trades of a pair Filter the pool under `Trade.Dex.SmartContract` and the token under `Trade.Currency`. Each message is one swap with the amount, the USD price, the side and the wallet that sent it. Saved stream [here](https://ide.bitquery.io/Get-pair-trades-data-just-like-dexcsreener). ```graphql subscription { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { Dex: { SmartContract: { is: "0xc2eab7d33d3cb97692ecb231a5d0e4a649cb539d" } } Currency: { SmartContract: { is: "0xaaee1a9723aadb7afa2810263653a34ba2c21c7a" } } } } ) { Block { Time } Trade { Amount PriceInUSD Currency { Symbol } Side { Amount AmountInUSD Type Currency { Symbol } } Dex { ProtocolName } } Transaction { Maker: From Hash } } } } ``` ## Price and stats of a token The header block of a token page in one query: the price at the start and end of the window, trades, buys, sells, makers and USD volume, over the last day with a one-hour sub-window. `Side.Type` names the counter-side of a trade, so the token was bought where the side was sold. Saved query [here](https://ide.bitquery.io/Buys-Sells-BuyVolume-SellVolume-Makers-TotalTradedVolume-PriceinUSD-for-a-eth-pair). ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { Dex: { SmartContract: { is: "0xc2eab7d33d3cb97692ecb231a5d0e4a649cb539d" } } Currency: { SmartContract: { is: "0xaaee1a9723aadb7afa2810263653a34ba2c21c7a" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Trade { Currency { Symbol } Side { Currency { Symbol } } start: PriceInUSD(minimum: Block_Number) end: PriceInUSD(maximum: Block_Number) } trades: count trades1h: count(if: { Block: { Time: { after_relative: { hours_ago: 1 } } } }) buys: count(if: { Trade: { Side: { Type: { is: sell } } } }) sells: count(if: { Trade: { Side: { Type: { is: buy } } } }) makers: uniq(of: Transaction_From) volumeUsd: sum(of: Trade_Side_AmountInUSD) volumeUsd1h: sum(of: Trade_Side_AmountInUSD, if: { Block: { Time: { after_relative: { hours_ago: 1 } } } }) buyVolumeUsd: sum(of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: sell } } } }) sellVolumeUsd: sum(of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: buy } } } }) } } } ``` ## Top traders of a token Rank by `Transaction.From`, the wallet that sent the swap, so routers and aggregators do not appear as traders. Saved query [here](https://ide.bitquery.io/top-traders-of-a-token_7). ```graphql { EVM(network: eth) { DEXTradeByTokens( orderBy: { descendingByField: "volumeUsd" } limit: { count: 50 } where: { Trade: { Currency: { SmartContract: { is: "0xaaee1a9723aadb7afa2810263653a34ba2c21c7a" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Transaction { From } trades: count volumeUsd: sum(of: Trade_Side_AmountInUSD) bought: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: sell } } } }) sold: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: buy } } } }) } } } ``` ## One wallet's trades The Trading cube keys trades by wallet across chains, with USD on every row. The example is an Ethereum wallet with large trades at the time of writing; take any address from the top traders above. As a subscription without the `Block` filter the same `where` follows the wallet live. ```graphql { Trading { Trades( where: { Trader: { Address: { is: "0xae2fc483527b8ef99eb5d9b44875f005ba1fae13" } } Pair: { Market: { Network: { is: "Ethereum" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } orderBy: { descending: Block_Time } limit: { count: 50 } ) { Block { Time } Side PriceInUsd AmountsInUsd { Base Quote } Pair { Token { Symbol } QuoteToken { Symbol } Market { Protocol Address } } } } } ``` ## Whale swaps on Ethereum Swaps over a hundred thousand dollars in the last hour, newest first. Drop the `Block` filter and subscribe for alerts. ```graphql { Trading { Trades( where: { AmountsInUsd: { Base: { gt: 100000 } } Pair: { Market: { Network: { is: "Ethereum" } } } Block: { Time: { since_relative: { hours_ago: 1 } } } } orderBy: { descending: Block_Time } limit: { count: 50 } ) { Block { Time } Side Trader { Address } AmountsInUsd { Base } Pair { Token { Symbol } QuoteToken { Symbol } Market { Protocol } } } } } ``` ## New Uniswap v3 pools The factory's `PoolCreated` event names both tokens, the fee tier and the new pool address. New pools on Ethereum arrive minutes to hours apart, so query the last day rather than waiting on a stream. Saved query [here](https://ide.bitquery.io/Latest-pools-created-Uniswap-v3_9). ```graphql { EVM(network: eth) { Events( where: { Log: { SmartContract: { is: "0x1f98431c8ad98523631ae4a59f267346ea31f984" } Signature: { Name: { is: "PoolCreated" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } limit: { count: 50 } orderBy: { descending: Block_Time } ) { Block { Time } Transaction { Hash } Arguments { Name Value { ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } } } } } } ``` ## Related pages - [GeckoTerminal-style EVM API](/docs/blockchain/Ethereum/dextrades/evm-geckoterminal-api/) - [GMGN-style EVM API](/docs/blockchain/Ethereum/dextrades/evm-gmgn-api/) - [Traders API](/docs/trading/crypto-trades-api/traders-api) - [Ethereum DEX trades API](/docs/blockchain/Ethereum/dextrades/dex-api) --- ## Crypto Coin Ticker API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/crypto-coin-ticker/ Crypto Coin Ticker API: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. Scale further with Kafka or gRPC streams. # Crypto Coin Ticker API You can build your crypto coin ticker using our [DEX APIs](https://bitquery.io/products/dex) based on the requirements of the data field. For pre-aggregated price data with OHLC, consider using our [Crypto Price API](/docs/trading/crypto-price-api/). For **per-swap ticks**, see the **[Crypto Trades API](/docs/trading/crypto-trades-api/trades-api)**. ## Using Crypto price API For a **live ticker**, use the **[Crypto Price API](/docs/trading/crypto-price-api/)** stream. [Open the 1-second price stream in the IDE](https://ide.bitquery.io/1-second-crypto-price-stream). > Note: A `Volume: {Usd: {gt: 5}}` filter is applied to remove extreme outliers; the price stream already pre-filters outliers—this is an additional check. ```graphql subscription { Trading { Tokens( where: { Interval: { Time: { Duration: { eq: 1 } } } Volume: { Usd: { gt: 5 } } } ) { Token { Address Id IsNative Name Network Symbol TokenId } Block { Date Time Timestamp } Interval { Time { Start Duration End } } Volume { Base Quote Usd } Supply { MarketCap FullyDilutedValuationUsd CirculatingSupply TotalSupply MaxSupply } Price { IsQuotedInUsd Ohlc { Close High Low Open } Average { ExponentialMoving Mean SimpleMoving WeightedSimpleMoving } } } } } ``` ## OHLC ticker from DEXTradeByTokens Open this API on our [GraphQL IDE](https://ide.bitquery.io/Coin-ticker-api_4). ```graphql { EVM(dataset: realtime) { DEXTradeByTokens( orderBy: {descendingByField: "Block_Timefield"} where: {Trade: {Side: {Currency: {SmartContract: {is: "0xdac17f958d2ee523a2206206994597c13d831ec7"}}}, Currency: {SmartContract: {is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"}}, PriceAsymmetry: {lt: 0.1}}} ) { Block { Timefield: Time(interval: {in: minutes, count: 10}) lastTradeTime: Time(maximum: Block_Time) FirstTradeTime: Time(minimum: Block_Time) LastTradeBlock: Number(maximum: Block_Number) FirstTradeBlock: Number(minimum: Block_Number) } volume: sum(of: Trade_Amount) Trade { Currency { Name Symbol } Side { Currency { Name Symbol } } high: Price(maximum: Trade_Price) low: Price(minimum: Trade_Price) open: Price(minimum: Block_Number) close: Price(maximum: Block_Number) } count } } } ``` We are getting OHLC (Open High Low Close) data, with the last trade details on 10-minute intervals. You can change this interval like the following. - Time(interval: \{in: minutes, count: 5\}) - Time(interval: \{in: seconds, count: 10\}) - Time(interval: \{in: hours, count: 3\}) - Time(interval: \{in: days, count: 14\}) - Time(interval: \{in: weeks, count: 3\}) - Time(interval: \{in: months, count: 1\}) - Time(interval: \{in: years, count: 2\}) You can also add additional information if you want; there are many more fields available. --- ## ERC20 Token Transfers API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/transfers/erc20-token-transfer-api/ Query and stream Ethereum ERC-20 and native transfers: filter by contract or address, aggregate volume, rank top transfers and backfill deterministically. # ERC20 Token Transfers API Track and analyze ERC20 token transfers across the Ethereum blockchain in real-time and historically. Monitor token movements, analyze transfer volumes, track wallet activity, and build comprehensive token transfer analytics using Bitquery's ERC20 Token Transfers API. ## What are ERC20 Token Transfers? ERC20 is the most widely adopted token standard on Ethereum, enabling fungible tokens that can be transferred between addresses. ERC20 token transfers represent the movement of tokens from one wallet to another, forming the foundation of DeFi, trading, and token-based applications. Understanding ERC20 transfers is essential for: - **Portfolio Tracking**: Monitor token movements in and out of wallets - **Tax & Accounting**: Generate comprehensive transfer reports for crypto tax calculations, cost basis tracking, and token accounting reconciliation - **Compliance & Auditing**: Track token flows for regulatory requirements - **DeFi Analytics**: Analyze liquidity movements and protocol interactions - **Token Analytics**: Understand token distribution and holder behavior - **Security Monitoring**: Detect suspicious transfers and wallet activity ## 🔗 Related APIs ### Ethereum APIs - **[Ethereum Balance API](/docs/blockchain/Ethereum/balances/balance-api)** - Get wallet balances for ERC20, ERC721, and ERC1155 tokens - **[Ethereum Transaction Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/)** - Track real-time balance changes with reason codes - **[Ethereum Token Holders API](/docs/blockchain/Ethereum/token-holders/token-holder-api)** - Get top token holders and distribution data - **[Ethereum Token Supply API](/docs/blockchain/Ethereum/token-supply/evm-token-supply)** - Track total supply and supply changes - **[Ethereum DEX Trades API](/docs/blockchain/Ethereum/dextrades/dex-api)** - Monitor DEX trading activity - **[Ethereum Transactions API](/docs/blockchain/Ethereum/transactions/transaction-api)** - Get comprehensive transaction data - **[Ethereum Events API](/docs/blockchain/Ethereum/events/events-api)** - Query smart contract events ### EVM APIs - **[EVM Transfers API](/docs/schema/evm/transfers)** - General EVM token transfers documentation - **[EVM Balance Updates API](/docs/schema/evm/balances)** - Track balance changes across EVM chains - **[EVM DEX Trades API](/docs/schema/evm/dextrades)** - DEX trading data across EVM chains ### NFT & Other Token Standards - **[NFT Transfer API](/docs/blockchain/Ethereum/transfers/nft-token-transfer-api)** - Track ERC721 and ERC1155 NFT transfers - **[RWA Token API](/docs/blockchain/Ethereum/transfers/rwa-api)** - Real World Asset token transfers ### Solana APIs - **[Solana Transfers API](/docs/blockchain/Solana/solana-transfers/)** - Track SPL token transfers and SOL transfers on Solana - **[Solana Balance Updates API](/docs/blockchain/Solana/solana-balance-updates/)** - Monitor Solana wallet balance changes - **[Solana DEX Trades API](/docs/blockchain/Solana/solana-dextrades/)** - Track Solana DEX trading activity --- ## 📋 Table of Contents - **How do I get token transfers for a specific contract?** - Filter by ERC-20 address - **How do I get all inbound and outbound transfers for an address?** - Sender or receiver OR filter - **Get Latest ERC20 Token Transfers** - Query recent token transfers - **Subscribe to Real-Time Transfers** - WebSocket subscriptions for live data - **Filter by Sender or Receiver** - Query transfers involving specific addresses - **Transfer Volume Analysis** - Calculate sent and received volumes - **Top Transfers** - Get largest token transfers - **Earliest Transfer Tracking** - Find first transfers to addresses - **Use Cases** - Common applications and examples - **API Response Fields** - Complete field reference --- ## How do I get token transfers for a specific contract? Query `EVM.Transfers` with `where.Transfer.Currency.SmartContract` equal to the ERC-20 contract address, plus `dataset` and `network` (`eth` or another EVM chain). Order by `Block_Time` and use `limit` for pagination. The same filter works for historical windows using `Block.Time` or related filters. ```graphql { EVM(dataset: realtime, network: eth) { Transfers( where: { Transfer: { Currency: { SmartContract: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Transfer { Amount Currency { Name Symbol } Receiver Sender Type } Block { Time Number } Transaction { Hash } } } } ``` ## Get Latest ERC20 Token Transfers Query the most recent ERC20 token transfers for any token on Ethereum. This example retrieves the latest USDT (Tether) token transfers. The contract address for USDT is [0xdac17f958d2ee523a2206206994597c13d831ec7](https://explorer.bitquery.io/ethereum/token/0xdac17f958d2ee523a2206206994597c13d831ec7). You can run this query [here](https://ide.bitquery.io/UDST-Token-Transfers-on-Ethereum_2). ```graphql { EVM(dataset: realtime, network: eth) { Transfers( where: { Transfer: { Currency: { SmartContract: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Transfer { Amount Currency { Name Symbol } Receiver Sender Type } } } } ``` **Common ERC20 Token Addresses (Ethereum):** | Token | Contract Address | Symbol | | ----- | -------------------------------------------- | ------ | | USDT | `0xdac17f958d2ee523a2206206994597c13d831ec7` | USDT | | USDC | `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` | USDC | | WETH | `0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2` | WETH | | DAI | `0x6b175474e89094c44da98b954eedeac495271d0f` | DAI | | LINK | `0x514910771af9ca656af840dff83e8264ecf986ca` | LINK | --- ## Query Multiple Tokens in a Single Query Query transfers for multiple ERC20 tokens simultaneously using the `in` operator. This is useful for monitoring multiple tokens at once, building portfolio trackers that track several tokens, or analyzing transfers across a token basket. The example below queries transfers for USDT, USDC, WETH, and native ETH (`0x` represents native ETH) in a single request: ```graphql { EVM(dataset: realtime, network: eth) { Transfers( where: { Transfer: { Currency: { SmartContract: { in: [ "0xdac17f958d2ee523a2206206994597c13d831ec7" "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" "0x" ] } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Transfer { Amount Currency { Name Symbol } Receiver Sender Type } } } } ``` **Use Cases:** - Monitor multiple stablecoins simultaneously (USDT, USDC, DAI) - Track transfers for a portfolio of tokens - Analyze token movements across a token basket - Build multi-token dashboards and analytics :::tip Multi-Chain Support **Query Any EVM Network**: Change the `network` parameter to query token transfers on other EVM-compatible blockchains: - `eth` - Ethereum Mainnet - `bsc` - BNB Smart Chain (BSC) - `base` - Base L2 - `arbitrum` - Arbitrum One - `matic` - Polygon PoS - `optimism` - Optimism L2 **Example for BSC:** ```graphql { EVM(dataset: realtime, network: bsc) { Transfers( where: { Transfer: { Currency: { SmartContract: { in: ["0x55d398326f99059fF775485246999027B3197955"] // USDT on BSC } } } } limit: { count: 10 } ) { Transfer { Amount Currency { Name Symbol } Sender Receiver } } } } ``` **Solana Token Transfers**: For SPL token transfers on Solana, see our **[Solana Transfers API](/docs/blockchain/Solana/solana-transfers/)** documentation. ::: --- ## Subscribe to Real-Time ERC20 Token Transfers Monitor ERC20 token transfers in real-time using GraphQL subscriptions. This is ideal for building live dashboards, alert systems, and real-time analytics applications. This example subscribes to WETH (Wrapped Ethereum) token transfers. The contract address is [0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2](https://explorer.bitquery.io/ethereum/token/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2). You can test this subscription [here](https://ide.bitquery.io/Subscribe-to-Latest-WETH-token-transfers). ```graphql subscription { EVM(network: eth, trigger_on: head) { Transfers( where: { Transfer: { Currency: { SmartContract: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } } } orderBy: { descending: Block_Time } ) { Transaction { Hash } Transfer { Amount Currency { Name Symbol } Receiver Sender Type } } } } ``` :::tip Real-Time Monitoring For more information on setting up real-time subscriptions, see our [GraphQL Subscriptions documentation](/docs/subscriptions/subscription). ::: --- ## How do I get all inbound and outbound transfers for an address? Query transfers where a specific address is either the sender or receiver. This uses the `any` filter to implement OR logic, allowing you to find all transfers involving a particular address regardless of direction. Use `EVM.Transfers` with `where.any`: one branch matches `Transfer.Sender`, the other `Transfer.Receiver`, both set to the wallet. That returns **ERC-20** movements in both directions. Add `Block.Time` or `Block.Number` for windows, and `Currency.SmartContract` if you only want one token. Native coin movements use a separate native-transfer pattern on the same `Transfers` cube with appropriate currency filters. You can find the query [here](https://ide.bitquery.io/Sender-OR-Receiver-Transfer-on-Ethereum). ```graphql query MyQuery { EVM(dataset: archive, network: eth) { Transfers( where: { any: [ { Transfer: { Sender: { is: "0x881d40237659c251811cec9c364ef91dc08d300c" } } } { Transfer: { Receiver: { is: "0x881d40237659c251811cec9c364ef91dc08d300c" } } } ] Block: { Number: { eq: "23814227" } } } limit: { count: 100 } orderBy: { descending: Block_Time } ) { Transfer { Amount Sender Receiver Currency { Symbol Name } } Transaction { Hash From To Index } Block { Number Time } } } } ``` --- ## Addresses That Sent or Received from Multiple Addresses Find addresses that have interacted with multiple addresses from a given list. This query uses the `array_intersect` function to identify addresses that have sent or received funds to/from every address in your list. You can run the query [here](https://ide.bitquery.io/array_intersect-example-for-2-addresses_2). ```graphql query ($addresses: [String!]) { EVM(dataset: archive) { Transfers( where: { any: [ { Transfer: { Sender: { in: $addresses } } } { Transfer: { Receiver: { in: $addresses } } } ] Block: { Date: { after: "2024-04-01" } } } ) { array_intersect( side1: Transfer_Sender side2: Transfer_Receiver intersectWith: $addresses ) } } } ``` **Variables:** ```json { "addresses": [ "0x21743a2efb926033f8c6e0c3554b13a0c669f63f", "0x107f308d85d5481f5b729cfb1710532500e40217" ] } ``` :::note Array Intersect Function Learn more about the `array_intersect` function in our [Array Intersect documentation](/docs/graphql/capabilities/array-intersect). ::: --- ## Transfer Volume Analysis (Sent and Received) Calculate the total amount of tokens sent and received by a specific address for a particular token over a time period. This is essential for portfolio analysis, tax reporting, and wallet analytics. You can run this query [here](https://ide.bitquery.io/transfer-volume). ```graphql query MyQuery($address: String, $token: String) { EVM { Transfers( where: { Block: { Time: { since_relative: { years_ago: 1 } } } Transfer: { Currency: { SmartContract: { is: $token } } any: [ { Transfer: { Sender: { is: $address } } } { Transfer: { Receiver: { is: $address } } } ] } } ) { Sent: sum( of: Transfer_Amount if: { Transfer: { Sender: { is: $address } } } ) Received: sum( of: Transfer_Amount if: { Transfer: { Receiver: { is: $address } } } ) } } } ``` **Variables:** ```json { "address": "0x782c362fbf71f939445e6902a064f7e9384f47e2", "token": "0x" } ``` :::note Native ETH Transfers Use `"0x"` as the token address to query native ETH transfers. For ERC20 tokens, use the token's contract address. ::: --- ## Top Transfers of a Token Retrieve the largest token transfers for any ERC20 token. This is useful for identifying whale movements, large transactions, and significant token flows. Try the query [here](https://ide.bitquery.io/Copy-of-top-transfers-of-a-token-on-Ethereum). ```graphql query MyQuery { EVM(dataset: archive) { Transfers( where: { Transfer: { Currency: { SmartContract: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } } TransactionStatus: { Success: true } Block: { Date: { is: "2024-06-29" } } } orderBy: { descending: Block_Time } limit: { count: 10 } ) { Transfer { Amount AmountInUSD Currency { Name Symbol SmartContract } Success Sender Receiver Index Id } Transaction { To Hash Value Type GasPrice Gas From Cost } Log { Signature { Signature Name } SmartContract } Call { From To Value Signature { Name } } Block { Number Time } } } } ``` --- ## Earliest Transfer to a Wallet Find the first transfer ever received by a specific wallet address. This is useful for wallet age analysis, first transaction tracking, and onboarding analytics. [Run Query](https://ide.bitquery.io/Copy-of-find-earliest-transfer-to-an-account). ```graphql query MyQuery { EVM(network: eth, dataset: archive) { Transfers( limit: { count: 1 } where: { Transfer: { Receiver: { is: "0xe37b87598134a2fc0Eda4d71a3a80ad28C751Ed7" } } } ) { Block { Time(minimum: Block_Number) } Transaction { From Hash } Transfer { Amount Currency { Native } } } } } ``` --- ## Use Cases ### 1. Portfolio Tracking & Analytics Track all token transfers for a wallet to build comprehensive portfolio dashboards: - Monitor incoming and outgoing transfers - Calculate total sent/received volumes - Track transfer history over time - Build transaction timelines **Related APIs:** - [Ethereum Balance API](/docs/blockchain/Ethereum/balances/balance-api) - Get current wallet balances - [Transaction Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/) - Real-time balance updates ### 2. Tax & Accounting Generate comprehensive transfer reports for tax calculations, accounting reconciliation, and financial reporting: **Tax Use Cases:** - Calculate capital gains/losses from token transfers - Track cost basis for tax reporting (FIFO, LIFO, or specific identification) - Generate Form 8949 compatible reports - Calculate realized gains/losses by token and date - Export transfer history for tax software integration **Accounting Use Cases:** - Reconcile token movements with accounting records - Track transfer volumes by token and time period - Generate audit trails for financial statements - Calculate token balances from transfer history - Export CSV/JSON reports for accounting systems **Key Features:** - Export all transfers for a wallet with timestamps - Calculate transfer volumes by token - Track transfer dates and USD values - Generate comprehensive CSV/JSON reports - Filter transfers by date ranges for tax periods ### 3. DeFi Protocol Analytics Analyze token flows in and out of DeFi protocols: - Monitor liquidity movements - Track protocol token distributions - Analyze user deposit/withdrawal patterns - Measure protocol adoption **Related APIs:** - [Ethereum DEX Trades API](/docs/blockchain/Ethereum/dextrades/dex-api) - Track DEX trading activity - [Ethereum Events API](/docs/blockchain/Ethereum/events/events-api) - Monitor smart contract events ### 4. Token Distribution Analysis Understand how tokens are distributed across addresses: - Track token holder changes - Analyze concentration metrics - Monitor whale movements - Identify distribution patterns **Related APIs:** - [Token Holders API](/docs/blockchain/Ethereum/token-holders/token-holder-api) - Get top holders - [Token Supply API](/docs/blockchain/Ethereum/token-supply/evm-token-supply) - Track supply changes ### 5. Security & Fraud Detection Monitor transfers for suspicious activity: - Detect large unexpected transfers - Track transfers to known scam addresses - Monitor wallet activity patterns - Set up real-time alerts ### 6. Wallet Analytics Build comprehensive wallet analysis tools: - Calculate wallet age (earliest transfer) - Track transfer frequency - Analyze token diversity - Monitor wallet activity levels --- ## API Response Fields | Field | Description | | ------------------------------ | ---------------------------------------------- | | `Transfer.Amount` | Amount of tokens transferred | | `Transfer.AmountInUSD` | Transfer amount in USD (if available) | | `Transfer.Sender` | Address that sent the tokens | | `Transfer.Receiver` | Address that received the tokens | | `Transfer.Currency.Name` | Token name (e.g., "Tether USD") | | `Transfer.Currency.Symbol` | Token symbol (e.g., "USDT") | | `Transfer.Currency.SmartContract` | Token contract address | | `Transfer.Success` | Whether the transfer was successful | | `Transfer.Type` | Type of transfer (e.g., "call") | | `Transaction.Hash` | Transaction hash | | `Transaction.From` | Transaction sender address | | `Transaction.To` | Transaction recipient address | | `Block.Number` | Block number | | `Block.Time` | Block timestamp | --- ## Best Practices 1. **Use Appropriate Datasets**: - `realtime` for recent data (last 8 hours) - `archive` for historical data - `combined` for comprehensive queries 2. **Filter by Token Contract**: Always filter by `SmartContract` address when querying specific tokens to improve performance. 3. **Use Limit and OrderBy**: Always specify `limit` and `orderBy` to control result size and ordering. 4. **Handle Large Result Sets**: For large queries, use pagination or time-based filters to avoid timeouts. 5. **Subscribe for Real-Time Data**: Use GraphQL subscriptions for live monitoring instead of polling. 6. **Combine with Other APIs**: Enhance transfer data with balance, transaction, and event APIs for comprehensive analytics. --- ## Getting Started 1. **Get API Access**: Sign up at [Bitquery](https://bitquery.io/) to get your API key 2. **Try in IDE**: Test queries in the [Bitquery IDE](https://ide.bitquery.io/) 3. **Read Documentation**: Explore our [Getting Started Guide](/docs/start/first-query/) For more information on authentication and API usage, see our [Authorization Guide](/docs/authorization/how-to-use). ## Deterministic Pagination for Backfilling Transfers When backfilling Ethereum transfer data or building a historical index, use deterministic pagination to guarantee no records are missed or duplicated. **Try it live:** [Deterministic Transfer API](https://ide.bitquery.io/Reliable-transfer-api) ```graphql { EVM(dataset: combined, network: eth) { Transfers( where: { Transfer: { Success: true } } orderBy: { ascending: [ Block_Number, Transaction_Index, Call_Index, Log_Index, Transfer_Index, Transfer_Type ] } limit: { count: 10, offset: 0 } ) { Block { Time Number } Transaction { Hash From Index } Transfer { Amount AmountInUSD Sender Receiver Index Currency { Symbol Name SmartContract Decimals Native } } Call { Index } Log { LogAfterCallIndex Index } Transfer { Type } } } } ``` The composite `orderBy` across `Block_Number`, `Transaction_Index`, `Call_Index`, `Log_Index`, `Transfer_Index`, and `Transfer_Type` uniquely positions every transfer, making offset-based pagination safe for backfilling. Increment `offset` by the `count` value on each request. You can pull up to **25,000 records in a single request** by setting `count: 25000`. --- ## EVM DEX Slippage API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/ethereum-slippage-api/ EVM DEX Slippage API: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. Includes filters and field selection tips. # EVM DEX Slippage API In this section we will see how to get Ethereum DEX pool slippage information using our API. The slippage API helps you understand **Uniswap price impact slippage** and liquidity depth for token swaps on Ethereum DEX pools. Use it as a **Uniswap slippage calculator** to **calculate slippage** and set **Uniswap slippage tolerance** for Uniswap V2, V3, and V4 pools—including **Uniswap V3 price impact slippage** at different tolerance levels. > **Note:** This API also works for other EVM chains such as Base, BSC, and Arbitrum—just change the network parameters in your request. ## What is Slippage and Price Impact in Crypto DEX pools? Slippage refers to the difference between the expected price of a trade and the actual execution price. When swapping tokens in a DEX pool, larger trades can move the price due to limited liquidity, resulting in slippage. The DEXPoolSlippages API provides detailed information about: - Maximum input amounts that can be swapped at different slippage tolerances - Minimum output amounts guaranteed at each slippage level - Average execution prices for different trade sizes - Price impact calculations for both swap directions (A to B and B to A) For a comprehensive explanation of how DEX pools work, liquidity calculations, and price tables, refer to the [DEXPools Cube documentation](/docs/cubes/evm-dexpool/). ## Realtime Slippage Monitoring for Uniswap Pools This subscription query returns real-time slippage data for all DEX pools on Ethereum. You can monitor price impact and liquidity depth as trades occur. You can find the query [here](https://ide.bitquery.io/realtime-slippage-on-ethereum) ```graphql subscription { EVM(network: eth) { DEXPoolSlippages { Price { BtoA { Price MinAmountOut MaxAmountIn } AtoB { Price MinAmountOut MaxAmountIn } Pool { PoolId SmartContract Pair { Decimals SmartContract Name } CurrencyB { Symbol SmartContract Name Decimals } CurrencyA { Symbol SmartContract Name Decimals } } Dex { SmartContract ProtocolVersion ProtocolName ProtocolFamily } SlippageBasisPoints } Block { Time Number } } } } ``` ## Latest Slippage for a Specific Pool on Uniswap V3 This query retrieves the latest slippage data for a specific DEX pool on Ethereum. Use it to calculate slippage and check Uniswap V3 price impact slippage for a particular token pair before trading. You can find the query [here](https://ide.bitquery.io/Latest-slippage-of-a-pool-on-Uniswap-v3-Ethereum) ```graphql query { EVM(network: eth) { DEXPoolSlippages( where: {Price: {Pool: {SmartContract: {is: "0xa43fe16908251ee70ef74718545e4fe6c5ccec9f"}}}} limit: {count: 10} orderBy: {descending: Block_Time} ) { Price { BtoA { Price MinAmountOut MaxAmountIn } AtoB { Price MinAmountOut MaxAmountIn } Pool { PoolId SmartContract Pair { Decimals SmartContract Name } CurrencyB { Symbol SmartContract Name Decimals } CurrencyA { Symbol SmartContract Name Decimals } } Dex { SmartContract ProtocolVersion ProtocolName ProtocolFamily } SlippageBasisPoints } Block { Time Number } } } } ``` > **Note:** This query can be converted to a subscription to monitor in real-time. Simply replace `query` with `subscription` to receive live updates whenever the pool's liquidity changes. ## Realtime Slippage for Uniswap V4 Pools This subscription query retrieves real-time slippage data for Uniswap V4 pools on Ethereum. Unlike Uniswap V3, which uses the pool's smart contract address, Uniswap V4 requires using the `PoolId` to identify pools. In Uniswap V4, liquidity is managed by a centralized pool manager contract. You can find the query [here](https://ide.bitquery.io/realtime-pair-slippage-on-ethereum-uniswap-v4) ```graphql subscription { EVM(network: eth) { DEXPoolSlippages( where: {Price: {Pool: {PoolId: {is: "0x89c10991af36a29d4a14b346a272baa7205d2b41c72013f61cfca41ef2666412"}}}} ) { Price { BtoA { Price MinAmountOut MaxAmountIn } AtoB { Price MinAmountOut MaxAmountIn } Pool { PoolId SmartContract Pair { Decimals SmartContract Name } CurrencyB { Symbol SmartContract Name Decimals } CurrencyA { Symbol SmartContract Name Decimals } } Dex { SmartContract ProtocolVersion ProtocolName ProtocolFamily } SlippageBasisPoints } Block { Time Number } } } } ``` ## Realtime Slippage Data via Kafka Streams Slippage data can also be obtained via Kafka streams for lower latency and better reliability. The Kafka topic for Ethereum DEX pools is: **`ethereum.dexpools.proto`** Kafka streams provide the same slippage data as GraphQL subscriptions but with several advantages: - Lower latency due to shorter data pipeline - Better reliability with persistent connections - Ability to read from latest offset without gaps - Better scalability with multiple consumers For detailed information on how to connect to Kafka streams, subscribe to topics, and parse messages, refer to the [Kafka Streaming Concepts documentation](/docs/streams/kafka-streaming-concepts/). > **Note:** IDE credentials will not work with Kafka Streams. You need separate Kafka credentials. Please contact sales on our official telegram channel or fill out the [form on our website](https://bitquery.io/forms/api). ## Understanding the Response The `DEXPoolSlippages` API response contains the following information: - **`Price`**: Price information for swaps at a specific slippage tolerance - **`AtoB`**: Price data for swapping CurrencyA to CurrencyB - `Price`: Average execution price for swaps at this slippage level - `MinAmountOut`: Minimum output amount guaranteed at this slippage level - `MaxAmountIn`: Maximum input amount that can be swapped at this slippage level - **`BtoA`**: Price data for swapping CurrencyB to CurrencyA (same structure as AtoB) - **`SlippageBasisPoints`**: Slippage tolerance in basis points (100 = 1%) - **`Pool`**: Pool information including token pair details - **`Dex`**: DEX protocol information (Uniswap V2, V3, V4, etc.) - **`Block`**: Block information when the slippage data was recorded - `Time`: Timestamp of the block - `Number`: Block number For more details on how slippage is calculated and when new pool records are emitted, see the [DEXPools Cube documentation](/docs/cubes/evm-dexpool/#when-is-a-new-dexpool-record-emitted-in-the-apis--streams). ## Use Cases ### Liquidity Depth Analysis Use the slippage API as a Uniswap slippage calculator to analyze which pools can handle large trades without significant price impact. By examining `MaxAmountIn` values at different slippage levels, you can: - Identify pools with sufficient liquidity for your trade size - Determine optimal slippage tolerance settings - Estimate price impact before executing trades ### Multi-Pool Price Comparison Compare execution prices across different pools and slippage scenarios to: - Find the best pool for your specific trade size - Understand price differences between DEX protocols - Optimize trade execution strategies ### Trading Applications #### Live Execution Testing Use the slippage API to test and validate trade execution strategies in real-time: - **Pre-trade validation**: Check if your intended trade size can be executed within acceptable slippage bounds before submitting - **Execution simulation**: Calculate expected price impact and minimum output amounts for different trade sizes - **Strategy backtesting**: Monitor historical slippage data to validate trading algorithms and optimize entry/exit points - **Risk assessment**: Evaluate maximum position sizes that can be entered without exceeding your slippage tolerance #### Detecting Liquidity Shocks and Toxic Order Flow The slippage API helps identify temporary price dislocations and liquidity shocks that can be exploited or avoided: - **Flow toxicity detection**: Monitor sudden changes in `MaxAmountIn` values to detect when pools experience large outflows or inflows - **Price impact analysis**: Track how `MinAmountOut` changes relative to `MaxAmountIn` to identify when pools become less liquid - **Mean reversion opportunities**: Identify pools where large swaps have created temporary price dislocations that may revert - **Toxic order flow avoidance**: Use slippage data to avoid entering positions when liquidity is thin or when large trades are likely to move price against you For a practical implementation example of using slippage data for automated trading strategies, including flow toxicity detection and mean-reversion trading, see the [AMM Flow Toxicity Alpha Engine](https://github.com/Divyn/amm-flow-toxicity-alpha-engine) repository. This system demonstrates how to: - Detect large swaps that move price significantly (50-500 basis points) - Verify isolation from trending markets - Execute fade trades against temporary price impacts - Manage positions with dynamic stop losses and take profits based on slippage data For more advanced use cases, refer to the [DEXPools Cube documentation](/docs/cubes/evm-dexpool/#advanced-use-cases-and-processing-patterns). --- ## EVM Token Supply API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/token-supply/evm-token-supply/ EVM Token Supply API: stream Ethereum market cap, FDV, supply, and price using Bitquery Trading GraphQL APIs. Run it in the IDE, then ship in your app. # EVM Token Supply API Track real-time and historical token supply data across all EVM-compatible blockchains including Ethereum, BNB Chain (BSC), Base, Arbitrum, Polygon, and more using Bitquery's Token Supply API. :::info Looking for Solana Token Supply? Bitquery also provides comprehensive **[Solana Token Supply API](/docs/blockchain/Solana/token-supply-cube/)** with features including: - Real-time token supply changes and market cap tracking - Pump.fun and Moonshot token creation monitoring - Token burn event tracking - Top tokens by market cap queries ➡️ **[View Solana Token Supply Documentation](/docs/blockchain/Solana/token-supply-cube/)** ::: ## What is Token Supply? Token supply refers to the total number of tokens that exist for a particular cryptocurrency or token. Understanding token supply is crucial for: - **Market Cap Calculation**: Total Supply × Token Price = Market Capitalization - **Inflation/Deflation Analysis**: Monitor minting and burning events - **DeFi Protocol Analysis**: Track liquidity and TVL changes - **Stablecoin Monitoring**: Verify backing and supply changes for USDT, USDC, DAI, etc. - **Investment Research**: Evaluate tokenomics and supply dynamics ## How do I get the total supply or circulating supply of a token? **Total supply on EVM:** Use Bitquery `EVM.TransactionBalances` (or streaming equivalents) and read `TokenBalance.TotalSupply` for the token contract, setting `network` to `eth`, `bsc`, `base`, or another supported chain. **Circulating supply** is not a single on-chain field: it is usually derived as total supply minus known treasury or locked wallets, or adjusted for burns—use mint/burn and transfer patterns from the same API family if you define it that way. ## 🔗 Related APIs ### EVM APIs - **[EVM Balance Updates API](/docs/schema/evm/balances/)** - Track wallet balance changes - **[EVM Token Holders API](/docs/schema/evm/token-holders/)** - Get top holders of any token - **[EVM Transfers API](/docs/schema/evm/transfers/)** - Monitor token transfers - **[EVM DEX Trades API](/docs/schema/evm/dextrades/)** - Track trading activity ### Solana APIs - **[Solana Token Supply API](/docs/blockchain/Solana/token-supply-cube/)** - Track SPL token supply, market cap, and burn events - **[Solana Balance Updates API](/docs/blockchain/Solana/solana-balance-updates/)** - Monitor Solana wallet balances - **[Solana DEX Trades API](/docs/blockchain/Solana/solana-dextrades/)** - Track Solana DEX trading activity --- ## Real-Time Token Supply Stream (WebSocket) ### Latest Token Supply on BNB Chain Subscribe to real-time token supply updates across all tokens on the BNB Chain (BSC). This WebSocket subscription provides continuous updates as token supplies change due to minting or burning. You can run this query [here](https://ide.bitquery.io/latest-token-supply-on-BSC-chain). ```graphql subscription { EVM(network: bsc) { TransactionBalances( limitBy: { by: TokenBalance_Currency_SmartContract, count: 1 } where: { TokenBalance: { Currency: { SmartContract: { not: "0x" } } } } ) { TokenBalance { TotalSupply Currency { Name Symbol SmartContract } } } } } ``` **Key Parameters:** - `limitBy: { by: TokenBalance_Currency_SmartContract, count: 1 }` - Returns only the latest supply for each unique token - `SmartContract: { not: "0x" }` - Excludes native currency (BNB) to focus on ERC-20 tokens :::tip Multi-Chain Support Change the `network` parameter to query other EVM chains: - `eth` - Ethereum - `bsc` - BNB Chain - `base` - Base - `arbitrum` - Arbitrum - `matic` - Polygon - `optimism` - Optimism ::: --- ## Token Supply Queries (GraphQL) ### Latest Token Supply of Specific Tokens on Ethereum Get the current total supply for specific tokens like USDC and USDT on Ethereum or any EVM network. This is ideal for stablecoin tracking and portfolio applications. You can run this query [here](https://ide.bitquery.io/latest-token-supply-on-USDT-and-USDC-on-ethereum-chain). ```graphql { EVM(network: eth) { TransactionBalances( orderBy: { descending: Block_Time } limitBy: { by: TokenBalance_Currency_SmartContract, count: 1 } where: { TokenBalance: { Currency: { SmartContract: { in: [ "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" "0xdac17f958d2ee523a2206206994597c13d831ec7" ] } } } } ) { TokenBalance { TotalSupply Currency { Name Symbol SmartContract } } } } } ``` **Common Token Addresses (Ethereum):** | Token | Contract Address | | ----- | -------------------------------------------- | | USDT | `0xdac17f958d2ee523a2206206994597c13d831ec7` | | USDC | `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` | | DAI | `0x6b175474e89094c44da98b954eedeac495271d0f` | | WETH | `0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2` | | LINK | `0x514910771af9ca656af840dff83e8264ecf986ca` | --- ### Latest Token Supply of All Active Tokens on Base Retrieve the latest total supply for all active tokens on the Base blockchain. This query is useful for market analytics, portfolio trackers, and DeFi dashboards. You can run this query [here](https://ide.bitquery.io/latest-token-supply-of-all-active-tokens-on-base-chain). ```graphql { EVM(network: base) { TransactionBalances( orderBy: { descending: Block_Time } limitBy: { by: TokenBalance_Currency_SmartContract, count: 1 } where: { TokenBalance: { Currency: { SmartContract: { not: "0x" } } } } ) { TokenBalance { TotalSupply Currency { Name Symbol SmartContract } } } } } ``` --- ## Use Cases ### 1. Stablecoin Supply Monitoring Track stablecoin supplies to monitor market dynamics and potential de-pegging risks: - Monitor USDT, USDC, DAI supply changes in real-time - Detect large minting or burning events - Compare supply across different chains ### 2. Market Cap Calculation Calculate accurate market capitalization by combining supply data with price feeds: ``` Market Cap = Total Supply × Current Price ``` ### 3. Token Inflation Analysis Analyze token inflation rates by comparing supply changes over time: - Track new token emissions - Monitor burning mechanisms - Calculate inflation/deflation rates ### 4. DeFi Protocol Analytics Monitor supply changes for DeFi governance tokens and LP tokens to understand protocol health and user activity. ### 5. Compliance & Auditing Maintain audit trails of supply changes for regulatory compliance and financial reporting. --- ## API Response Fields | Field | Description | | ------------------------------------- | ---------------------------------------- | | `TokenBalance.TotalSupply` | Current total supply of the token | | `TokenBalance.Currency.Name` | Token name (e.g., "USD Coin") | | `TokenBalance.Currency.Symbol` | Token symbol (e.g., "USDC") | | `TokenBalance.Currency.SmartContract` | Token contract address | | `TokenBalance.Currency.Decimals` | Number of decimal places | | `Block.Number` | Block number of the supply update | | `Block.Time` | Timestamp of the supply update | --- ## Supported Networks | Network | Parameter | Description | | -------- | ----------- | ------------------- | | Ethereum | `eth` | Ethereum Mainnet | | BNB Chain| `bsc` | BNB Smart Chain | | Base | `base` | Base L2 | | Arbitrum | `arbitrum` | Arbitrum One | | Polygon | `matic` | Polygon PoS | | Optimism | `optimism` | Optimism L2 | | Robinhood| `robinhood` | Robinhood network | | Arc | `arc` | Arc mainnet | --- ## Best Practices 1. **Use `limitBy` for Latest Data**: Always use `limitBy: { by: TokenBalance_Currency_SmartContract, count: 1 }` to get only the most recent supply for each token. 2. **Filter by Smart Contract**: When querying specific tokens, use the `SmartContract: { is: "..." }` filter to improve query performance. 3. **Use Archive Dataset for History**: For historical queries, specify `dataset: archive` to access complete blockchain history. 4. **Handle Decimals Properly**: Remember to divide `TotalSupply` by `10^Decimals` to get the human-readable supply value. --- ## Getting Started 1. **Get API Access**: Sign up at [Bitquery](https://bitquery.io/) to get your API key 2. **Try in IDE**: Test queries in the [Bitquery IDE](https://ide.bitquery.io/) 3. **Integrate**: Use the GraphQL endpoint in your application For more information on authentication and API usage, see our [Getting Started Guide](/docs/start/first-query/). --- ## Ethereum API - Best Blockchain Data API for Developers URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ Ethereum on-chain data API: DEX trades, slippage, liquidity, token holders, balances and token transfers, with real-time streaming and how it differs from RPC. # Ethereum API - Complete Developer Guide :::tip Building a trading app or DEX UI on Ethereum? For **real-time trades and prices on Ethereum** (and the last ~30 days), use the curated [**Trading cube**](/docs/trading/trading-data-overview) — [`Trading.Trades`](/docs/trading/crypto-trades-api/trades-api) gives you clean, MEV-filtered swaps with **USD price, market cap, and supply on every row** across **10 chains in one API**. For **historical Ethereum data older than ~30 days**, use the chain-level `DEXTrades` / `DEXTradeByTokens` APIs documented below. ::: ## What is Bitquery? Bitquery is the leading blockchain data platform that provides comprehensive **Ethereum API** solutions for developers. Instead of running your own Ethereum node or building complex indexing infrastructure, you can use our pre-built **Ethereum API** to get the blockchain data you need in seconds. Our **Ethereum API** provides comprehensive access to all Ethereum blockchain data including transactions, token balances, DEX trades, liquidity events, slippage data, pool reserves, blocks, smart contract events, gas fees, mempool data, and NFT information. Available through GraphQL API with real-time streaming via GraphQL subscriptions and Kafka. ## Getting Started New to Bitquery? Here's how to get started: 1. **[Create a free account](https://ide.bitquery.io/)** - Get instant access to our GraphQL IDE 2. **[Generate your API key](/docs/authorization/how-to-generate/)** - Required for API access 3. **[Run your first query](/docs/start/first-query/)** - Learn the basics in 5 minutes 4. **[Explore examples](/docs/start/starter-queries/)** - Copy-paste ready queries **Free trial**: 7 days and 1,000 API points, on real-time data only. No credit card required. Need help crafting a query or subscription? Message us on [support](https://t.me/Bloxy_info). ## Why Choose Bitquery's Ethereum API? Unlike traditional Ethereum JSON-RPC providers, our **Ethereum API** stores, indexes, and enriches every Ethereum transaction, event, contract call, token transfer, balance update, and DEX trade. Our advanced **Ethereum API** allows you to query both historical and real-time Ethereum blockchain data from multiple dimensions without the complexity of running your own infrastructure. ### Key Benefits of Our Ethereum API: - **Complete Data Coverage**: Access to all Ethereum blockchain data since genesis - **Real-time Updates**: Live data streaming via GraphQL subscriptions and Kafka - **Advanced Analytics**: Pre-computed metrics and enriched data - **Developer-Friendly**: GraphQL interface with comprehensive documentation - **High Performance**: Sub-second response times for complex queries - **Cost-Effective**: Free tier with 1,000 API calls per day ## How is it different from raw Ethereum RPC or Ethereum node API? **Ethereum RPC** - Low‑level JSON‑RPC that returns raw node data - No historical indexing, joins, or analytics out of the box - Best for transaction submission and node-level introspection **Bitquery Ethereum API** - Pre‑indexed, enriched datasets exposed via GraphQL - Powerful filtering, joins, aggregations, and subscriptions (Websockets / Webhooks) - Ideal for building applications, analytics, monitoring, dashboards, and reporting without running infra ## What can you build with it? Build powerful applications including: - **Trading Tools**: Trading terminals, bots, and automated strategies - **Portfolio Trackers**: Monitor wallet portfolios and token holders - **Compliance Tools**: Tax reporting, auditing, and accounting products - **DeFi Analytics**: Monitor DEX price/volume, liquidity events, slippage, and pool reserves - **Network Analysis**: Analyze gas usage, fees, and network health - **Real-time Monitoring**: Stream mempool activity and pending transactions - **Business Intelligence**: Compute KPIs over blocks/transactions for dashboards ## Real-time Data & Streaming Get live Ethereum data through our streaming solutions: - **GraphQL Subscriptions**: Convert any query to a live stream by changing `query` to `subscription` - **Kafka Streaming**: High-throughput streaming for enterprise applications See examples and code snippets [here](/docs/subscriptions/websockets/) for GraphQL subscription implementation, and learn about [Kafka streaming](/docs/streams/kafka-streaming-concepts/) for high-volume use cases. ## Ethereum DEX Trades APIs - [Ethereum DEX API](/docs/blockchain/Ethereum/dextrades/dex-api) - [Ethereum Token Trades APIs](/docs/blockchain/Ethereum/dextrades/token-trades-apis) - [Trades of an Ethereum Address API](/docs/blockchain/Ethereum/dextrades/trades-of-an-address-api) - [Uniswap API](/docs/blockchain/Ethereum/dextrades/uniswap-api) - [Pancakeswap API](/docs/blockchain/Ethereum/dextrades/pancakeswap-api) - [DEXScreener (EVM)](/docs/blockchain/Ethereum/dextrades/DEXScreener/evm_dexscreener) Query and subscribe to on‑chain swaps, OHLCV, liquidity events, pools, and per‑wallet trading activity across major EVM DEXes. ## Ethereum Slippage API - [Ethereum Slippage API](/docs/blockchain/Ethereum/dextrades/ethereum-slippage-api) Get slippage and price impact data for Ethereum DEX pools. Understand price impact and liquidity depth for token swaps, calculate maximum input amounts at different slippage tolerances, and monitor real-time slippage data across all DEX pools on Ethereum. ## Ethereum Liquidity API - [Ethereum Liquidity API](/docs/blockchain/Ethereum/dextrades/ethereum-liquidity-api) Monitor real-time liquidity changes, track pool reserves, and analyze liquidity depth for token pairs on Ethereum DEX pools. Track when liquidity is added or removed, monitor pool health and depth, and analyze liquidity patterns across different pools. ## Ethereum Token Holders API - [Token Holder API](/docs/blockchain/Ethereum/token-holders/token-holder-api) Track and analyze token holder distributions with comprehensive historical and real-time data. Get top holders by balance, monitor holder count changes, calculate distribution metrics like Gini coefficient and Nakamoto coefficient for decentralization analysis, identify new and active holders, and track first/last activity dates for any ERC-20 token on Ethereum. ## Ethereum Balance API - [Balance API](/docs/blockchain/Ethereum/balances/balance-api) Get real‑time and historical token and native ETH balances for any Ethereum address. Track balance changes over time, calculate portfolio values in USD, and monitor wallet holdings across ERC20, ERC721, and ERC1155 tokens. Perfect for building portfolio trackers, tax tools, and wallet analytics. ## Ethereum Token Transfers API - [ERC20 Token Transfer API](/docs/blockchain/Ethereum/transfers/erc20-token-transfer-api) - [Ethereum Token Total Supply API](/docs/blockchain/Ethereum/transfers/total-supply) Track comprehensive token transfer activity across Ethereum with support for all major ERC standards including ERC20, ERC721, ERC1155, and more. Monitor transfers for any Ethereum address or smart contract, analyze inflow and outflow patterns, and discover specific transfers across the entire blockchain for any token. Get enriched data with corresponding USD values, transfer volumes, and detailed transaction context to power portfolio tracking, Tax tools, compliance monitoring, and token analytics applications. ## Ethereum Blocks API - [Ethereum Blocks API](/docs/blockchain/Ethereum/blocks/blocks-api) Access comprehensive Ethereum block data including block headers, timestamps, gas usage, miner/validator information, base fees, and transaction counts. Build time‑series analytics, monitor network health, track block production patterns, analyze fee dynamics, and compute blockchain metrics. Perfect for building block explorers, network monitoring tools, and blockchain analytics dashboards. ## Ethereum Smart Contract Events API - [Ethereum Smart Contract Events API](/docs/blockchain/Ethereum/events/events-api) Access and analyze smart contract events across Ethereum with comprehensive filtering and decoding capabilities. Query contract logs by specific topics, parameters, addresses, and event signatures to track contract interactions, state changes, and protocol activity. Get decoded event data with parameter names and values, filter by block ranges or time periods, and monitor real-time contract events. Essential for building DeFi analytics, protocol monitoring tools, governance trackers, and smart contract auditing systems. ## Ethereum Transaction Fees API - [Ethereum Transaction Fees API](/docs/blockchain/Ethereum/fees/fees-api) Analyze comprehensive transaction fee data across Ethereum including gas usage patterns, base fee dynamics, priority fees, and transaction cost distributions. Track gas consumption by transaction type, monitor EIP-1559 fee market mechanics, calculate average gas prices over time, and analyze fee optimization strategies. Get detailed gas usage statistics, fee predictions, and cost analysis to power gas estimation tools, transaction optimization services, and fee market analytics dashboards. ## Ethereum Mempool API - [Ethereum Mempool API](/docs/blockchain/Ethereum/mempool/mempool-api) Monitor and analyze Ethereum's mempool to track pending transactions before they are included in blocks. Get real-time insights into transaction queues, fee estimations, and network congestion patterns. Track pending transactions by address, value, gas price, and transaction type to build MEV strategies, optimize transaction timing, and provide better fee estimation services. Additionally, simulate mempool transactions to preview potential transfers, trades, and contract interactions before execution, enabling advanced analysis of transaction outcomes and state changes. Essential for building frontrunning protection, transaction monitoring tools, MEV detection systems, and advanced DeFi applications that need to react to pending on-chain activity. ## Ethereum NFT API - [Ethereum NFT API](/docs/blockchain/Ethereum/nft/nft-api) Access comprehensive NFT data across Ethereum including collections, ownership tracking, transfer history, marketplace trades, and metadata. Query NFT collections by contract address, track ownership changes and holder distributions, monitor NFT transfers and sales across major marketplaces like OpenSea and LooksRare, and retrieve detailed token metadata including images, attributes, and rarity information. Get enriched trading data with USD values, floor prices, and volume metrics to power NFT analytics dashboards, portfolio trackers, rarity tools, and marketplace monitoring applications. ## Ethereum Transactions API - [Ethereum Transaction API](/docs/blockchain/Ethereum/transactions/transaction-api) Query detailed Ethereum transaction data including transaction hashes, from/to addresses, values transferred, gas prices, gas limits, gas used, nonce values, and transaction status. Access transaction input data, method signatures, internal transactions, and execution traces. Filter transactions by sender, receiver, value ranges, time periods, or transaction type to analyze payment flows, contract calls, and wallet behavior. Retrieve comprehensive transaction receipts with logs, events, and error details for both successful and failed transactions. Essential for transaction monitoring, forensic analysis, compliance reporting, and building comprehensive blockchain data applications. ## Ethereum Videos Tutorials ### DEX Trades on EVM (Uniswap, Aggregators, Screens) ### Ethereum Price & Balances ## More guides - [Data Coverage & Retention](/docs/graphql/data-coverage-retention/) — how far back this chain's data goes - [Common errors and what to do](/docs/start/errors/) - [Plans, Points & Limits](/docs/plans/how-billing-works/) - [First query in 5 minutes](/docs/start/first-query/) --- ## Ethereum Balance API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/balance-api/ Ethereum Balance API: fetch current and historical Ethereum balances with Bitquery GraphQL balance queries. Great for bots, dashboards, and alerts. # Address Balance API The **Balances** API returns current and historical token balances for an address on Ethereum. To return only non-zero balances, add `Amount(selectWhere: { gt: "0" })` on the `Balance` field (not in `where`). Use `dataset: combined` or `dataset: archive` as follows: | Dataset | When to use | | -------------- | ------------------------------------------------------------------------------------------- | | **`combined`** | Latest balances. Queries **realtime and archive** databases and merges results. | | **`archive`** | Historical snapshots with `Block.Date`, and balances for **addresses not recently active**. | ## Balance of an Address Returns token balances for a wallet address. Use `Amount(selectWhere: { gt: "0" })` to exclude zero balances. [Run in IDE](https://ide.bitquery.io/Ethereum-Balance-of-an-Address) ```graphql query { EVM(network: eth, dataset: combined) { Balances( where: { Balance: { Address: { is: "0x76147fd7891731e01f35cc18f87ae8e95bf06869" } } } ) { Currency { Symbol SmartContract } Balance { Amount(selectWhere: { gt: "0" }) AmountInUSD Address } } } } ``` **Parameters** - `network: eth`: Ethereum mainnet. - `dataset: combined`: Merges realtime and archive data for the latest balance state. - `Balance.Address`: Wallet address to query. **Returned fields** - `Currency.Symbol`, `Currency.SmartContract`: Token metadata. - `Balance.Amount`, `Balance.AmountInUSD`: Token balance and USD value (use `selectWhere` to filter non-zero amounts). ## Balance on a Specific Date Use `Block.Date.till` for a point-in-time snapshot. Use `dataset: archive` for historical dates and addresses not recently active. [Run in IDE](https://ide.bitquery.io/ethereum-balances-address-by-date) ```graphql { EVM(network: eth, dataset: combined) { Balances( where: { Balance: { Address: { is: "0xf9D48e42d0FEb477a0286B206eDbafefA3577F63" } } Block: { Date: { till: "2026-04-01" } } } ) { Currency { Symbol SmartContract } Balance { Amount(selectWhere: { gt: "0" }) AmountInUSD } } } } ``` ## Balance for a Specific Token Add a `Currency.SmartContract` filter. Always use the contract address, not the token name. [Run in IDE](https://ide.bitquery.io/ethereum-balances-specific-token) ```graphql query { EVM(network: eth, dataset: combined) { Balances( where: { Balance: { Address: { is: "0x3416cf6c708da44db2624d63ea0aaef7113527c6" } } Currency: { SmartContract: { is: "0x54D2252757e1672EEaD234D27B1270728fF90581" } } } ) { Currency { Symbol SmartContract } Balance { Amount(selectWhere: { gt: "0" }) AmountInUSD Address } } } } ``` ## Balance History by Date Returns balance snapshots over time for an address. Use `dataset: archive`. Order by `Block_Date` descending and use `limit` to paginate. Add `Currency.SmartContract` under `Currency` to filter by a specific token. [Run in IDE](https://ide.bitquery.io/ethereum-balances-history) ```graphql query { EVM(network: eth, dataset: archive) { Balances( where: { Balance: { Address: { is: "0x5646c5b4845e565706ef107f62887145a51a3127" } } Currency: {} } orderBy: { descending: Block_Date } limit: { count: 100 } ) { Currency { Symbol SmartContract } Balance { Amount(selectWhere: { gt: "0" }) AmountInUSD } Block { Date } } } } ``` ## Wallet Balance for a Specific Token on a Date Use `dataset: archive`, `Block.Date.till`, `orderBy: { descending: Block_Date }`, and `limit: { count: 1 }` to get the balance as of that date. [Run in IDE](https://ide.bitquery.io/ethereum-wallet-balance-token-at-date) ```graphql query { EVM(network: eth, dataset: archive) { Balances( where: { Block: { Date: { till: "2026-05-05" } } Balance: { Address: { is: "0xA46320Aa0b4877b9a46a07B4F3DB93719bd422dE" } } Currency: { SmartContract: { is: "0x54D2252757e1672EEaD234D27B1270728fF90581" } } } limit: { count: 1 } orderBy: { descending: Block_Date } ) { Currency { Symbol SmartContract } Balance { Amount(selectWhere: { gt: "0" }) AmountInUSD Address } } } } ``` --- ## Ethereum Blocks API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/blocks/blocks-api/ Ethereum blocks: get the latest blocks on the network with their parameters and result fields explained, using a ready-to-run Bitquery GraphQL query. # Blocks API ## Latest blocks in the Ethereum network This GraphQL query retrieves the latest blocks in real time on the Ethereum network that were mined after March 3rd, 2023. It includes information on the block number, hash, mix digest, date, base fee, coinbase, transaction hash, transaction count, and result (including gas and errors). You can find the query [here](https://ide.bitquery.io/Latest-blocks-in-the-Ethereum-network_1). ```graphql subscription { EVM(network: eth) { Blocks( limit: { count: 10 } orderBy: { descending: Block_Time } where: { Block: { Date: { after: "2023-03-03" } } } ) { Block { Number Hash MixDigest Date BaseFee Coinbase TxHash TxCount Result { Errors Gas } } } } } ``` ### Parameters - `network`: The blockchain network to query (e.g., `eth`, `bsc`, `polygon`). - `limit`: The maximum number of blocks to retrieve (here set to 10). - `orderBy`: The field and direction to sort the results (e.g., `orderBy: {descending: Block_Time}`). - `where`: Conditions to filter blocks by (e.g., `where: {Block: {Date: {after: "2023-03-03"}}}`). ### Results - **Block**: Information about each block, including: - `Number` - `Hash` - `MixDigest` - `Date` - `BaseFee` - `Coinbase` - `TxHash` - `TxCount` - **Result**: Execution details for each block: - `Errors` - `Gas` --- ## Ethereum DEX Trades API: Every DEX, Pair Stats, Traders and Latest Swaps URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/dex-api/ Ethereum DEX data with Bitquery GraphQL: which protocols trade and how much, one family's daily stats, busiest pairs, top traders, latest swaps, no outliers. # Ethereum DEX Trades API: Every DEX, Pair Stats, Traders and Latest Swaps Two cubes hold Ethereum's DEX swaps. `DEXTrades` has one row per swap with both sides, the pool and the protocol, and reaches history on the archive dataset. `DEXTradeByTokens` has one row per swap per token, which is the shape for anything grouped by token, pair, protocol or trader. The [Trading cube](/docs/trading/crypto-trades-api/trades-api) adds a third option for the last month or so: swaps with the trader, USD price, market cap and supply on every row across ten chains, and it is the better start for live feeds. This page uses the two chain cubes to answer the questions people ask about Ethereum DEXs as a whole: which ones trade, how much, who trades on them, what just happened. Every example runs in the [IDE](https://ide.bitquery.io) on a free account. One caution runs through the page: a few swaps in thin pools carry absurd USD values, so every sum here caps the USD of a single trade with `Side: { AmountInUSD: { lt: "10000000" } }`; drop the cap if you want raw totals. ## Which DEXs trade on Ethereum, and how much Group by protocol over the last day. `ProtocolFamily` is the brand and `ProtocolName` the version; Uniswap v3, v4 and v2 lead by trades, with PancakeSwap v3, Balancer, Curve, Fluid and the rest behind them. Saved query [here](https://ide.bitquery.io/dex-markets). ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { Side: { AmountInUSD: { lt: "10000000" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } orderBy: { descendingByField: "trades" } limit: { count: 30 } ) { Trade { Dex { ProtocolFamily ProtocolName } } trades: count volumeUsd: sum(of: Trade_Side_AmountInUSD) traders: uniq(of: Transaction_From) } } } ``` The same list, kept live, is on [DEXrabbit](https://dexrabbit.bitquery.io/eth/dex_market). ## One DEX family's day Trades, USD volume, distinct traders, tokens and pools for a protocol family. Saved query [here](https://ide.bitquery.io/dex-info). ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { Dex: { ProtocolFamily: { is: "Uniswap" } } Side: { AmountInUSD: { lt: "10000000" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { trades: count volumeUsd: sum(of: Trade_Side_AmountInUSD) traders: uniq(of: Transaction_From) tokens: uniq(of: Trade_Currency_SmartContract) pools: uniq(of: Trade_Dex_SmartContract) } } } ``` ## The busiest pairs on a DEX Pairs against WETH, USDC or USDT on Uniswap over the last three hours, ranked by USD volume, with distinct buyers and sellers. Each row is a token and the quote it traded against. Saved query [here](https://ide.bitquery.io/trading-pairs-on-a-specific-dex). ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { Dex: { ProtocolFamily: { is: "Uniswap" } } Side: { AmountInUSD: { lt: "10000000" } Currency: { SmartContract: { in: [ "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" "0xdac17f958d2ee523a2206206994597c13d831ec7" ] } } } } Block: { Time: { since_relative: { hours_ago: 3 } } } } orderBy: { descendingByField: "volumeUsd" } limit: { count: 50 } ) { Trade { Currency { Symbol SmartContract } Side { Currency { Symbol } } Dex { ProtocolName } } trades: count volumeUsd: sum(of: Trade_Side_AmountInUSD) buyers: uniq(of: Trade_Buyer) sellers: uniq(of: Trade_Seller) } } } ``` ## Top traders on a DEX Rank by `Transaction.From`, the account that sent the swap, which works for every protocol version including Uniswap v4, where the pool manager appears as buyer and seller on raw rows. Saved query [here](https://ide.bitquery.io/top-traders-on-a-DEX_1). ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { Dex: { ProtocolFamily: { is: "Uniswap" } } Side: { AmountInUSD: { lt: "10000000" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } orderBy: { descendingByField: "volumeUsd" } limit: { count: 50 } ) { Transaction { From } trades: count volumeUsd: sum(of: Trade_Side_AmountInUSD) tokens: uniq(of: Trade_Currency_SmartContract) } } } ``` [DEXrabbit](https://dexrabbit.bitquery.io/eth/dex_market/Uniswap#traders) shows this table for each DEX. ## Latest swaps on a DEX Raw rows from `DEXTrades`, newest first; change `query` to `subscription` and drop `limit` and `orderBy` for a live feed. Saved query [here](https://ide.bitquery.io/latest-trades_5). ```graphql { EVM(network: eth) { DEXTrades( where: { Trade: { Dex: { ProtocolFamily: { is: "Uniswap" } } } } orderBy: { descending: Block_Time } limit: { count: 50 } ) { Block { Time } Trade { Dex { ProtocolName SmartContract } Buy { Currency { Symbol } Amount AmountInUSD } Sell { Currency { Symbol } Amount AmountInUSD } } Transaction { Hash From } } } } ``` ## Where to go next - One venue in depth: [Uniswap](/docs/blockchain/Ethereum/dextrades/uniswap-api), [Uniswap v4](/docs/blockchain/Ethereum/dextrades/uniswap-v4-api), [PancakeSwap](/docs/blockchain/Ethereum/dextrades/pancakeswap-api). - Every pool a token trades in: [trading pairs API](/docs/blockchain/Ethereum/dextrades/get-trading-pairs-of-token). - Live swaps with trader and market cap on each row: [Crypto Trades API](/docs/trading/crypto-trades-api/trades-api). - When to use which cube: [DEXTrades vs DEXTradeByTokens vs Trades](/docs/cubes/dextrades-dextradebytokens-trading-trades). --- ## Ethereum EVM DEXscreener API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/DEXScreener/evm_dexscreener/ Ethereum EVM DEXscreener API: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. See examples in the Bitquery IDE. # DEXScreener EVM API Everything you see on the DEXScreener EVM dashboard—live pairs, trades, prices, volumes, makers/buyers/sellers, and more—can be accessed via APIs/Streams with Bitquery. We expose the same on-chain data via GraphQL APIs, real-time WebSocket streams, and enterprise Kafka topics, with optional cloud connectors (AWS, GCP, Snowflake) for analytics pipelines. Checkout our [DEXScreener Solana API documentation](/docs/blockchain/Solana/DEXScreener/solana_dexscreener/) if you are interested in getting Solana data which DEXScreener shows. :::note DEXScreener EVM APIs include data apis for EVM chains like Ethereum, Binance Smart Chain(BSC), Arbitrum, Base, Matic, Optimism, etc ::: ## Bitquery EVM Data Access Options - **GraphQL APIs**: Query historical and real-time EVM data with flexible filtering and aggregation - **Real-time Streams**: Subscribe to live EVM blockchain events via WebSocket subscriptions - **Cloud Solutions**: Access EVM data through AWS, GCP, and Snowflake integrations - **Kafka Streams**: High-throughput data streaming for enterprise applications ## Getting Started with EVM - **[EVM API Examples](/docs/blockchain/Ethereum/)** - Complete collection of EVM API examples - **[EVM DEX Trades](/docs/category/dex-trades/)** - Real-time DEX trading data and analytics - **[EVM Subscriptions](/docs/subscriptions/subscription)** - Learn how to set up real-time data streams - **[IDE for EVM](https://ide.bitquery.io)** - Interactive development environment for testing EVM queries This guide shows how to retrieve the same EVM DEX data that DEXScreener displays—real-time trades, pair stats, volumes, buyers/sellers, and more—using Bitquery APIs, streams, and Kafka. ## Get the Top Trading Pairs The query will fetch you the Top Trading Pairs in desceneding order of the total number of trades took place in them just like how DEXScreener shows in its UI. You can check out the video tutorial [here](https://www.youtube.com/watch?v=qAJ2SPFaO-k) to understand the query better. You can find the query [here](https://ide.bitquery.io/List-of-trading-pairs-in-descending-order-of-trxns-in-last-24-hours) ```graphql query TrendingPairs { EVM(dataset: combined, network: eth) { DEXTradeByTokens( orderBy: {descendingByField: "TradeCount"} where: {Block: {Time: {since: "2024-06-05T08:08:00Z"}}, TransactionStatus: {Success: true}} limit: {count: 10} limitBy: {by: Trade_Dex_Pair_SmartContract, count: 1} ) { TradeCount: count Trade { Dex { SmartContract ProtocolName ProtocolFamily Pair { SmartContract } } Currency { Symbol SmartContract } Side { Currency { Symbol SmartContract } } } } } } ``` ## Get Trade Transactions for a particular pair in realtime The query will subscribe you to real-time trade transactions for a pair, providing a continuous stream of data as new trades are processed and recorded. You can find the query [here](https://ide.bitquery.io/Get-pair-trades-data-just-like-dexcsreener) ```graphql subscription{ EVM(network: eth) { DEXTradeByTokens( orderBy: {ascending: Block_Time} where: {Trade: {Currency: {SmartContract: {is: "0x382ea807A61a418479318Efd96F1EFbC5c1F2C21"}}, Side: {Currency: {SmartContract: {is: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"}}}}} ) { Block{ Time } Trade { Amount Currency { Symbol } PriceInUSD Dex { ProtocolName SmartContract } Side { Amount AmountInUSD Currency { Symbol } Buyer Seller } Buyer Seller } Transaction { Maker: From Hash Type } } } } ``` ## Get Price of a Token This query will give you the latest Price of a specified token using Trading API. Here is the [saved query link](https://ide.bitquery.io/token-usd-price-using-trading-api) ```graphql query MyQuery { Trading { Pairs( where: {Token: {Id: {is: "bid:eth:0xa12cc123ba206d4031d1c7f6223d1c2ec249f4f3"}}, Interval: {Time: {Duration: {eq: 1}}}, Price: {IsQuotedInUsd: true}} limit: {count: 10} orderBy: {descending: Interval_Time_Start} ) { Token { Name Address Id NetworkBid } Price { Average { Mean Estimate ExponentialMoving SimpleMoving WeightedSimpleMoving } Ohlc { Open High Low Close } } } } } ``` ## Get Liquidity of a specific pair by using its Pair Address The below query finds the liquidity of a pool using the pool address `0xc2eaB7d33d3cB97692eCB231A5D0e4A649Cb539d`. With this query we can get balance of the pool tokens. And to get the USD Liquidity you can multiply the balances of both the tokens to their respective USD prices and then sum it up. ```graphql query MyQuery { EVM(dataset: archive, network: eth) { Balances( where: {Balance: {Address: {is: "0xc2eaB7d33d3cB97692eCB231A5D0e4A649Cb539d"}}, Currency: {SmartContract: {in: ["0xaaeE1A9723aaDB7afA2810263653A34bA2C21C7a","0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"]}}} orderBy: { descending: Balance_Amount } ) { Currency { Name } Balance { Amount } } } } ``` ## Get the Buys, Sells, Buy Volume, Sell Volume and Makers The query will fetch you the buys, sells, buy volume, sell volume and also the number of makers for a particular token just like how DEXScreener shows in its UI. We are getting these trade metrics for this particular pool address `0x842293fa6ee0642bf61ebf8310e7e546039ba7f4`. You can find the query [here](https://ide.bitquery.io/Buys-Sells-BuyVolume-SellVolume-Makers-TotalTradedVolume-PriceinUSD-for-a-eth-pair#) ```graphql query MyQuery($network: evm_network, $token: String,$pairAddress: String , $min5_timestamp: DateTime, $hr1_timestamp: DateTime) { EVM(dataset: realtime, network: $network) { DEXTradeByTokens( where: {TransactionStatus: {Success: true}, Trade: {Currency: {SmartContract: {is: $token}}, Dex: {SmartContract: {is: $pairAddress}}}, Block: {Time: {since: $hr1_timestamp}}} ) { Trade { Currency { Name SmartContract Symbol } startPrice: PriceInUSD(minimum: Block_Time) Price_at_min5: PriceInUSD( minimum: Block_Time if: {Block: {Time: {after: $min5_timestamp}}} ) current_price: PriceInUSD(maximum: Block_Time) Dex { ProtocolName ProtocolFamily SmartContract } Side { Currency { Symbol Name SmartContract } } } makers: count(distinct: Transaction_From) makers_5min: count( distinct: Transaction_From if: {Block: {Time: {after: $min5_timestamp}}} ) buyers: count( distinct: Transaction_From if: {Trade: {Side: {Type: {is: sell}}}} ) buyers_5min: count( distinct: Transaction_From if: {Trade: {Side: {Type: {is: sell}}}, Block: {Time: {after: $min5_timestamp}}} ) sellers: count( distinct: Transaction_From if: {Trade: {Side: {Type: {is: buy}}}} ) sellers_5min: count( distinct: Transaction_From if: {Trade: {Side: {Type: {is: buy}}}, Block: {Time: {after: $min5_timestamp}}} ) trades: count trades_5min: count(if: {Block: {Time: {after: $min5_timestamp}}}) traded_volume: sum(of: Trade_Side_AmountInUSD) traded_volume_5min: sum( of: Trade_Side_AmountInUSD if: {Block: {Time: {after: $min5_timestamp}}} ) buy_volume: sum( of: Trade_Side_AmountInUSD if: {Trade: {Side: {Type: {is: sell}}}} ) buy_volume_5min: sum( of: Trade_Side_AmountInUSD if: {Trade: {Side: {Type: {is: sell}}}, Block: {Time: {after: $min5_timestamp}}} ) sell_volume: sum( of: Trade_Side_AmountInUSD if: {Trade: {Side: {Type: {is: buy}}}} ) sell_volume_5min: sum( of: Trade_Side_AmountInUSD if: {Trade: {Side: {Type: {is: buy}}}, Block: {Time: {after: $min5_timestamp}}} ) buys: count(if: {Trade: {Side: {Type: {is: sell}}}}) buys_5min: count( if: {Trade: {Side: {Type: {is: sell}}}, Block: {Time: {after: $min5_timestamp}}} ) sells: count(if: {Trade: {Side: {Type: {is: buy}}}}) sells_5min: count( if: {Trade: {Side: {Type: {is: buy}}}, Block: {Time: {after: $min5_timestamp}}} ) } } } { "network": "eth", "token": "0x6982508145454Ce325dDbE47a25d4ec3d2311933", "pairAddress": "0xA43fe16908251ee70EF74718545e4FE6C5cCEc9f", "hr1_timestamp": "2024-11-14T03:20:00Z", "min5_timestamp": "2024-11-14T04:15:00Z" } ``` ## Get OHLC Data for a Token Pair This query fetches the Open, High, Low, and Close (OHLC) price data (USD-quoted) for a given token pair across DEXs, using a specified quote token and time interval (in seconds). Specify the base token and quote token contract addresses in the `Token.Id` and `QuoteToken.Id` filters. The `Interval.Time.Duration` field allows you to define the candle interval (e.g., `3600` for 1 hour). The query returns the most recent OHLC data for up to 10 pairs sorted by their interval start time. You can find the query [here](https://ide.bitquery.io/ohlc-of-a-token-pair-1-hour-interval) ```graphql query MyQuery { Trading { Pairs( where: {Token: {Id: {is: "bid:eth:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"}}, QuoteToken: {Id: {is: "bid:eth:0xdac17f958d2ee523a2206206994597c13d831ec7"}}, Interval: {Time: {Duration: {eq: 3600}}}, Price: {IsQuotedInUsd: true}} limit: {count: 10} orderBy: {descending: Interval_Time_Start} ) { Token { Name Address Id NetworkBid } QuoteToken{ Name Address Id NetworkBid } Price { Average { Mean Estimate ExponentialMoving SimpleMoving WeightedSimpleMoving } Ohlc { Open High Low Close } } } } } ``` ## Top Traders of a token This query will fetch you top traders of a token for the selected network. You can test the query [here](https://ide.bitquery.io/top-traders-of-a-token_1). ```graphql query topTraders($network: evm_network, $token: String) { EVM(network: $network) { DEXTradeByTokens( orderBy: {descendingByField: "volumeUsd"} limit: {count: 100} where: {Trade: {Currency: {SmartContract: {is: $token}}}} ) { Trade { Dex { OwnerAddress ProtocolFamily ProtocolName } } bought: sum(of: Trade_Amount, if: {Trade: {Side: {Type: {is: buy}}}}) sold: sum(of: Trade_Amount, if: {Trade: {Side: {Type: {is: sell}}}}) volume: sum(of: Trade_Amount) volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } { "network": "eth", "token": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599" } ``` ## Track newly created pairs on uniswap v3 You can track newly created pairs on uniswap v3 on ethereum mainnet. Open this query on our GraphQL IDE using this [link](https://ide.bitquery.io/Latest-pools-created-Uniswap-v3_9). ```graphql subscription { EVM(network: eth) { Events( orderBy: { descending: Block_Number } limit: { count: 10 } where: { Log: { SmartContract: { is: "0x1f98431c8ad98523631ae4a59f267346ea31f984" } Signature: { Name: { is: "PoolCreated" } } } } ) { Log { Signature { Name Parsed Signature } SmartContract } Transaction { Hash } Block { Date Number } Arguments { Type Value { ... on EVM_ABI_Boolean_Value_Arg { bool } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Integer_Value_Arg { integer } } Name } } } } ``` ## Video Tutorial on How to Get EVM Chains Trades Data just like DEXScreener from Bitquery API ## Video Tutorial on How to Get USD Price of a pool Token and Liquidity of the Pool just like DEXScreener shows ## Video Tutorial on How to Get Buys, Sells, Buy Volume, Sell Volume, and Makers for EVM Chains just like DEXScreener ## Video Tutorial on How to Get Top Trading Pairs for EVM Chains just like DEXScreener --- ## Ethereum EVM Photon API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/evm-photon-api/ Ethereum EVM Photon API: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. Built for traders and analytics teams. # Photon EVM API ## Recommended: Trading API queries (real-time + last ~30 days) ### Live trades with USD price, market cap and supply Streams MEV-filtered trades across all 10 chains — add `Network: {is: "Ethereum"}` inside `Pair.Market` to scope to one chain. Run it [in the IDE](https://ide.bitquery.io/Trading-API-Live-Trades-All-Chains). ```graphql subscription { Trading { Trades { Block { Time } Price PriceInUsd Amounts { Base Quote } AmountsInUsd { Base Quote } Trader { Address } Pair { Token { Symbol Network } QuoteToken { Symbol } Market { Protocol Network } } } } } ``` ### Most accurate token price with 1-minute OHLC (top market) Returns the token's price from its top-volume market via `Ranking: { Position: { eq: 1 } }` — swap the token address and network for your token. Run it [in the IDE](https://ide.bitquery.io/Trading-API-Token-Price-Top-Market-Rank-1). ```graphql { Trading { Pairs( where: { Token: {Address: {is: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}, Network: {is: "Solana"}} Ranking: {Position: {eq: 1}} Interval: {Time: {Duration: {eq: 60}}} Price: {IsQuotedInUsd: true} } limit: {count: 1} orderBy: {descending: Block_Time} ) { Token { Symbol Address } QuoteToken { Symbol } Market { Protocol Address Network } Price { IsQuotedInUsd Ohlc { Open High Low Close } Average { Mean } } Volume { Base Usd } Block { Time } } } } ``` The chain-level queries below remain the right tool for **history older than ~30 days** and per-pool detail. This section will guide you through different APIs which will tell you how to get data like realtime trades, price of a token, buys, sells, sell volume, makers, top holders of a token, liquidity of a pair and many more just like how Photon shows for EVM Chains. ## Get the Top Trading Pairs The query will fetch you the Top Trading Pairs in desceneding order of the total number of trades took place in them just like how Photon shows in its UI. You can check out the video tutorial [here](https://www.youtube.com/watch?v=qAJ2SPFaO-k) to understand the query better. You can find the query [here](https://ide.bitquery.io/List-of-trading-pairs-in-descending-order-of-trxns-in-last-24-hours) ```graphql query TrendingPairs { EVM(dataset: combined, network: eth) { DEXTradeByTokens( orderBy: {descendingByField: "TradeCount"} where: {Block: {Time: {since: "2024-06-05T08:08:00Z"}}, TransactionStatus: {Success: true}} limit: {count: 10} limitBy: {by: Trade_Dex_Pair_SmartContract, count: 1} ) { TradeCount: count Trade { Dex { SmartContract ProtocolName ProtocolFamily Pair { SmartContract } } Currency { Symbol SmartContract } Side { Currency { Symbol SmartContract } } } } } } ``` ## Get Trade Transactions for a particular pair in realtime The query will subscribe you to real-time trade transactions for a pair, providing a continuous stream of data as new trades are processed and recorded. You can find the query [here](https://ide.bitquery.io/Get-pair-trades-data-just-like-dexcsreener) ```graphql subscription{ EVM(network: eth) { DEXTradeByTokens( orderBy: {ascending: Block_Time} where: {Trade: {Currency: {SmartContract: {is: "0x382ea807A61a418479318Efd96F1EFbC5c1F2C21"}}, Side: {Currency: {SmartContract: {is: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"}}}}} ) { Block{ Time } Trade { Amount Currency { Symbol } PriceInUSD Dex { ProtocolName SmartContract } Side { Amount AmountInUSD Currency { Symbol } Buyer Seller } Buyer Seller } Transaction { Maker: From Hash Type } } } } ``` ## Get Price of a Token This query will give you the latest Price of a specified token using DEXTrades API. Here we have calculated the price of a token in USD and also against the sell currency. Here is the [saved query link](https://ide.bitquery.io/Price-of-a-token-in-realtime) ```graphql query MyQuery { EVM(network: eth, dataset: realtime) { DEXTrades( limit: {count: 1} orderBy: {descending: Block_Time} where: {Trade: {Buy: {Currency: {SmartContract: {is: "0xaaeE1A9723aaDB7afA2810263653A34bA2C21C7a"}}}, Sell: {Currency: {SmartContract: {is: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"}}}, Dex: {Pair: {SmartContract: {is: "0xc2eaB7d33d3cB97692eCB231A5D0e4A649Cb539d"}}}}, TransactionStatus: {Success: true}} ) { Trade { Buy { Currency { Symbol } Price_In_USD: PriceInUSD Price_against_sell_currency: Price } Sell { Currency { Symbol } } } } } } ``` ## Get Liquidity of a specific pair by using its Pair Address The below query finds the liquidity of a pool using the pool address `0xc2eaB7d33d3cB97692eCB231A5D0e4A649Cb539d`. With this query we can get balance of the pool tokens. And to get the USD Liquidity you can multiply the balances of both the tokens to their respective USD prices and then sum it up. ```graphql query MyQuery { EVM(dataset: combined, network: eth) { Balances( where: {Balance: {Address: {is: "0xc2eaB7d33d3cB97692eCB231A5D0e4A649Cb539d"}}, Currency: {SmartContract: {in: ["0xaaeE1A9723aaDB7afA2810263653A34bA2C21C7a","0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"]}}} orderBy: { descending: Balance_Amount } ) { Currency { Name } Balance { Amount } } } } ``` ## Get the Buys, Sells, Buy Volume, Sell Volume and Makers The query will fetch you the buys, sells, buy volume, sell volume and also the number of makers for a particular token just like how Photon shows in its UI. We are getting these trade metrics for this particular pool address `0x842293fa6ee0642bf61ebf8310e7e546039ba7f4`. You can find the query [here](https://ide.bitquery.io/Buys-Sells-BuyVolume-SellVolume-Makers-TotalTradedVolume-PriceinUSD-for-a-eth-pair#) ```graphql query MyQuery($network: evm_network, $token: String,$pairAddress: String , $min5_timestamp: DateTime, $hr1_timestamp: DateTime) { EVM(dataset: realtime, network: $network) { DEXTradeByTokens( where: {TransactionStatus: {Success: true}, Trade: {Currency: {SmartContract: {is: $token}}, Dex: {SmartContract: {is: $pairAddress}}}, Block: {Time: {since: $hr1_timestamp}}} ) { Trade { Currency { Name SmartContract Symbol } startPrice: PriceInUSD(minimum: Block_Time) Price_at_min5: PriceInUSD( minimum: Block_Time if: {Block: {Time: {after: $min5_timestamp}}} ) current_price: PriceInUSD(maximum: Block_Time) Dex { ProtocolName ProtocolFamily SmartContract } Side { Currency { Symbol Name SmartContract } } } makers: count(distinct: Transaction_From) makers_5min: count( distinct: Transaction_From if: {Block: {Time: {after: $min5_timestamp}}} ) buyers: count( distinct: Transaction_From if: {Trade: {Side: {Type: {is: sell}}}} ) buyers_5min: count( distinct: Transaction_From if: {Trade: {Side: {Type: {is: sell}}}, Block: {Time: {after: $min5_timestamp}}} ) sellers: count( distinct: Transaction_From if: {Trade: {Side: {Type: {is: buy}}}} ) sellers_5min: count( distinct: Transaction_From if: {Trade: {Side: {Type: {is: buy}}}, Block: {Time: {after: $min5_timestamp}}} ) trades: count trades_5min: count(if: {Block: {Time: {after: $min5_timestamp}}}) traded_volume: sum(of: Trade_Side_AmountInUSD) traded_volume_5min: sum( of: Trade_Side_AmountInUSD if: {Block: {Time: {after: $min5_timestamp}}} ) buy_volume: sum( of: Trade_Side_AmountInUSD if: {Trade: {Side: {Type: {is: sell}}}} ) buy_volume_5min: sum( of: Trade_Side_AmountInUSD if: {Trade: {Side: {Type: {is: sell}}}, Block: {Time: {after: $min5_timestamp}}} ) sell_volume: sum( of: Trade_Side_AmountInUSD if: {Trade: {Side: {Type: {is: buy}}}} ) sell_volume_5min: sum( of: Trade_Side_AmountInUSD if: {Trade: {Side: {Type: {is: buy}}}, Block: {Time: {after: $min5_timestamp}}} ) buys: count(if: {Trade: {Side: {Type: {is: sell}}}}) buys_5min: count( if: {Trade: {Side: {Type: {is: sell}}}, Block: {Time: {after: $min5_timestamp}}} ) sells: count(if: {Trade: {Side: {Type: {is: buy}}}}) sells_5min: count( if: {Trade: {Side: {Type: {is: buy}}}, Block: {Time: {after: $min5_timestamp}}} ) } } } { "network": "eth", "token": "0x6982508145454Ce325dDbE47a25d4ec3d2311933", "pairAddress": "0xA43fe16908251ee70EF74718545e4FE6C5cCEc9f", "hr1_timestamp": "2024-11-14T03:20:00Z", "min5_timestamp": "2024-11-14T04:15:00Z" } ``` ## Get OHLC of a token pair This query retrieves the Open, High, Low, and Close (OHLC) prices in USD for a specific token traded on DEXes over a defined time period and interval. You can use the `quoteCurrency` to input the contract address of the currency used for quoting the token prices. You can find the query [here](https://ide.bitquery.io/WETH-USDT-OHLC-on-Ethereum_1) ```graphql { EVM(network: eth, dataset: archive) { DEXTradeByTokens( orderBy: {descendingByField: "Block_testfield"} where: {Trade: {Currency: {SmartContract: {is: "0xdac17f958d2ee523a2206206994597c13d831ec7"}}, Side: {Currency: {SmartContract: {is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"}}, Type: {is: buy}}, PriceAsymmetry: {lt: 0.1}}} limit: {count: 10} ) { Block { testfield: Time(interval: {in: hours, count: 1}) } volume: sum(of: Trade_Amount) Trade { high: Price(maximum: Trade_Price) low: Price(minimum: Trade_Price) open: Price(minimum: Block_Number) close: Price(maximum: Block_Number) } count } } } ``` ## Top Traders of a token This query will fetch you top traders of a token for the selected network. You can test the query [here](https://ide.bitquery.io/top-traders-of-a-token_7). ```graphql query topTraders($network: evm_network, $token: String) { EVM(network: $network) { DEXTradeByTokens( orderBy: {descendingByField: "volumeUsd"} limit: {count: 100} where: {Trade: {Currency: {SmartContract: {is: $token}}}} ) { Trade { Buyer Dex { OwnerAddress ProtocolFamily ProtocolName } } bought: sum(of: Trade_Amount, if: {Trade: {Side: {Type: {is: buy}}}}) sold: sum(of: Trade_Amount, if: {Trade: {Side: {Type: {is: sell}}}}) volume: sum(of: Trade_Amount) volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } { "network": "eth", "token": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599" } ``` ## Track newly created pairs on uniswap v3 You can track newly created pairs on uniswap v3 on ethereum mainnet. Open this query on our GraphQL IDE using this [link](https://ide.bitquery.io/Latest-pools-created-Uniswap-v3_9). ```graphql subscription { EVM(network: eth) { Events( orderBy: { descending: Block_Number } limit: { count: 10 } where: { Log: { SmartContract: { is: "0x1f98431c8ad98523631ae4a59f267346ea31f984" } Signature: { Name: { is: "PoolCreated" } } } } ) { Log { Signature { Name Parsed Signature } SmartContract } Transaction { Hash } Block { Date Number } Arguments { Type Value { ... on EVM_ABI_Boolean_Value_Arg { bool } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Integer_Value_Arg { integer } } Name } } } } ``` --- ## Ethereum Eth Gasprice URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/eth_gasPrice/ eth_gasPrice equivalent on Ethereum: a GraphQL stream that returns the gas price of the latest transaction in WEI as a readable number instead of hex. # eth_gasPrice In this section, we will build a data stream that returns the gas fee of the latest transaction in WEI. Unlike any JSON RPC method like eht_gasPrice that returns the hexadecimal equivalent of an integer representing the current gas price in WEI, this returns the integer value itself. [This](https://ide.bitquery.io/eth_gasPrice_1) is the stream that returns the current gas price in `WEI`. ``` graphql subscription { EVM { Transactions { Transaction { Gas } ChainId } } } ``` The above stream returns the following response. ``` json { "EVM": { "Transactions": [ { "ChainId": "1", "Transaction": { "Gas": "100000" } }, ] } } ``` --- ## Ethereum Eth Getbalance API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/eth-getbalance/ Ethereum Eth Getbalance API: fetch current and historical Ethereum balances with Bitquery GraphQL balance queries. Works with WebSocket live subscriptions. # eth_getBalance Ethereum getBalance is an API endpoint that retrieves the balance for a particular address for any given currency on the Ethereum blockchain. In this section we will see how to create queries that serves as an alternative for the eth_getBalance JSON RPC method and how to customize it to get data we need. ## eth_getBalance for One Address ### Get balance for all currencies [Run in IDE](https://ide.bitquery.io/ethereum-balances-address) ```graphql query { EVM(network: eth, dataset: combined) { Balances( where: { Balance: { Address: { is: "0x21a31ee1afc51d94c2efccaa2092ad1028285549" } } } ) { Currency { Name Symbol SmartContract } Balance { Amount(selectWhere: { gt: "0" }) AmountInUSD } } } } ``` ### Get balance for one currency [Run in IDE](https://ide.bitquery.io/ethereum-balances-native-eth) Returns the balance for native ETH (`SmartContract: "0x"`). ```graphql query { EVM(network: eth, dataset: combined) { Balances( where: { Balance: { Address: { is: "0x21a31ee1afc51d94c2efccaa2092ad1028285549" } } Currency: { SmartContract: { is: "0x" } } } ) { Currency { Name Symbol SmartContract } Balance { Amount(selectWhere: { gt: "0" }) AmountInUSD } } } } ``` ## eth_getBalance for Multiple Addresses Query each address in the `in` list. [Run in IDE](https://ide.bitquery.io/ethereum-balances-multiple-addresses) ```graphql query { EVM(network: eth, dataset: combined) { Balances( where: { Balance: { Address: { in: [ "0xD51a44d3FaE010294C616388b506AcdA1bfAAE46", "0x6d07d7bac25d9e836bbceb3ed5e2a910214de846", "0x354e9fa5c6ee7e6092158a8c1b203ccac932d66d" ] } } } ) { Currency { Name Symbol SmartContract } Balance { Amount(selectWhere: { gt: "0" }) AmountInUSD Address } } } } ``` --- ## Ethereum Eth Getcode URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/eth_getCode/ eth_getCode alternative for Ethereum: fetch a contract's bytecode with a GraphQL query that needs only the address, not a block number. # eth_getCode In this section we will build a query that serves as an alternative to the eth_getCode JSON RPC method. However unlike the method that requires two arameters, namely `address` and `block number`, this API only needs an `address`. The [below](https://ide.bitquery.io/eth_getCode) query serves as the alternative API to the method, with address as `0xc923D39fA2d97fb4B660Fc66DAdB1421605975E0`. ``` graphql { EVM(dataset: archive, network: eth) { creates: Calls( where: { Call: { To: { is: "0xc923D39fA2d97fb4B660Fc66DAdB1421605975E0" }, Create: true } } ) { Call { Output } } } } ``` --- ## Ethereum Eth Getlogs URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/eth_getLogs/ eth_getLogs equivalent on Ethereum: get the latest logs, or filter logs by originating address, by topics, or by block, with GraphQL query examples. # eth_getLogs In this section, we will see how we can use Bitquery APIs as an alternative to the eth_getLogs JSON RPC method and return an array of `Logs` object matching the filter object(*optional). The Logs object consist of the following data. - `removed`: (boolean) true when the log was removed, due to a chain reorganization. false if it's a valid log. - `logIndex`: Log index position in the block. Null when it is a pending log. - `transactionIndex`: Hexadecimal of the transactions index position from which the log created. Null when it is a pending log. - `transactionHash`: 32 bytes. Hash of the transactions from which this log was created. Null when it is a pending log. - `blockHash`: 32 bytes. Hash of the block where this log was in. Null when it is a pending log. - `blockNumber`: Block number where this log was in. Null when it is a pending log. - `address`: 20 bytes. Address from which this log originated. - `data`: Contains one or more 32-bytes non-indexed arguments of the log. - `topics`: An array of 0 to 4 indexed log arguments, each 32 bytes. ## Get Latest Logs [This](https://ide.bitquery.io/eth_getLogs_1) subscription API returns the stream of thelatest logs for the `Ethereum Mainnet`. Now note that there is currently no filter in place. ``` graphql subscription { EVM { Events { Block { Hash Number } Transaction { Hash Index } LogHeader { Address Data Index Removed } Topics { Hash } } } } ``` ## Get Logs with Filteration Now, just like the orignal eth_getLogs method, Bitquery APIs provides the option to filter out the `Logs` based on the following parameeters. - `address`: (optional) Contract address (20 bytes) or a list of addresses from which logs should originate. - `topics`: (optional) Array of 32 bytes DATA topics. Topics are order-dependent. - `blockhash`: (optional) Restricts the logs returned to the single block referenced in the 32-byte hash blockHash. ### Get Logs Originated From an Address [This](https://ide.bitquery.io/eth_getLogs-with-filters) API returns the logs originated from a fixed address, which is `0x7d4a7be025652995364e0e232063abd9e8d65e6e` in this case. Also, unlike the JSON RPC method you can fiter out the `Logs` from multiple addresses using [this](https://ide.bitquery.io/eth_getLogs-with-filters_1) API. ``` graphql { EVM { Events( where: {LogHeader: {Address: {is: "0x7d4a7be025652995364e0e232063abd9e8d65e6e"}}} limit: {count: 10} ) { Block { Hash Number } Transaction { Hash Index } LogHeader { Address Data Index Removed } Topics { Hash } } } } ``` ### Filter Logs on Topics [This](https://ide.bitquery.io/eth_getLogs-with-filters_2) query filters outs the `Logs` based on the `topics`. Also, [this](https://ide.bitquery.io/eth_getLogs-with-filters_3) query filters out the Logs based on multiple `Topics`. ``` graphql { EVM { Events( where: { Topics: { includes: { Hash: { is:"e1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c" } } } } ) { Block { Hash Number } Transaction { Hash Index } LogHeader { Address Data Index Removed } Topics { Hash } } } } ``` ### Get Logs from a Block Using [this](https://ide.bitquery.io/eth_getLogs-with-filters_4) query, you can get the `logs` that belong to a particular `block` by using `blockHash` as a filter. Here `0xa0e1c15b905f4ed6f4e466b2693791ffc6be6ccd3a2a95d403585799ab5fecd9` is the parameter used for filteration. ``` graphql { EVM { Events( where: { Block: { Hash: { is: "0xa0e1c15b905f4ed6f4e466b2693791ffc6be6ccd3a2a95d403585799ab5fecd9" } } } ) { Block { Hash Number } Transaction { Hash Index } LogHeader { Address Data Index Removed } Topics { Hash } } } } ``` --- ## Ethereum Eth Subscribe URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/eth_subscribe/ eth_subscribe alternatives for Ethereum: GraphQL subscriptions for pending transactions, contract logs, and new block headers in real time. # eth_subscribe Ethereum Subscription API allows developers to build websockets that receive real-time notifications about the Ethereum blockchain. In this section we will see how to create subscription for each eth_subscribe JSON RPC method and how to customize it to get data we need. ## eth_subscribe(“pendingTransactions”) To subscribe to incoming pending transactions, use the below subscription. You can run it [here](https://ide.bitquery.io/eth_subscribependingTransactions) ```graphql subscription { EVM(mempool: true) { Transactions { Transaction { CostInUSD Cost Data From Hash To Type ValueInUSD Value Time Index Gas } TransactionStatus { FaultError EndError Success } } } } ``` ## eth_subscribe("logs") You can subscribe to all incoming logs filtered by any of the fields including method signature, tx value,sender , receiver and so on. In the below example we are tracking only logs where the method name is `transfer`. You can run it [here](https://ide.bitquery.io/eth_subscribelogs) ```graphql subscription { EVM(mempool: true) { Events(where: {Log: {Signature: {Name: {is: "Transfer"}}}}) { Log { SmartContract Signature { Name Signature } } Block { Number Hash Time } Transaction { Hash From ValueInUSD Value To Type } LogHeader { Data Address Index Removed } } } } ``` ## eth_subscribe("newBlockHeaders") You can subscribe to new blocks as they arrive in real-time. This includes information about the new block, such as its block number, hash,transaction count and timestamp. ```graphql subscription { EVM { Blocks { Block { Number ParentHash Hash TxCount Time } } } } ``` --- ## Ethereum Events API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/events/events-api/ Ethereum smart contract events: mempool and recent events with logs, AAVE V3, staking rewards, Uniswap liquidity removals, swaps and Chef Fun. # Events API > **Before you start**: Not sure when to use Events vs Transfers vs Calls vs DexTrades? Read our [Mental Model guide](/docs/start/mental-model-transfers-events-calls) to understand which primitive to use for your use case. The Event API gives you access real-time blockchain event data. Events represent changes to the state of a blockchain, such as transactions, token transfers, or contract creations. You can find the **Ethers Library equivalents** for these queries at **[Bitquery Ethers Library Section](/docs/blockchain/Ethereum/ethers-library/debug_traceCall/)**. You can find the **NFT Events Examples** at **[Bitquery NFT API Section](/docs/blockchain/Ethereum/nft/nft-blur-marketplace-api/)**. ## Is it possible to subscribe to smart contract events using Bitquery streams? {#is-it-possible-to-subscribe-to-smart-contract-events-using-bitquery-streams} **Yes.** On **EVM** chains (Ethereum, BSC, Base, and other `EVM(network: …)` networks in the API), Bitquery exposes decoded **contract logs** under the **`Events`** field. Use a GraphQL **`subscription`** (not `query`) with the same `where` filters you would use for historical pulls—typically **`Log`** (signature name, smart contract address, topics) and **`Transaction`**—and deliver it over a **WebSocket** to [`wss://streaming.bitquery.io/graphql`](/docs/subscriptions/websockets/) as in [WebSocket access](/docs/subscriptions/websockets/) and [subscription basics](/docs/subscriptions/subscription/). Filter reference: [GraphQL filters](/docs/graphql/filters/). For **high-throughput or replay**, event-style data is also available via **Kafka** topics; see [streaming overview](/docs/streams/). **Solana** does not use this EVM `Events` shape; for live program activity use **`Solana`** subscriptions (e.g. instructions) as in [Solana instructions](/docs/blockchain/Solana/solana-instructions/). Example: stream logs from a specific contract (here USDT on Ethereum) as they are indexed: ```graphql subscription SmartContractEvents { EVM(network: eth) { Events( where: {Log: {SmartContract: {is: "0xdAC17F958D2ee523a2206206994597C13D831ec7"}}} ) { Log { Signature { Name } SmartContract } Transaction { Hash } } } } ``` More patterns below: **mempool** logs (pending), **recent** events with `query`, and other **subscription** examples on this page. ## Mempool Events on Ethereum This query listens to real-time mempool events on the Ethereum (ETH) blockchain. The query is designed to capture details of transactions, logs, events, and arguments from the Ethereum Virtual Machine (EVM) before they are confirmed in a block. You can run it [here](https://ide.bitquery.io/Mempool-event-stream) ```graphql subscription { EVM(network: eth, mempool: true) { Events { Call { CallPath InternalCalls } Topics { Hash } Receipt { CumulativeGasUsed } Transaction { From To Type } Log { Signature { Name } SmartContract } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` ## Recent Events with Logs on Ethereum This query is used to retrieve recent events' data on the ETH network. You can find the query [here](https://ide.bitquery.io/Recents-Events-and-Logs-on-Ethereum_2). The query returns details on each event include transaction details like hash, sender, call trace and event logs. ```graphql query MyQuery { EVM(dataset: realtime, network: eth) { Events(limit: {count: 10}, orderBy: {descending: Block_Time}) { Block { Number } Call { CallPath InternalCalls } Topics { Hash } Receipt { CumulativeGasUsed } Transaction { From To Type } Log { SmartContract Signature { Name } } Arguments { Value { ... on EVM_ABI_Boolean_Value_Arg { bool } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Integer_Value_Arg { integer } } Name } } } } ``` ## Daily Stats on Calls This query retrieves the date and number of unique event calls for the date. You can find the query [here](https://ide.bitquery.io/Daily-Unique-Call-Count) ```graphql query MyQuery { EVM(dataset: archive, network: bsc) { Events( where: { Block: { Date: { after: "2023-01-10" } } } orderBy: { descendingByField: "count(distinct: Call_Signature_Signature)" } ) { Block { Date } count_unique_calls: count(distinct: Call_Signature_Signature) } } } ``` **Parameters** - `dataset`: This parameter specifies the dataset to use. In this case, the "combined" dataset is being used. - `network`: This parameter specifies the network to query. In this case, the Binance Smart Chain (BSC) network is being queried. - `where`: Filters the results to only include blocks that occurred after a specific date. - `orderBy`: Orders the results in descending order based on the number of unique event call signatures in each block. - `descendingByField`: Specifies that we want to sort the results in descending order. **Returned Data** - `Date`: Returns the date - `count_unique_calls`: Returns the number of unique event calls ### Track all AAVE V3 Events The query below shows latest 10 events emitted by the AAVE V3 contract. The `Log` field in the results will contain information about the event, including its signature, smart contract address, and transaction hash. The `Arguments` field will contain the values of any arguments that were passed to the event. You can find the query [here](https://ide.bitquery.io/All-aave-v3-events-latest) ```graphql { EVM(dataset: realtime, network: eth) { Events( orderBy: {descending: Block_Time} limit: {count: 10} where: {Transaction: {To: {is: "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2"}}} ) { Log { Signature { Name Parsed Signature } SmartContract } Transaction { Hash From } Block { Date Number Hash Time } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } } } } } } ``` ## Staking and Rewards To get Staking-related information, we will be using the "Staked" signature to filter the events and logs. Each event contains information about the block number, transaction details (sender, receiver, hash, and type), log signature, smart contract involved, and specific arguments related to the staking actions, such as user addresses and staked amounts. You can find the query [here](https://ide.bitquery.io/Copy-of-Latest-Token-Stake-Events) ```graphql query MyQuery { EVM(dataset: realtime, network: eth) { Events( limit: {count: 10} orderBy: {descending: Block_Time} where: {Log: {Signature: {Name: {is: "Staked"}}}} ) { Block { Number } Transaction { From To Type Hash } Log { Signature { Name SignatureHash Signature } SmartContract } } } } ``` ## Subscribe to the Same Event Across Multiple Contracts In the below query we listen for a specific event (Approval) across multiple smart contracts on the Ethereum (ETH) network. Run the query [here](https://ide.bitquery.io/Subscribe-to-the-Same-Event-Across-Multiple-Contracts) ```graphql subscription { EVM(network: eth) { Events( where: {Log: {Signature: {Name: {is: "Approval"}}, SmartContract: {in: ["0x943af17c37207c9d7a27d12cb5055542a0b7afa8","0x3b62021a8b9fc78106f964853dc375933ab71a06"]}}} ) { Block { Time Number } Transaction { Hash From To ValueInUSD Value Type } Log { Signature { Name } SmartContract } } } } ``` ## Latest Liquidity Removal on Uniswap This query retrieves the most recent liquidity removal events (Burn events) on Uniswap. It includes details about the transaction, block, log, and arguments. You can run the query [here](https://ide.bitquery.io/uniswap-v2-liquidity-removed) ```graphql { EVM(network: eth, dataset: combined) { Events( limit: {count: 100} where: {Transaction: {To: {is: "0x7a250d5630b4cf539739df2c5dacb4c659f2488d"}}, Log: {Signature: {Name: {in: ["Burn"]}}}} ) { Transaction { Hash From To } Block { Number } Log { Signature { Name } SmartContract } Transaction { From To Type } LogHeader { Address Index } Arguments { Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_Boolean_Value_Arg { bool } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } } Name } } } } ``` ## Subscribe to All Swap Events This subscription provides information on the latest real-time swap events on Ethereum. You can run it [here](https://ide.bitquery.io/all-swap-events) ```graphql subscription { EVM(network: eth) { Events(where: {Log: {Signature: {Name: {in: ["swap", "Swap"]}}}}) { Log { SmartContract Signature { Name } } Transaction { From To ValueInUSD Value Type } Arguments { Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } Name } } } } ``` ## Get All Chef Fun Swaps Chefdotfun, similar to platforms like Pumpfun and Sunpump, is a token creation platform on the Ethereum network. This query retrieves the latest Chefdotfun swap transactions by filtering event logs related to the smart contract. You can run the query [here](https://ide.bitquery.io/Latest-chefdog-swaps) ```graphql query MyQuery { EVM(dataset: combined, network: eth) { Events( where: {Log: {SmartContract: {is: "0x4ba1970f8d2dda96ebfbc466943fb0dfaab18c75"}, Signature: {Name: {in: ["swap","Swap"]}}}} orderBy: {descending: Block_Time} limit: {count: 100} ) { Log { SmartContract Signature { Name } } Transaction { From To ValueInUSD Value Type } Arguments { Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } Name } } } } ``` --- ## Ethereum Fees API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/fees/fees-api/ Ethereum Fees API: analyze Ethereum transaction fees and costs with Bitquery GraphQL queries and streams. See examples in the Bitquery IDE. # Ethereum Fees API ## Get Trades with Transaction fees Get a list of successful DEX trades on EVM along with the transaction fee details for each trade. `SenderFee` and `SenderFeeInUSD` fields in query are the transaction fees in ETH and transaction fees in USD respectively. You can test the query [here](https://ide.bitquery.io/trades-with-the-transaction-fees_1#).
Click to expand GraphQL query ```graphql query MyQuery { EVM { DEXTradeByTokens( where: {TransactionStatus: {Success: true}} ) { Block { Time } Trade { AmountInUSD Amount Buyer Seller Currency { SmartContract Name Symbol } Side { Currency { Symbol SmartContract Name } Seller Buyer AmountInUSD Amount } } Transaction { From To Hash } joinTransactions(join: inner, Transaction_Hash: Transaction_Hash) { Fee { SenderFee SenderFeeInUSD } } } } } ````
## Get Transfers by an address and Transaction fees paid for the transfer Track wallet token transfers and get the fees paid for each by the address. `SenderFee` and `SenderFeeInUSD` fields in query are the transaction fees in ETH and transaction fees in USD respectively. You can test the query [here](https://ide.bitquery.io/binancehot-wallet-transfers-with-transaction-fees).
Click to expand GraphQL query ```graphql query MyQuery { EVM { Transfers( where: {Transaction: {From: {is: "0xF977814e90dA44bFA03b6295A0616a897441aceC"}}} limit: {count: 10} orderBy: {descending: Block_Time} ) { Block { Time } Fee { SenderFee SenderFeeInUSD } Transfer { Currency { Name SmartContract Symbol } Amount AmountInUSD } } } } ```
## Total transaction fees paid by an account Get the total fees (in Eth and USD) paid by a specific EVM account across all transfers. `SenderFee` and `SenderFeeInUSD` fields in query are the transaction fees in ETH and transaction fees in USD respectively. You can test the query [here](https://ide.bitquery.io/total-txn-fees-paid-by-binance-hot-wallet-in-a-day).
Click to expand GraphQL query ```graphql query MyQuery { EVM(dataset: combined, aggregates: yes) { Transfers( where: {Transaction: {From: {is: "0xF977814e90dA44bFA03b6295A0616a897441aceC"}}, TransactionStatus: {Success: true}, Block: {Time: {till: "2025-05-07T00:00:00Z", since: "2025-05-06T00:00:00Z"}}} ){ Total_Transaction_Fees_paid_in_ETH:sum(of:Fee_SenderFee) Total_Transaction_Fees_paid_in_USD:sum(of:Fee_SenderFeeInUSD) } } } ```
## Transaction fees paid by an account for each currency transfers Get total fees paid by a EVM account for transferring each type of token. `SenderFee` and `SenderFeeInUSD` fields in query are the transaction fees in ETH and transaction fees in USD respectively. You can test the query [here](https://ide.bitquery.io/Transaction-fees-paid-by-Binance-Hot-Wallet-aggregated-by-currency).
Click to expand GraphQL query ```graphql query MyQuery { EVM(dataset: combined, aggregates: yes) { Transfers( where: {Transaction: {From: {is: "0xF977814e90dA44bFA03b6295A0616a897441aceC"}}, TransactionStatus: {Success: true}, Block: {Time: {till: "2025-05-07T00:00:00Z", since: "2025-05-06T00:00:00Z"}}} orderBy: {descendingByField: "Total_Transaction_Fees_paid_in_USD"} ) { Transfer { Currency { Name Symbol SmartContract } } Total_Transaction_Fees_paid_in_ETH: sum(of: Fee_SenderFee) Total_Transaction_Fees_paid_in_USD: sum(of: Fee_SenderFeeInUSD) } } } ```
## Video Tutorial | How to get Total Fees paid by a Account on EVM Network ``` --- ## Ethereum Fluid DEX API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/fluid-dex-api/ Ethereum Fluid DEX API: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. Run it in the IDE, then ship in your app. # Fluid DEX API :::tip Need real-time Fluid DEX data or anything from the last ~30 days? For **real-time + last ~30 days**, use the [**Trading cube**](/docs/trading/trading-data-overview) — [`Trading.Trades`](/docs/trading/crypto-trades-api/trades-api) gives you clean, MEV-filtered Fluid DEX swaps with **USD price, market cap, and supply on every row** across **10 chains in one API**. Use this page when you need **historical Fluid DEX data older than ~30 days**, raw per-swap detail, or call / event context. ::: Fluid DEX is a decentralized exchange protocol built on Ethereum and other EVM chains. Bitquery's APIs support tracking Fluid DEX vault positions, events, and contract interactions in real-time and across historical data. You can get data on other EVM chains like Base, Arbitrum, and Polygon by changing the contract address based on the [Fluid contracts deployments](https://github.com/Instadapp/fluid-contracts-public/blob/main/deployments/deployments.md) and the `network` parameter ## New Position Mint on Fluid Vault Factory Track new position mints on the Fluid DEX Vault Factory contract. This query monitors the `NewPositionMinted` event which is emitted when a new position is created on the vault factory. [Run Query](https://ide.bitquery.io/new-position-mints-on-Fluid-DEX-Vault) | [Run Stream](https://ide.bitquery.io/stream-new-position-mints-on-Fluid-DEX-Vault) ```graphql { EVM(dataset: realtime, network: eth) { Events( limit: {count: 20} where: { Log: { Signature: {Name: {is: "NewPositionMinted"}} SmartContract: {is: "0x324c5Dc1fC42c7a4D43d92df1eBA58a54d13Bf2d"} } } ) { Block { Time Number Hash } Receipt { ContractAddress } TransactionStatus { Success } LogHeader { Address Index Data } Transaction { Hash From To } Log { EnterIndex ExitIndex Index LogAfterCallIndex Pc SmartContract Signature { Name Signature } } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` ## Recent Transfers to a Fluid Token Vault Track all recent token transfers to a specific Fluid DEX vault. This query is useful for monitoring deposits and liquidity flows into a particular vault. [Run Query](https://ide.bitquery.io/Recent-Transfers-to-cbBTC-Fluid-Vault) **Example Vault Address:** `0x5dae640956711E11016C1b27CF9968Ba5B4a69CC` (cbBTC Fluid Vault) ```graphql query RecentTransfers { EVM(dataset: realtime, network: eth) { Transfers( where: { Transaction: {To: {is: "0x5dae640956711E11016C1b27CF9968Ba5B4a69CC"}} } orderBy: {descending: Block_Number} limit: {count: 100} ) { Block { Time Number } Transaction { Hash } Transfer { Amount Sender Receiver Currency { Symbol Name SmartContract } } } } } ``` ## All Events on Fluid Vault Factory Contract Get a comprehensive list of all events emitted by the Fluid DEX Vault Factory contract. This query aggregates event counts by signature to identify which events are most frequently emitted, helping you understand the contract's activity patterns. [Run Query](https://ide.bitquery.io/all-events-on-fluid-DEX-VaultFactory) **VaultFactory Address:** `0x324c5Dc1fC42c7a4D43d92df1eBA58a54d13Bf2d` ```graphql { EVM(dataset: archive, network: eth) { Events( limit: {count: 20} where: { Log: { SmartContract: {is: "0x324c5Dc1fC42c7a4D43d92df1eBA58a54d13Bf2d"} } } orderBy: {descendingByField: "txc"} ) { txc: count Log { SmartContract Signature { Name Signature } } } } } ``` --- ## Ethereum Gas Balance Tracker URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-gas-balance-tracker/ Ethereum Gas Balance Tracker: stream Ethereum balance changes with reason codes using Bitquery GraphQL subscriptions. See examples in the Bitquery IDE. # Ethereum Gas Balance Tracker The Ethereum Gas Balance Tracker API provides real-time balance updates related to Gas Fee activities, including transaction fee rewards, monitoring gas fee spent, and other Gas-related balance changes. ## Get Top Gas Fee Collectors [This](https://ide.bitquery.io/top-gas-fee-collectors_1) API endpoint returns the list of top gas fee collectors. We are tracking the Gas Collection Event causing Balance Update by appliying condition on `BalanceChangeReasonCode` to be equal to `5`. ```graphql query TopGasGainers { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 5}}} orderBy: {descendingByField: "gain", descending: Block_Time} limitBy: {by: TokenBalance_Address, count: 1} ) { TokenBalance { Address Currency { Name Symbol SmartContract } PreBalance PostBalance } gain: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) } } } ``` ## Track the Balance after Latest Gas Fee Burn [This](https://ide.bitquery.io/Latest-balance-and-gas-fee-paid-for-an-address_1#) API endpoint returns the Balance and the Gas Fee burnt for a particular address after the latest Gas Fee Burn Event. We are tracking the Gas Burn Event causing Balance Update by appliying condition on `BalanceChangeReasonCode` to be equal to `6`. ```graphql query MyQuery { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 6}, Address: {is: "0x18bb896994283bd9c16aa2072777a97c12f1b290"}}} limit: {count: 1} orderBy: {descending: Block_Time} ) { Block{ Time } TokenBalance { PreBalance PreBalanceInUSD PostBalance PostBalanceInUSD } fee_paid: calculate( expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance" ) fee_paid_usd: calculate( expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD" ) } } } ``` ## Track the Balance after Latest Gas Fee Burn for Multiple Addresses [This](https://ide.bitquery.io/Latest-balance-and-gas-fee-paid-for-multiple-addresses) API endpoint returns the Balance and the Gas Fee burnt for a list of addresses after the latest Gas Fee Burn Event. ```graphql query MyQuery { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 6}, Address: {in: ["0x18bb896994283bd9c16aa2072777a97c12f1b290", "0xdadb0d80178819f2319190d340ce9a924f783711"]}}} limitBy: {by: TokenBalance_Address count: 1} orderBy: {descending: Block_Time} ) { Block{ Time } TokenBalance { PreBalance PreBalanceInUSD PostBalance PostBalanceInUSD } fee_paid: calculate( expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance" ) fee_paid_usd: calculate( expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD" ) } } } ``` ## Monitoring Balance after Latest Gas Fee Burn [This](https://ide.bitquery.io/Monitor-balance-and-gas-fee-paid-for-an-address-using-stream_1) stream returns the Balance and the Gas Fee burnt for a particular address in real time. ```graphql subscription { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 6}, Address: {is: "0x18bb896994283bd9c16aa2072777a97c12f1b290"}}} ) { Block{ Time } TokenBalance { PreBalance PreBalanceInUSD PostBalance PostBalanceInUSD } fee_paid: calculate( expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance" ) fee_paid_usd: calculate( expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD" ) } } } ``` ## Monitoring Balance after Latest Gas Fee Burn for Multiple Addresses [This](https://ide.bitquery.io/Monitor-balance-and-gas-fee-paid-for-multiple-addresses--stream_1) stream returns the Balance and the Gas Fee burnt for a list of addresses in real time. ```graphql query MyQuery { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 6}, Address: {in: ["0x18bb896994283bd9c16aa2072777a97c12f1b290", "0xdadb0d80178819f2319190d340ce9a924f783711"]}}} limitBy: {by: TokenBalance_Address count: 1} orderBy: {descending: Block_Time} ) { Block{ Time } TokenBalance { PreBalance PreBalanceInUSD PostBalance PostBalanceInUSD } fee_paid: calculate( expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance" ) fee_paid_usd: calculate( expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD" ) } } } ``` ## Track the Balance after Latest Gas Return [This](https://ide.bitquery.io/Latest-balance-after-unused-gas-fee-returned--for-an-address#) API endpoint returns the Balance and the Gas Returned for a particular address after the latest Gas Return Event. We are tracking the Gas Return Event causing Balance Update by appliying condition on `BalanceChangeReasonCode` to be equal to `7`. ```graphql query MyQuery { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 7}, Address: {is: "0x18bb896994283bd9c16aa2072777a97c12f1b290"}}} limit: {count: 1} orderBy: {descending: Block_Time} ) { Block{ Time } TokenBalance { PreBalance PreBalanceInUSD PostBalance PostBalanceInUSD } fee_paid: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) fee_paid_usd: calculate( expression: "$TokenBalance_PostBalanceInUSD - $TokenBalance_PreBalanceInUSD" ) } } } ``` ## Track the Balance after Latest Gas Return for Multiple Addresses [This](https://ide.bitquery.io/Latest-balance-after-unused-gas-fee-returned--for-multiple-addresses#) API endpoint returns the Balance and the Gas Returned for a list of addresses after the latest Gas Return Event. ```graphql query MyQuery { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 7}, Address: {in: ["0x18bb896994283bd9c16aa2072777a97c12f1b290", "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97"]}}} limitBy: {by:TokenBalance_Address count: 1} orderBy: {descending: Block_Time} ) { Block{ Time } TokenBalance { PreBalance PreBalanceInUSD PostBalance PostBalanceInUSD } fee_paid: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) fee_paid_usd: calculate( expression: "$TokenBalance_PostBalanceInUSD - $TokenBalance_PreBalanceInUSD" ) } } } ``` ## Monitoring Balance after Latest Gas Return [This](https://ide.bitquery.io/Monitor-balance-after-unused-gas-fee-returned--for-an-address--stream#) stream returns the Balance and the Gas Returned for a particular address in real time. ```graphql subscription { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 7}, Address: {is: "0x18bb896994283bd9c16aa2072777a97c12f1b290"}}} limit: {count: 1} orderBy: {descending: Block_Time} ) { Block{ Time } TokenBalance { PreBalance PreBalanceInUSD PostBalance PostBalanceInUSD } fee_paid: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) fee_paid_usd: calculate( expression: "$TokenBalance_PostBalanceInUSD - $TokenBalance_PreBalanceInUSD" ) } } } ``` ## Monitoring Balance after Latest Gas Return for Multiple Addresses [This](https://ide.bitquery.io/Monitor-balance-after-unused-gas-fee-returned--for-multiple-addresses--stream#) stream returns the Balance and the Gas Returned for a list of addresses in real time. ```graphql subscription { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 7}, Address: {in: ["0x18bb896994283bd9c16aa2072777a97c12f1b290", "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97"]}}} ) { Block{ Time } TokenBalance { PreBalance PreBalanceInUSD PostBalance PostBalanceInUSD } fee_paid: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) fee_paid_usd: calculate( expression: "$TokenBalance_PostBalanceInUSD - $TokenBalance_PreBalanceInUSD" ) } } } ``` --- ## Ethereum Liquidity API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/ethereum-liquidity-api/ Ethereum Liquidity API: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. Great for bots, dashboards, and alerts. # Ethereum Liquidity API In this section we will see how to get Ethereum DEX pool liquidity information using Bitquery API. The liquidity API helps you monitor real-time liquidity changes, track pool reserves, and analyze liquidity depth for token pairs on Ethereum DEX pools. > **Note:** This API also works for other EVM chains such as Base, BSC, and Arbitrum—just change the network parameters in your request. ## Understanding Liquidity and Pool Reserves Liquidity in DEX pools refers to the amount of tokens available for trading. Pool reserves (the balance of each token in the pool) determine the pool's ability to handle trades without significant price impact. Monitoring liquidity changes helps you: - Track when liquidity is added or removed from pools - Monitor pool health and depth - Identify liquidity events that may affect trading - Analyze liquidity patterns across different pools The DEXPoolEvents API provides real-time information about: - Current liquidity reserves for both tokens in the pool - Spot prices for both swap directions - Pool and token pair information - Transaction details for liquidity-changing events For a comprehensive explanation of how DEX pools work, liquidity calculations, and when pool events are emitted, refer to the [DEXPools Cube documentation](/docs/cubes/evm-dexpool/). ## Realtime Liquidity Stream This subscription query returns real-time liquidity data for all DEX pools on Ethereum. You can monitor liquidity changes, pool reserves, and spot prices as trades and liquidity modifications occur across all pools. You can find the query [here](https://ide.bitquery.io/Realtime-Liquidity-Stream_4#) ```graphql subscription MyQuery { EVM(network: eth) { DEXPoolEvents { Block { Time Number } PoolEvent { AtoBPrice BtoAPrice Dex { SmartContract ProtocolName } Liquidity { AmountCurrencyA AmountCurrencyB } Pool { CurrencyA { Name SmartContract Symbol } CurrencyB { Name SmartContract Symbol } PoolId SmartContract } } Transaction { Gas Hash } } } } ``` ## Latest Liquidity Changes of a Specific Pool This query retrieves the latest liquidity events for a specific DEX pool on Ethereum. Use this to check current pool reserves, spot prices, and recent liquidity changes for a particular token pair. You can find the query [here](https://ide.bitquery.io/Latest-Liquidity-Changes-of-a-Specific-Pool_5#) ```graphql query MyQuery { EVM(network: eth) { DEXPoolEvents( limit: { count: 10 } orderBy: { descending: Block_Time } where: { PoolEvent: { Pool: { SmartContract: { is: "0x9c087eb773291e50cf6c6a90ef0f4500e349b903" } } } } ) { Block { Time Number } PoolEvent { AtoBPrice BtoAPrice Dex { SmartContract ProtocolName } Liquidity { AmountCurrencyA AmountCurrencyB } Pool { CurrencyA { Name SmartContract Symbol } CurrencyB { Name SmartContract Symbol } PoolId SmartContract } } Transaction { Gas Hash } } } } ``` ## Get Liquidity of All Pools for a Token This query returns current liquidity across all pools where a token appears as either `CurrencyA` or `CurrencyB`. It is useful when you want a token-wide liquidity view across multiple pools and DEXes. You can find the query [here](https://ide.bitquery.io/liquidiy-of-all-token-pools_1) ```graphql query MyQuery($token: String) { EVM { DEXPoolEvents( where: { TransactionStatus: { Success: true } any: [ { PoolEvent: { Pool: { CurrencyA: { SmartContract: { is: $token } } } } } { PoolEvent: { Pool: { CurrencyB: { SmartContract: { is: $token } } } } } ] } ) { PoolEvent { Dex { SmartContract } Liquidity { AmountCurrencyA(maximum: Block_Time) AmountCurrencyAInUSD(maximum: Block_Time) AmountCurrencyB(maximum: Block_Time) AmountCurrencyBInUSD(maximum: Block_Time) } Pool { CurrencyA { Name Symbol SmartContract } CurrencyB { Name Symbol SmartContract } } } } } } ``` ```json { "token": "0x8eD97a637A790Be1feff5e888d43629dc05408F6" } ``` ## Realtime Liquidity Stream of a Specific Pool This subscription query monitors real-time liquidity changes for a specific DEX pool on Ethereum. Use this to track liquidity events, pool reserves, and spot prices for a particular pool as they occur. You can find the query [here](https://ide.bitquery.io/Realtime-Liquidity-Stream-of-a-Specific-Pool_4#) ```graphql subscription MyQuery { EVM(network: eth) { DEXPoolEvents( where: { PoolEvent: { Pool: { SmartContract: { is: "0x9c087eb773291e50cf6c6a90ef0f4500e349b903" } } } } ) { Block { Time Number } PoolEvent { AtoBPrice BtoAPrice Dex { SmartContract ProtocolName } Liquidity { AmountCurrencyA AmountCurrencyB } Pool { CurrencyA { Name SmartContract Symbol } CurrencyB { Name SmartContract Symbol } PoolId SmartContract } } Transaction { Gas Hash } } } } ``` ## Latest Liquidity Changes of Pools in a Specific DEX Protocol - Uniswap V4 This subscription query monitors real-time liquidity changes for all pools in a specific DEX protocol on Ethereum. Here we have taken example of Uniswap V4. You can find the query [here](https://ide.bitquery.io/Latest-Liquidity-Changes-of-Pools-in-a-Specific-DEX-Protocol---Uniswap-V4_6#) ```graphql subscription MyQuery { EVM(network: ethereum) { DEXPoolEvents( where: { PoolEvent: { Dex: { ProtocolName: { is: "uniswap_v4" } } } } ) { Block { Time Number } PoolEvent { AtoBPrice BtoAPrice Dex { SmartContract ProtocolName } Liquidity { AmountCurrencyA AmountCurrencyB } Pool { CurrencyA { Name SmartContract Symbol } CurrencyB { Name SmartContract Symbol } PoolId SmartContract } } Transaction { Gas Hash } } } } ``` > **Important Note:** In Uniswap V4, all pools' liquidity is stored in the PoolManager contract, so the DEX smart contract address will be the same for all pairs. Use `PoolId` to differentiate between different pools. The `PoolId` field uniquely identifies each pool within the PoolManager. ## Top Liquidity Pools on Ethereum (USDC, WBTC, WETH, USDT) The following GraphQL query retrieves the top 10 most recent DEX pool events on Ethereum where either side of the pool is one of the major tokens: USDC, WBTC, WETH, or USDT. Pools are filtered so that CurrencyA or CurrencyB is in the following contracts: - USDC: `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` - WBTC: `0x2260fac5e5542a773aa44fbcfedf7c193bc2c599` - WETH: `0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2` - USDT: `0xdac17f958d2ee523a2206206994597c13d831ec7` Pools are sorted by latest block time and then by the largest dollar value of liquidity for both A and B sides. Only events from the last 2 minutes are retrieved. You can run and modify this query in the [IDE example](https://ide.bitquery.io/top-liquidity-pools-on-Ethereum). ```graphql query MyQuery { EVM(network: eth) { DEXPoolEvents( limit: { count: 10 } orderBy: [ { descending: Block_Time } { descending: PoolEvent_Liquidity_AmountCurrencyAInUSD } { descending: PoolEvent_Liquidity_AmountCurrencyBInUSD } ] where: { any: [ { PoolEvent: { Pool: { CurrencyA: { SmartContract: { in: [ "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599" "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" "0xdac17f958d2ee523a2206206994597c13d831ec7" ] } } } } } { PoolEvent: { Pool: { CurrencyB: { SmartContract: { in: [ "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599" "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" "0xdac17f958d2ee523a2206206994597c13d831ec7" ] } } } } } ] Block: { Time: { since_relative: { minutes_ago: 2 } } } } ) { Block { Time Number } PoolEvent { AtoBPrice BtoAPrice Dex { SmartContract ProtocolName } Liquidity { AmountCurrencyA AmountCurrencyAInUSD AmountCurrencyB AmountCurrencyBInUSD } Pool { CurrencyA { Name SmartContract Symbol } CurrencyB { Name SmartContract Symbol } PoolId SmartContract } } Transaction { Gas Hash } } } } ``` ## Top Liquidity Pools of a token on Ethereum The following API query retrieves the top liquidity pools where shiba inu (`0x95ad61b0a150d79219dcf64e1e6cc01f0b64c4ce`) is either token A or token B in the pool on the Base chain. This allows you to identify which pools have the most liquidity for cbBTC, filtered to exclude certain pools if necessary. This query separates results by whether shiba inu is listed as the first token (`CurrencyA`) or the second token (`CurrencyB`) in the DEX pool, returning the 10 pools with the highest liquidity for each category. Exclusions (e.g., pools you want omitted from the results) are specified in the `SmartContract: {notIn: [...]}` filter. To test run, visit the [IDE example](https://ide.bitquery.io/top-liquidity-pools-of-atoken-on-ethereum) or modify the pool filters to target another token as needed. ```graphql query MyQuery { EVM(network: eth) { TokenIsCurrencyA: DEXPoolEvents( limit: { count: 10 } orderBy: { descendingByField: "PoolEvent_Liquidity_AmountCurrencyA_maximum" } where: { PoolEvent: { Pool: { CurrencyA: { SmartContract: { is: "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE" } } SmartContract: { notIn: ["0x000000000004444c5dc75cB358380D2e3dE08A90"] } } } } ) { PoolEvent { Liquidity { AmountCurrencyA(maximum: Block_Time) AmountCurrencyB(maximum: Block_Time) } Pool { PoolId SmartContract CurrencyA { Name Symbol SmartContract } CurrencyB { Name Symbol SmartContract } } } } TokenIsCurrencyB: DEXPoolEvents( limit: { count: 10 } orderBy: { descendingByField: "PoolEvent_Liquidity_AmountCurrencyB_maximum" } where: { PoolEvent: { Pool: { CurrencyB: { SmartContract: { is: "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE" } } SmartContract: { notIn: ["0x000000000004444c5dc75cB358380D2e3dE08A90"] } } } } ) { PoolEvent { Liquidity { AmountCurrencyA(maximum: Block_Time) AmountCurrencyB(maximum: Block_Time) } Pool { PoolId SmartContract CurrencyA { Name Symbol SmartContract } CurrencyB { Name Symbol SmartContract } } } } } } ``` ## Realtime Liquidity Data via Kafka Streams Liquidity data can also be obtained via Kafka streams for lower latency and better reliability. The Kafka topic for Ethereum DEX pools is: **`eth.dexpools.proto`** Kafka streams provide the same liquidity data as GraphQL subscriptions but with several advantages: - Lower latency due to shorter data pipeline - Better reliability with persistent connections - Ability to read from latest offset without gaps - Better scalability with multiple consumers For detailed information on how to connect to Kafka streams, subscribe to topics, and parse messages, refer to the [Kafka Streaming Concepts documentation](/docs/streams/kafka-streaming-concepts/). > **Note:** IDE credentials will not work with Kafka Streams. You need separate Kafka credentials. Please contact sales on our official telegram channel or fill out the [form on our website](https://bitquery.io/forms/api). ## Understanding the Response The `DEXPoolEvents` API response contains the following information: - **`PoolEvent`**: Pool event information - **`Liquidity`**: Current pool reserves - `AmountCurrencyA`: Current balance of CurrencyA in the pool (in raw units) - `AmountCurrencyB`: Current balance of CurrencyB in the pool (in raw units) - **`AtoBPrice`**: Current spot price for swapping CurrencyA to CurrencyB - **`BtoAPrice`**: Current spot price for swapping CurrencyB to CurrencyA - **`Pool`**: Pool information - `SmartContract`: Pool contract address - `PoolId`: Unique pool identifier - `CurrencyA`: First token in the pair (name, symbol, smart contract address) - `CurrencyB`: Second token in the pair (name, symbol, smart contract address) - **`Dex`**: DEX protocol information - `SmartContract`: DEX router/factory contract address - `ProtocolName`: Protocol name (e.g., Uniswap V2, Uniswap V3, Uniswap V4) - **`Block`**: Block information when the liquidity event occurred - `Time`: Timestamp of the block - `Number`: Block number - **`Transaction`**: Transaction information - `Hash`: Transaction hash - `Gas`: Gas used for the transaction For more details on when new pool events are emitted and how liquidity is calculated, see the [DEXPools Cube documentation](/docs/cubes/evm-dexpool/#when-is-a-new-dexpool-record-emitted-in-the-apis--streams). ## Use Cases ### Real-Time Liquidity Monitoring Use the liquidity API to monitor pool reserves in real-time: - Track when large amounts of liquidity are added or removed - Monitor pool health and detect potential liquidity issues - Alert on significant liquidity changes that may affect trading ### Liquidity Depth Analysis Analyze which pools have sufficient liquidity for your needs: - Compare liquidity reserves across different pools - Identify pools with deep liquidity for large trades - Monitor liquidity trends over time ### Trading Applications #### Pre-Trade Liquidity Checks Before executing large trades, check current pool reserves: - Verify sufficient liquidity exists for your trade size - Monitor liquidity changes that may affect execution - Identify optimal pools with best liquidity depth #### Liquidity Event Detection Track liquidity events that may create trading opportunities: - Detect when new liquidity is added to pools - Monitor liquidity removals that may signal pool abandonment - Identify pools experiencing rapid liquidity growth For more advanced use cases, refer to the [DEXPools Cube documentation](/docs/cubes/evm-dexpool/#advanced-use-cases-and-processing-patterns). --- ## Ethereum MEV Balance Tracker URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-mev-balance-tracker/ Ethereum MEV Balance Tracker: stream Ethereum balance changes with reason codes using Bitquery GraphQL subscriptions. See examples in the Bitquery IDE. # Ethereum MEV Balance Tracker The Ethereum MEV (Maximal Extractable Value) Balance Tracker API provides real-time balance updates related to MEV activities, including transaction fee rewards, block builder rewards, and other MEV-related balance changes. ## Track MEV-Boost Relay Transaction Balances Track balance changes for MEV-boost relay addresses to monitor their activity and rewards. This example uses the `BloXroute Max Profit` address. [Run query](https://ide.bitquery.io/BloXroute-Max-Profit-Tx-Balance-Tracker) ```graphql { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { Address: { is: "0xF2f5C73fa04406b1995e397B55c24aB1f3eA726C" } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD Address BalanceChangeReasonCode } Transaction { Hash From To Value ValueInUSD GasPrice Index } } } } ``` ## Track MEV-Related Balance Updates Monitor balance changes related to MEV activities, including transaction fee rewards and block builder rewards. Try the API [here](https://ide.bitquery.io/Track-MEV-Related-Balance-Updates). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } } } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash } } } } ``` **Balance Change Reason Code for MEV:** - **Code 5**: `BalanceIncreaseRewardTransactionFee` - Transaction tip increasing block builder's balance (MEV-related) ## Track MEV Payout Transaction Balances with MEV Reward This query focuses on a block builder address and returns the most recent payouts, including the token metadata, pre/post balances, and USD valuations, so you can quickly see how large each MEV reward was. [Try the API](https://ide.bitquery.io/QuasarBuilder-MEV-Payout-Transaction-Balance) ```graphql { EVM(network: eth) { TransactionBalances( limit: {count: 10} where: {Transaction: {}, TokenBalance: {BalanceChangeReasonCode: {eq: 6}, Address: {is: "0x396343362be2a4da1ce0c1c210945346fb82aa49"}}} orderBy: {descending: Block_Time} ) { Block { Time } TokenBalance { Currency { Symbol HasURI SmartContract } PreBalance PostBalance Address BalanceChangeReasonCode TotalSupplyInUSD TotalSupply TokenOwnership { Owns Id } PostBalanceInUSD } Transaction { Hash MEV_reward: Value ValueInUSD } } } } ``` ## Track Block Builder Rewards Monitor transaction fee rewards received by block builders (MEV extractors): Try the API [here](https://ide.bitquery.io/Track-Block-Builder-Rewards). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } } Block: { Number: { gt: "0" } } } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash GasPrice } } } } ``` ## Filter by MEV Bot or Builder Address Track balance changes for specific MEV bots or block builders: Try the API [here](https://ide.bitquery.io/Filter-by-MEV-Bot-or-Builder-Address). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { Address: { is: "0xMEVBotOrBuilderAddressHere" } BalanceChangeReasonCode: { eq: 5 } } } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash GasPrice } } } } ``` ## Track Large MEV Transactions Monitor large transaction fee rewards that may indicate significant MEV extraction: Try the API [here](https://ide.bitquery.io/Track-Large-MEV-Transactions). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } PostBalanceInUSD: { gt: "1000" } } } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash GasPrice } } } } ``` ## Aggregate MEV Rewards Calculate total MEV rewards for a specific address or time period: Try the API [here](https://ide.bitquery.io/Aggregate-MEV-Rewards). ```graphql { EVM(dataset: archive, network: eth) { TransactionBalances( where: { TokenBalance: { Address: { is: "0xMEVBotOrBuilderAddressHere" } BalanceChangeReasonCode: { eq: 5 } } } ) { TokenBalance { Currency { Symbol } totalRewards: sum(of: TokenBalance_PostBalanceInUSD) totalRewardsETH: sum(of: TokenBalance_PostBalance) rewardCount: count } } } } ``` --- ## Ethereum Mempool API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/mempool/mempool-api/ Watch Ethereum pending transactions before confirmation with Bitquery mempool GraphQL subscriptions, filters, and stream examples. # Mempool API In this section we will look at some examples of how to write mempool queries to extract the necessary data from broadcasted transactions. To read more about how we offer mempool data, read the introduction [here](/docs/subscriptions/mempool-subscriptions/) ## How do I get unconfirmed/pending transactions for an address? Subscribe to **`EVM(mempool: true)`** **`Transactions`** with **`where.any`** on **`Transaction.From`** and **`Transaction.To`** so you see pending txs **to or from** the wallet. Mempool support varies by **`network`**; the example under [Transactions from an Address](#transactions-from-an-address) shows a **from** filter you can extend with `any`. For **BSC**-specific streaming, see [BSC mempool stream](/docs/blockchain/BSC/bsc-mempool-stream/). ## Simulating Pending Transactions The below query retrieves information about in-flight transactions, helping you simulate the most recent state. It is a way to see if they will succeed without sending them on-chain. The `Success` field tells you if your mempool tranaction is successful and `FaultError` and `FaultError` indicate otherwise. You can find query [here](https://ide.bitquery.io/Simulating-Pending-Transactions_1) ```graphql subscription{ EVM(mempool: true) { Transfers{ Log { Index } Transaction { Time Type To Gas From Cost Hash } Transfer { Amount Currency { Name } Type } TransactionStatus { Success FaultError FaultError } Block { Time } } } } ``` ## Get Recommended Fees The Recommended Fees API provides real-time data from the mempool. It returns fields such as block time, block number, transaction hash, transaction cost, sender address, recipient address, base fee, burnt fees, sender fees, priority fees per gas, miner rewards, gas refunds, effective gas prices, and potential savings. You can use it to build applications that require up-to-date information about recommended transaction fees. You can run the query [here](https://ide.bitquery.io/Get-Mempool-Fees) ```graphql { EVM(mempool: true) { Transactions(limit: {count: 100}) { Block { Time Number BaseFee } Transaction { Hash Cost To From } Fee { Burnt SenderFee PriorityFeePerGas MinerReward GasRefund EffectiveGasPrice Savings } } } } ``` ## PairCreated Events This query returns information about transactions that have triggered the `PairCreated` event in the mempool, including the transaction hash, log signature, and argument values. You can run the query [here](https://ide.bitquery.io/PairCreated-in-Mempool) ```graphql subscription { EVM(mempool: true) { Events(where: {Log: {Signature: {Name: {is: "PairCreated"}}}}) { Transaction { Hash } Log{ Signature{ Name } } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` ## Token Trades This subscription provides information about the most recent token trades in the mempool, including the block number and time, transaction details, and trade information such as buyer, seller, price, and currencies involved. You can run the query [here](https://ide.bitquery.io/mempool-token-trades_1) ```graphql subscription { EVM(mempool: true) { buyside: DEXTrades { Block { Number Time } Transaction { From To Hash } Trade { Buy { Amount Buyer Currency { Name Symbol SmartContract } Seller Price } Sell { Amount Buyer Currency { Name SmartContract Symbol } Seller Price } } } } } ``` ## Transfers This subscription returns details about the latest token transfers in the mempool, including the transfer amount, currency name and symbol, sender, receiver, and transfer type. You can run the query [here](https://ide.bitquery.io/mempool-transfers_1) ```graphql subscription { EVM(mempool: true) { Transfers { Transfer { Amount Currency { Name Symbol } Receiver Sender Type } } } } ``` ## Transactions from an Address Mempool Transactions API provides real-time data from the Binance mempool. You can use it to build applications that require up-to-date information about transactions associated with a specific address. The example below retrieves mempool transactions **from** the specified address (Binance / BSC mempool context). To also include pending txs **to** that address, use `where: { any: [ { Transaction: { From: { is: "..." } } }, { Transaction: { To: { is: "..." } } } ] }` in the same subscription shape. Results include block time, block number, hash, cost, and from/to fields where available. You can run the query [here](https://ide.bitquery.io/Binance-Mempool-Transactions_1) ```graphql subscription { EVM(mempool: true) { Transactions( where: {Transaction: {From: {is: "0x21a31ee1afc51d94c2efccaa2092ad1028285549"}}} ) { Block { Time Number } Transaction { Hash Cost To From } } } } ``` ## Balance Updates in Mempool in Real-time You can track balance changes from each transaction in the mempool, even before it is confirmed. The `TransactionBalances` cube returns the balance before and after each change, with `BalanceChangeReasonCode` saying why it changed. ```graphql subscription { EVM(network: eth, mempool: true) { TransactionBalances { Block { Time } TokenBalance { Currency { Name Symbol } Address PreBalance PostBalance BalanceChangeReasonCode } Transaction { Hash } } } } ``` ## V, R, S Signature of Mempool Transactions The following subscription query retrieves real-time mempool transactions and includes key details such as the block time, block number, transaction hash, transaction cost, and the V, R, S components of the transaction signature. You can run it [here](https://ide.bitquery.io/vrs-signature) ```graphql subscription { EVM(network: eth, mempool: true) { Transactions { Block { Time Number } Transaction { Hash Cost } Signature { V S R } } } } ``` --- ## Ethereum Miner Balance Tracker: Block Producer Income After the Merge URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-miner-balance-tracker/ Ethereum has had no miners since the Merge. Track what block producers earn now with Bitquery GraphQL: priority fees per transaction, block and builder. # Ethereum Miner Balance Tracker: Block Producer Income After the Merge Ethereum stopped mining at the Merge in September 2022. The mining codes stay in the balance schema, 1 for an uncle reward and 2 for a block reward, but the `TransactionBalances` cube covers the recent realtime window only, so on Ethereum they never appear and a filter on them returns nothing. What a block producer earns today shows up under other codes: - **Priority fees**, reason code 5, credited to the block's fee recipient for each transaction. In practice that address is a block builder, since most blocks are built through MEV-Boost. - **Consensus-layer rewards**, which reach validators through consensus-layer withdrawals. Withdrawals are not transactions, so this cube does not record them; reason code 3 exists in the schema for them but returns no rows in live data. The [validator balance tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-validator-balance-tracker) covers what can be tracked on the execution layer. - **Builder payments to the proposer**, ordinary transfers in the last transaction of a block, covered by the [MEV balance tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-mev-balance-tracker). This page tracks the first of these. Every example runs in the [IDE](https://ide.bitquery.io) on a free account. The example builder is Titan Builder, `0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97`; the query under "Who collected fees" lists the others. ## Stream fee credits as they happen Each message is one transaction's priority fee. `tip` is the balance after minus the balance before, in ETH. Saved stream [here](https://ide.bitquery.io/Track-Transaction-Fee-Rewards). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } } } ) { Block { Number Time } TokenBalance { Address PreBalance PostBalance Currency { Symbol } } Transaction { Hash From } tip: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) } } } ``` ## Largest tips in the last ten minutes Sort on the computed field. `calculate` only sees fields that are selected, so `PreBalance` and `PostBalance` stay in the query. Saved query [here](https://ide.bitquery.io/Track-Block-Mining-Rewards). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 20 } orderBy: { descendingByField: "tip" } where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } } Block: { Time: { since_relative: { minutes_ago: 10 } } } } ) { Block { Number Time } TokenBalance { Address PreBalance PostBalance } Transaction { Hash From } tip: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) } } } ``` ## One builder's income per block Group by block for one address. The balance before the first credit and after the last credit in the block bracket the block's fee income, so `end` minus `start` is what the builder collected in that block, and `count` is the number of transactions that paid. Saved query [here](https://ide.bitquery.io/Filter-by-Miner-Address). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 20 } orderBy: { descending: Block_Number } where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } Address: { is: "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97" } } Block: { Time: { since_relative: { minutes_ago: 30 } } } } ) { Block { Number } count start: TokenBalance { PreBalance(minimum: Transaction_Index) } end: TokenBalance { PostBalance(maximum: Transaction_Index) } } } } ``` ## Who collected fees in the last hour Group the code 5 rows by receiving address to see which builders and fee recipients were active, ranked by the number of transactions that paid them. Saved query [here](https://ide.bitquery.io/Track-Miner-Balance-Updates). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 20 } orderBy: { descendingByField: "count" } where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } } Block: { Time: { since_relative: { hours_ago: 1 } } } } ) { TokenBalance { Address } count } } } ``` ## Why the mining codes return nothing Codes 1 and 2 belong to proof-of-work blocks. The cube has no archive dataset on Ethereum, so the pre-Merge era is out of reach and the count below is zero in any window. Saved query [here](https://ide.bitquery.io/Track-Uncle-Block-Rewards). ```graphql { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { in: [1, 2] } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { count } } } ``` ## Video walkthrough ## Related pages - [Ethereum MEV balance tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-mev-balance-tracker) - [Ethereum validator balance tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-validator-balance-tracker) - [Ethereum gas balance tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-gas-balance-tracker) - [Ethereum transaction balance tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-transaction-balance-tracker) --- ## Ethereum NFT API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/nft/nft-api/ Query Ethereum NFT trades, ownership, metadata, and transfers with Bitquery GraphQL APIs, filters, and live streams. See examples in the Bitquery IDE. # NFT API Non-Fungible Tokens (NFTs) are digital assets with unique identification codes that cannot be exchanged for other tokens on a one-to-one basis. NFTs have gained significant popularity in recent years, with the growth of digital art, collectables, and gaming. Bitquery's APIs help you extract and analyze NFT data from various blockchain networks. Below are some examples of NFT queries that can be performed using Bitquery's platform: ## NFT Holders for a project This query retrieves the Ethereum addresses that hold Axie Infinity NFT tokens associated with that smart contract, ranked by their current balance. `Holders` takes a `date` argument for the snapshot day. ```graphql { EVM(network: eth, dataset: combined) { Holders( date: "2026-09-30" limit: { count: 100 } orderBy: { descending: Balance_Amount } where: { Currency: { SmartContract: { is: "0xf5b0a3efb8e8e4c201e2a935f110eaaf3ffecb8d" } } } ) { Holder { Address } Balance { Amount(selectWhere: { gt: "0" }) } } } } ``` **Parameters** - `network`: This specifies the Ethereum network to use. In this case, the network is "eth". - `date`: The snapshot day for the holder list. - `dataset`: This specifies the dataset to use. In this case, the dataset is [combined](/docs/graphql/dataset/combined). - `limit`: This parameter specifies the maximum number of results to return. In this query, the limit is set to 100. - `orderBy`: This parameter specifies the field to order the results by. In this query, the results are ordered in descending order of balance. - `where`: This parameter specifies the conditions to filter the results by. In this query, the filter condition is that the Currency is a Smart Contract with the address "0xf5b0a3efb8e8e4c201e2a935f110eaaf3ffecb8d". ** Returned Data** - `Address`: This field returns the Ethereum wallet address holding the NFT - `Amount`: This field returns the number of tokens the address holds. `selectWhere: { gt: "0" }` drops zero balances. ## All NFTs owned by an address ```graphql { EVM(network: eth, dataset: combined) { Balances( limit: { count: 100 } orderBy: { descending: Balance_Amount } where: { Balance: { Address: { is: "0xaba7161a7fb69c88e16ed9f455ce62b791ee4d03" } } Currency: { Fungible: false } } ) { Currency { Fungible Symbol SmartContract Name HasURI Decimals } Balance { Address Amount(selectWhere: { gt: "0" }) LastChangeTime } } } } ``` **Parameters** - `EVM(network: eth, dataset: combined)`: specifies that we want to query the [combined](/docs/graphql/dataset/combined) dataset of the Ethereum blockchain. - `Balances`: returns the current balance per currency for the address. - `where: { Balance: { Address: { is: "0xaba7161a7fb69c88e16ed9f455ce62b791ee4d03" } }, Currency: { Fungible: false } }`: keeps only non-fungible (NFT) currencies held by this address. **Returned Data** - `Currency`: returns the currency information for the specified smart contract. - `Fungible`: specifies if the currency is fungible or non-fungible. - `Symbol`: returns the symbol for the currency. - `SmartContract`: returns the address of the smart contract for the currency. - `Name`: returns the name of the currency. - `HasURI`: specifies if the currency has a URI. - `Balance`: returns the balance information for the specified address. - `Address`: returns the holder address. - `Amount`: returns the number of NFTs of this collection the address holds. `selectWhere: { gt: "0" }` drops collections it no longer holds. - `LastChangeTime`: returns when the balance last changed. ## Latest NFT trades for given project ```graphql { EVM(network: eth) { DEXTrades( orderBy: {descending: Block_Number} where: {Trade: {Buy: {Currency: {SmartContract: {is: "0x0fcbd68251819928c8f6d182fc04be733fa94170"}}}}} limit: {count: 10} ) { Block { Time } Transaction { Hash } Trade { Dex { ProtocolFamily ProtocolName ProtocolVersion SmartContract } Buy { Price Buyer Ids URIs } Sell { Seller Amount Currency { Symbol SmartContract } } } } } } ``` **Parameters** - `network: eth` specifies that the Ethereum network is being queried. - `dexTrade` retrieves information about trades on DEXs and NFT marketplace for all type of tokens (Fungible or Non-fungible). - `limit: {count: 100}` specifies that up to 100 results will be returned. - `orderBy: {descending: Block_Number}` sorts the results in descending order by the block number (height). - `where` filters the results based on certain criteria. In this case, the results are filtered based on buyCurrency token address "0x0fcbd68251819928c8f6d182fc04be733fa94170" . ## All NFT transfers in a block This query retrieves all NFT token transfers on the Ethereum network within a specific block, and returns information about the block, transfer amount, token currency, sender, and receiver. ```graphql { EVM(dataset: combined, network: eth) { Transfers( orderBy: { descending: Block_Time } where: { Block: { Number: { eq: "16747554" } } Transfer: { Currency: { Fungible: false } } } ) { Block { Hash Number } Transfer { Amount Currency { Name Symbol Native } Sender Receiver } } } } ``` **Parameters**: The EVM Transfers query takes in the following parameters: - `dataset`: This specifies the dataset to use. In this case, the dataset is [combined](/docs/graphql/dataset/combined) - `network`: This specifies the Ethereum network to use. In this case, the network is "eth". - `date`: The snapshot day for the holder list. - `orderBy`: This parameter specifies the field to order the results by. In this query, the results are ordered in descending order of block time. - `where`: This parameter specifies the conditions to filter the results by. In this query, the filter condition is that the transfer is non-fungible and occurred within a specific block identified by the block number. **Returned Data** The EVM Transfers query returns the following fields: - `Hash`: This field returns the hash of the block in which the transfer occurred. - `Number`: This field returns the number of the block in which the transfer occurred. - `Amount`: This field returns the amount transferred. - `Currency.Name`: This field returns the name of the token currency. - `Currency.Symbol`: This field returns the symbol of the token currency. - `Currency.Native`: This field returns a boolean indicating whether the token currency is a native currency of the blockchain. - `Sender`: This field returns the Ethereum address of the sender. - `Receiver`: This field returns the Ethereum address of the receiver. ## All transfers of an NFT This query retrieves the most recent transfers of a specific non-fungible token (NFT) on the Ethereum network. You can find the GraphQL query [here](https://ide.bitquery.io/All-transfers-of-an-NFT) ```graphql query MyQuery { EVM(dataset: combined, network: eth) { Transfers( orderBy: { descending: Block_Time } where: { Transfer: { Currency: { Fungible: false SmartContract: { is: "0x005e6b6776108f4c9e9c5c1259b9554036f8d55e" } } } } limit: { count: 20 } ) { Block { Hash Number } Transfer { Amount Currency { Name Symbol Native } Sender Receiver } } } } ``` **Parameters** - `EVM(dataset: combined, network: eth)` specifies that the query will be executed on the Ethereum blockchain network. - `Transfers` specifies that the query will retrieve transfer transactions on the Ethereum network. - `orderBy: {descending: Block_Time}` specifies that the transfers should be ordered by the time of the block in which they occurred, in descending order (i.e., most recent first). - `where: {Transfer: {Currency: {Fungible: false, SmartContract: {is: "0x005e6b6776108f4c9e9c5c1259b9554036f8d55e"}}}}` specifies the conditions for the transfers to be retrieved. In this case, it specifies that the transfers must involve a non-fungible token (Fungible: false) whose smart contract address is `0x005e6b6776108f4c9e9c5c1259b9554036f8d55e`. - `limit: {count: 20}` specifies that the query should only return the 20 most recent transfers that meet the specified conditions. **Returned Data** - `Block.Hash`: The hash of the block in which the transfer occurred. - `Block.Number`: The number of the block in which the transfer occurred. - `Amount`: The amount of the NFT that was transferred. - `Currency.Name`: The name of the NFT's currency. - `Currency.Symbol`: The symbol of the NFT's currency. - `Currency.Native`: The native type of the NFT's currency. - `Sender`: The address of the sender of the transfer. - `Receiver`: The address of the receiver of the transfer. --- ## Ethereum NFT Balance API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/transaction-balance-tracker/nft-balance-api/ Ethereum NFT Balance API: stream Ethereum balance changes with reason codes using Bitquery GraphQL subscriptions. Works with WebSocket live subscriptions. # Ethereum NFT Balance API The Ethereum NFT Balance API provides real-time balance updates for ERC-721 and ERC-1155 non-fungible tokens on the Ethereum blockchain. Track NFT ownership, token IDs, and ownership status for any address holding NFTs. :::note For NFTs (ERC-721 / ERC-1155), the following fields are available: - **Available**: `PostBalance`, `TokenOwnership` - **Not Provided**: `PreBalance`, `BalanceChangeReasonCode`, `TotalSupply`, `TotalSupplyInUSD`, `PostBalanceInUSD` ::: ## Get Latest NFT Balance for an Address Get the latest NFT balance for a specific address and NFT collection. This query returns the current NFT count and ownership information. Try the API [here](https://ide.bitquery.io/Get-Latest-NFT-Balance-for-an-Address). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 1 } orderBy: { descending: Block_Time } where: { TokenBalance: { Address: { is: "0x2906bF2d33bAd2041B31bd22a728724e23F6e764" } Currency: { SmartContract: { is: "0xbe9371326F91345777b04394448c23E2BFEaa826" } Fungible: false } } } ) { Block { Time Number } TokenBalance { Currency { Symbol Name SmartContract HasURI } PostBalance Address TokenOwnership { Owns Id } } Transaction { Hash } } } } ``` ## Stream NFT Balance Updates in Real Time Subscribe to real-time NFT balance updates for a specific address and collection. This subscription will notify you whenever NFT ownership changes. Try the API [here](https://ide.bitquery.io/Stream-NFT-Balance-Updates-in-Real-Time). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { Address: { is: "0x2906bF2d33bAd2041B31bd22a728724e23F6e764" } Currency: { SmartContract: { is: "0xbe9371326F91345777b04394448c23E2BFEaa826" } Fungible: false } } } ) { Block { Time Number } TokenBalance { Currency { Symbol Name SmartContract HasURI } PostBalance Address TokenOwnership { Owns Id } } Transaction { Hash From To } } } } ``` ## Get All NFT Collections for an Address Retrieve all NFT collections held by a specific address. This query returns balances for all NFT collections the address owns. Try the API [here](https://ide.bitquery.io/Get-All-NFT-Collections-for-an-Address_1). ```graphql { EVM(network: eth) { TransactionBalances( orderBy: { descendingByField: "TokenBalance_PostBalanceInUSD_maximum" } where: { TokenBalance: { Address: { is: "0x2906bF2d33bAd2041B31bd22a728724e23F6e764" } Currency: { Fungible: false } } } ) { TokenBalance { Address Currency { Symbol Name SmartContract Decimals } PostBalance(maximum: Block_Time, selectWhere: { ne: "0" }) PostBalanceInUSD(maximum: Block_Time) Address } } } } ``` ## Get NFT Balances for Multiple Addresses Get NFT balances for multiple addresses in a single query. Useful for portfolio tracking or wallet monitoring applications. Try the API [here](https://ide.bitquery.io/Get-NFT-Balances-for-Multiple-Addresses_1). ```graphql { EVM(network: eth) { TransactionBalances( orderBy: { descendingByField: "TokenBalance_PostBalanceInUSD_maximum" } where: { TokenBalance: { Address: { in: [ "0x2906bF2d33bAd2041B31bd22a728724e23F6e764" "0x3c6559E241f6A2e15a98f3270bc66447e0B6222b" ] } Currency: { Fungible: false } } } ) { TokenBalance { Address Currency { Symbol Name SmartContract Decimals } PostBalance(maximum: Block_Time, selectWhere: { ne: "0" }) PostBalanceInUSD(maximum: Block_Time) Address } } } } ``` ## Get NFT Ownership History Retrieve the NFT ownership history of a specific NFT over a specific time period. This helps track NFT transfers and ownership changes. Try the API [here](https://ide.bitquery.io/Get-NFT-Ownership-History_2). ```graphql { EVM(network: eth) { TransactionBalances( orderBy: { descending: Block_Time } where: { TokenBalance: { PostBalance: { eq: "1" } Currency: { SmartContract: { is: "0xbe9371326F91345777b04394448c23E2BFEaa826" } Fungible: false } TokenOwnership: { Id: { eq: "24010" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Block { Time Number Hash } TokenBalance { Currency { Symbol Name SmartContract HasURI } PostBalance Address TokenOwnership { Owns Id } } Transaction { Hash From To } } } } ``` ## Track specific NFT Balance Changes Monitor NFT transfers for a specific collection across all transactions. This helps track NFT movements and ownership changes. Try the API [here](https://ide.bitquery.io/Track-specific-NFTs-Balance-Changes). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { Currency: { SmartContract: { is: "0xbe9371326F91345777b04394448c23E2BFEaa826" } Fungible: false } } } ) { Block { Time Number } TokenBalance { Currency { Symbol Name SmartContract HasURI } PostBalance Address TokenOwnership { Owns Id } } Transaction { Hash From To } } } } ``` ## Get NFT Owner for Specific Token ID Check the current owner of a specific NFT token ID. This query returns ownership information for a particular token. `0xF9c362CDD6EeBa080dd87845E88512AA0A18c615` is the NFT Contract address and `3042` is the NFT Token ID. Try the API [here](https://ide.bitquery.io/Get-NFT-Owner-for-Specific-Token-ID). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 1 } orderBy: { descending: Block_Time } where: { TokenBalance: { PostBalance: { eq: "1" } Currency: { SmartContract: { is: "0xF9c362CDD6EeBa080dd87845E88512AA0A18c615" } Fungible: false } TokenOwnership: { Id: { eq: "3042" } } } } ) { Block { Time Number } TokenBalance { Currency { Symbol Name SmartContract HasURI } PostBalance Address TokenOwnership { Owns Id } } Transaction { Hash } } } } ``` --- ## Ethereum NFT Calls API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/nft/nft-calls-api/ Ethereum NFT Calls API: track Ethereum NFT trades, ownership, and metadata with Bitquery GraphQL and streams. Keep queries fast with indexed filters. # NFT Calls API This API helps retrieve information about smart contract transactions, including details about the contract function that was called, the input and output parameters, and more. ## Latest Calls for an NFT Here's an example query that retrieve the most recent smart contract calls made on an NFT token contract. ```graphql { EVM { Calls( limit: {count: 10} orderBy: {descending: Block_Time} where: {Call: {To: {is: "0x60e4d786628fea6478f785a6d7e704777c86a7c6"}}} ) { Call { From Gas GasUsed To Value } Transaction { Hash } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** - `orderBy` : Orders the results in descending order based on the Block_Time. - `limit` : Specifies the maximum results to return. In this query, the limit is 10. - `where` : It filters the results to include only calls made to the smart contract with the specified address ("0x60e4d786628fea6478f785a6d7e704777c86a7c6"). **Returned Data** - `Transaction` : The `Hash` field represents the hash of the transaction. - `Call` : Retrieves information about the call - * `From`: The address from which the call was made. * `Gas`: The gas limit specified for the call. * `GasUsed`: The amount of gas used during the call. * `To` : The address of the NFT token contract that received the call. * `Value` : The amount of Ether transferred in the call. - `Arguments { Name Value {....} }` : Retrieves Array of arguments passed in the smart contract call, including their names and values, refer to [arguments](/docs/schema/evm/arguments) for data structure. You can find the graphql query [here](https://ide.bitquery.io/Smart-contract-calls-to-an-nft-contract). --- ## Ethereum NFT Collection API: Token List, Holders and Transfers URL: https://docs.bitquery.io/docs/blockchain/Ethereum/nft/nft-collection-api/ Token list, holders, latest transfers and mints for an Ethereum NFT collection with Bitquery GraphQL, worked on Bored Ape Yacht Club. # Ethereum NFT Collection API: Token List, Holders and Transfers An NFT collection is one contract, and two Bitquery cubes describe it. `Transfers` on the archive dataset holds every mint and transfer of every token id since the contract was deployed, which gives you the full token list with each token's metadata URI. `Holders` holds the current owners, ranked by how many tokens of the collection each address holds, without you aggregating transfers yourself. Both examples use the Bored Ape Yacht Club contract `0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d`; put any ERC-721 or ERC-1155 contract in its place. Every query runs in the [IDE](https://ide.bitquery.io). Queries on the `archive` or `combined` dataset need an archive add-on; the free trial is real-time only. ## All token ids in a collection Group the collection's transfers by token id on the `archive` dataset. Each row is one token, `count` is how many times it has moved, and `offset` pages through the whole collection in id order. For the current owner of one token, take its latest transfer with `Id` in the filter: the `Receiver` is the owner. Saved query [here](https://ide.bitquery.io/Get-all-NFTs-for-a-collection). ```graphql { EVM(dataset: archive, network: eth) { Transfers( where: {Transfer: {Currency: {SmartContract: {is: "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"}}}} limit: {count: 1000, offset: 0} orderBy: {ascendingByField: "Transfer_Id"} ) { Transfer { Id } count } } } ``` ## Holders of a collection, ranked The `Holders` cube returns current balances per address for the collection contract, so the top rows are the largest holders. Add `date: "YYYY-MM-DD"` to see the holder set on a past day. ```graphql { EVM(network: eth) { Holders( limit: { count: 100 } orderBy: { descending: Balance_Amount } where: { Currency: { SmartContract: { is: "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d" } } } ) { Holder { Address } Balance { Amount } } } } ``` See the [Balances and Holders cubes](/docs/cubes/balances-cube) page for more balance and holder query patterns. ## Transfer history and mints Plain rows come from the same filter without the grouping. Add the zero address as `Sender` to keep only mints, `Id` for one token, or a `Block.Time` window for a period; the example lists the first BAYC mints from the collection's launch weeks on the archive dataset. Change `query` to `subscription` and drop the dataset argument to stream new transfers of the collection as they happen. ```graphql { EVM(dataset: archive, network: eth) { Transfers( where: { Transfer: { Currency: { SmartContract: { is: "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d" } } Sender: { is: "0x0000000000000000000000000000000000000000" } } Block: { Time: { since: "2021-04-01T00:00:00Z", till: "2021-05-31T00:00:00Z" } } } limit: { count: 20 } orderBy: { ascending: Block_Time } ) { Block { Time } Transfer { Id Receiver URI } Transaction { Hash } } } } ``` ## Related pages - [Ethereum NFT API](/docs/blockchain/Ethereum/nft/nft-api) - [Balances and Holders cubes](/docs/cubes/balances-cube) - [Transfers cube](/docs/cubes/transfers-cube) - [Optimism NFT API](/docs/blockchain/Optimism/optimism-nft) --- ## Ethereum NFT Metadata API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/nft/nft-metadata-api/ Ethereum NFT Metadata API: track Ethereum NFT trades, ownership, and metadata with Bitquery GraphQL and streams. Built for traders and analytics teams. # NFT Metadata API The NFT Metadata API retrieves the metadata of NFT. ## Get the Metadata of an NFT Let see an example query that retrieves the metadata of an NFT based on its token ID and the smart contract address. It fetches the latest transfer of the NFT by ordering the results based on the block Number in descending order. ```graphql { EVM(dataset: archive, network: eth) { Transfers( where: {Transfer: {Currency: {SmartContract: {is: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D"}}, Id: {eq: "4226"}}} limit: {count: 1, offset: 0} orderBy: {descending: Block_Number} ) { Transfer { Currency { SmartContract Name Decimals Fungible HasURI Symbol } Id URI Data owner: Receiver } } } } ``` **Parameters** - `network` : Specifies the Ethereum network. - `dataset` : Indicates the [combined](/docs/graphql/dataset/combined) dataset to be used. - `orderBy` : Orders the results in descending order based on the Block_Number. - `where` : This parameter specifies the conditions to filter the results by. In this case, the token ID is `4226` and the Currency with the Smart Contract being `0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D`. **Returned Data** - `Currency {....}` : Represent currency details. - `owner` : Specifies the address of the current owner of the NFT. - `URI` : Represents the URL associated with the NFT. You can find the graphql query [here](https://ide.bitquery.io/NFT-metadata_1_1). ## Get the Creator of an NFT The Following query retrieves the Creator of the NFT. ```graphql { EVM(dataset: combined, network: eth) { Calls( limit: {count: 1} orderBy: {descending: Block_Time} where: {Call: {To: {is: "0x23581767a106ae21c074b2276d25e5c3e136a68b"}, Create: true}} ) { Call { creator: From Create } Transaction { Hash } } } } ``` **Parameters** - `orderBy` : Orders the results in descending order based on the Block_Time. - `limit` : Specifies the maximum results to return. In this query, the limit is 1. - `where` : It filters the results to include only calls made to the smart contract with the specified address `0x23581767a106ae21c074b2276d25e5c3e136a68b` and only includes create call. **Returned Data** - `Call`: The `creator: From` field represent the address of the creator. - `Transaction` : Represents hash of the transaction at which this NFT was created. You can find the graphql query [here](https://ide.bitquery.io/Creator_of_an_NFT). --- ## Ethereum NFT Ownership API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/nft/nft-ownership-api/ Ethereum NFT Ownership API: track Ethereum NFT trades, ownership, and metadata with Bitquery GraphQL and streams. Built for traders and analytics teams. # NFT Ownership API The NFT Ownership API can be used to retrieve information about the ownership of a specific NFT ( Non-Fungible Token ) on the supported blockchain. For instance using this we can access the owners of an NFT including their addresses and associated metadata and also we can retrieve a list of the top holders of a particular NFT. ## Get NFT Owners This query fetches the most recent owner of the NFT. It reads the latest transfer of token ID `9996` from the `Transfers` cube; the `Receiver` of that transfer is the current owner. ```graphql query MyQuery { EVM(dataset: combined, network: eth) { Transfers( orderBy: { descending: Block_Time } limit: { count: 1 } where: { Transfer: { Id: { eq: "9996" } Currency: { Fungible: false SmartContract: { is: "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e" } } } } ) { Transfer { Receiver Amount Id Currency { Name SmartContract } } Block { Number Date } } } } ``` **Parameters** - `network` : This specifies the Ethereum network to use. - `dataset` : This specifies the dataset to use. In this case, the dataset is [combined](/docs/graphql/dataset/combined). - `limit` : Specifies the maximum results to return. In this query, the limit is 1. - `orderBy` : Results are in descending order by Block_Time. - `where` : This parameter allows you to filter the results based on specific conditions. In this case, the token ID is "9996" and the Currency is non-fungible, with the Smart Contract being `0x8a90cab2b38dba80c64b7734e58ee1db38b8992e`. **Returned Data** - `Transfer` : `Receiver` is the current owner of the NFT. It also has the amount, token ID and the NFT currency (`Name`, `SmartContract`). - `Block` : Includes the block number and date of the latest transfer. ## Top Holders of an NFT Let's see an example showcasing the retrieval of the top 10 holders for a particular NFT, with their balances. ```graphql query MyQuery { EVM(dataset: combined, network: eth) { Balances( orderBy: { descending: Balance_Amount } limit: { count: 10 } where: { Currency: { SmartContract: { is: "0x7dD4F223D9155F412790D696Fa30923489d4Ad34" } } } ) { Balance { Address Amount(selectWhere: { gt: "0" }) } } } } ``` In this query, you'll need to replace `0x7dD4F223D9155F412790D696Fa30923489d4Ad34` with the contract address of the NFT you'd like to retrieve top holders for. **Parameters** - `dataset` : Specifies combined dataset that includes both realtime & archive data. - `network` : Specifies that the Ethereum network is being queried. - `orderBy` : Orders the results based on the "Balance" field in descending order, meaning the holder with highest balance will appear first. - `limit` : Limits the number of results returned to 10. - `where` : It filters the query results based on the NFT smart contract address `0x7dD4F223D9155F412790D696Fa30923489d4Ad34` . `Currency: {SmartContract: {is: ""}}` specifies the filter for the smart contract address. **Returned Data** - `Balance` : `Address` is the holder of the NFT and `Amount` is how many tokens of the collection it holds. ## Find NFT Creator Address The creator of the NFT can be inferred from the sender of the first transfer. By setting, `Transfers(limit: {count: 1} orderBy: {ascending: Block_Time})` we fetch the earliest (first) transfer record based on block time. You can run the query [here](https://ide.bitquery.io/Fidenza-725) ```graphql query MyQuery { EVM(dataset: archive) { Transfers( limit: {count: 1} orderBy: {ascending: Block_Time} where: {Transfer: {Currency: {SmartContract: {is: "0xa7d8d9ef8D8Ce8992Df33D8b8CF4Aebabd5bD270"}}, Id: {eq: "78000725"}}} ) { Block { Time } Transfer { Amount Currency { Symbol SmartContract ProtocolName Native Name HasURI Fungible DelegatedTo Delegated Decimals } Data Id Receiver Success Type } } } } ``` ## Past (churned) holders of tokens Check past (churned) holders of an NFT collection. The `Balances` cube returns every address that has held the token; `Amount(selectWhere: {le: "0"})` keeps only those whose balance is now zero. `FirstChangeTime` and `LastChangeTime` show when each address started and stopped holding. ```graphql { EVM(dataset: combined) { Balances( limit: {count: 10} where: {Currency: {Fungible: false, SmartContract: {is: "0x364c828ee171616a39897688a831c2499ad972ec"}}} ) { Balance { Address Amount(selectWhere: {le: "0"}) FirstChangeTime LastChangeTime } } } } ``` --- ## Ethereum NFT Trades API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/nft/nft-trades-api/ Ethereum NFT Trades API: track Ethereum NFT trades, ownership, and metadata with Bitquery GraphQL and streams. See examples in the Bitquery IDE. # NFT Trades API The NFT Trades API provides access to diverse NFT DEX trades data on supported blockchain. ## Get Latest NFT Trades of an Address Let's dive into an example query that fetches the most recent NFT trades associated with a specific address. ```graphql query MyQuery { EVM(dataset: combined) { DEXTrades( limit: {offset: 0, count: 10} orderBy: {descendingByField: "Block_Time"} where: {Trade: {Buy: {Buyer: {is: "0x6afdf83501af209d2455e49ed9179c209852a701"}, Currency: {Fungible: false}}}} ) { Trade { Dex { ProtocolName OwnerAddress Delegated DelegatedTo ProtocolName SmartContract } Buy { Price Seller Buyer Currency { Symbol HasURI Name Fungible SmartContract } Ids OrderId URIs } Sell { Price Amount Currency { Name } Buyer Seller } } Transaction { Hash } Block { Time } } } } ``` **Parameters** - `dataset` : Indicates the [combined](/docs/graphql/dataset/combined) dataset to be used. - `orderBy` : Orders the results in descending order based on the Block_Time. - `where` : It filters results based on specified conditions. Here, it selects transfers where the currency is non-fungible and buyer's address is `0x6afdf83501af209d2455e49ed9179c209852a701`. **Returned Data** - `Trade`: It displays the details of the trade, `DEX {}` provides DEX information (protocol name, owner address, delegated status, delegated to address, and smart contract address), `Buy{}` and `sell{}` represents the buy side details ( price, seller, buyer, currency information, NFT IDs, order ID, and URIs ), and the sell side details ( price, amount, currency information, buyer, and seller ) respectively. - `Transaction` : Represents the hash of the transaction associated with the trade. - `Block` - Represents the block time of the trade. You can find the graphql query [here](https://ide.bitquery.io/NFT-trades-of-an-address). ## Get Top Traded NFT Tokens This query retrieves the Top Traded NFT Tokens of the month. ```graphql { EVM(dataset: combined, network: eth) { DEXTrades( orderBy: {descendingByField: "count"} limit: {offset: 0, count: 10} where: {Block: {Date: {since: "2023-05-01", till: "2023-05-28"}}, Trade: {Buy: {Currency: {Fungible: false}}, Sell: {Currency: {Fungible: true}}}} ) { Trade { Buy { Currency { Symbol SmartContract } min_price: Price(minimum: Trade_Buy_Price) max_rice: Price(maximum: Trade_Buy_Price) } Sell { Currency { Symbol SmartContract } } } buy_amount: sum(of: Trade_Buy_Amount) sell_amount: sum(of: Trade_Sell_Amount) count } } } ``` You can find the graphql query [here](https://ide.bitquery.io/Top-traded-NFT-tokens-in-a-month). ## Latest NFT Trades on Opensea The following query retrieves the most latest Opensea trades by tracking the Seaport protocol ( Here seaport_v1.4 means all versions of seaport ) and all transactions sent to Opensea’s seaport contract `0x00000000000000adc04c56bf30ac9d3c0aaf14dc`. ```graphql query MyQuery { EVM(dataset: combined, network: eth) { DEXTrades( where: {Trade: {Dex: {ProtocolName: {in: "seaport_v1.4"}}}, Transaction: {To: {is: "0x00000000000000adc04c56bf30ac9d3c0aaf14dc"}}} limit: {count: 10} orderBy: {descending: Block_Time} ) { Trade { Buy { Currency { Name ProtocolName Symbol Fungible SmartContract } Amount Buyer Ids Price URIs } Sell { Currency { Name ProtocolName Symbol Decimals Fungible SmartContract } Amount Buyer Ids URIs } } Block { Time Number } } } } ``` **Parameters** - `network` : Specifies the Ethereum network. - `dataset` : Indicates the [combined](/docs/graphql/dataset/combined) dataset to be used. - `orderBy` : Orders the results in descending order based on the Block_Time. - `where` : Filters the results based on the specified conditions. In this case, We need to track `Seaport` protocol and all transactions sent to Opensea’s seaport contract `0x00000000000000adc04c56bf30ac9d3c0aaf14dc`. **Returned Data** - `Buy` : Represents the buy side of the trade, including the currency being bought, amount, buyer's address, currency's name, and smart contract address. - `Sell` : Represents the sell side of the trade, including the currency being sold, amount, buyer's address, currency's name, and smart contract address. - `Block` : Provides the block number and timestamp of the trade. You can find the graphql query [here](https://ide.bitquery.io/Latests-OpenSea-Trades). ## Top Traded NFTs on Opensea This query retrieves the Top Traded NFTs on Opensea based on trade count and can also aggregate trading vol, trade count, buyer, seller, and nfts. ```graphql query MyQuery { EVM(dataset: combined, network: eth) { DEXTrades( where: {Trade: {Dex: {ProtocolName: {in: "seaport_v1.4"}}}, Transaction: {To: {is: "0x00000000000000adc04c56bf30ac9d3c0aaf14dc"}}} orderBy: {descendingByField: "count"} limit: {count: 10} ) { tradeVol: sum(of: Trade_Buy_Amount) count buyers: count(distinct: Trade_Buy_Buyer) seller: count(distinct: Trade_Buy_Seller) nfts: count(distinct: Trade_Buy_Ids) Trade { Buy { Currency { Name ProtocolName Symbol Fungible SmartContract } } } } } } ``` **Returned Data** - `tradeVol` : Represents trading volume which is sum of trade buy amount. - `count` : Represents the total number of trades. - `buyers` : count of distinct buyers involved in trades. - `seller` : count of distinct sellers involved in trades. - `nfts` : Represents the count of distinct Ids of NFTs traded. You can find the graphql query [here](https://ide.bitquery.io/Top-Traded-NFTs-on-Opensea). ## Total Buy & Sell of an NFT on Opensea To Retrieve Total Buy & sell of specific NFT on Opensea, we just need to specify the currency contract address in the Buy filter. ```graphql query MyQuery { EVM(dataset: combined, network: eth) { DEXTrades( where: {Trade: {Dex: {ProtocolName: {in: "seaport_v1.4"}}, Buy: {Currency: {Fungible: false}}}, Transaction: {To: {is: "0x00000000000000adc04c56bf30ac9d3c0aaf14dc"}}} orderBy: {descendingByField: "count"} limit: {count: 10} ) { tradeVol: sum(of: Trade_Buy_Amount) count buyer: count(distinct: Trade_Buy_Buyer) seller: count(distinct: Trade_Buy_Seller) nfts: count(distinct: Trade_Buy_Ids) Trade { Buy { Currency { Name ProtocolName Symbol Fungible SmartContract } } } } } } ``` You can find the graphql query [here](https://ide.bitquery.io/Total-buy-sell-of-an-NFT-on-opensea). ## Latest NFT buyer on Opensea This query retrieves the Latest NFT buyer on Opensea. ```graphql query MyQuery { EVM(dataset: combined, network: eth) { DEXTrades( where: {Trade: {Dex: {ProtocolName: {in: "seaport_v1.4"}}, Buy: {Currency: {Fungible: false}}}, Transaction: {To: {is: "0x00000000000000adc04c56bf30ac9d3c0aaf14dc"}}} orderBy: {descendingByField: "count"} limit: {count: 10} ) { count uniq_tx: count(distinct: Transaction_Hash) Block { first_date: Time(minimum: Block_Date) last_date: Time(maximum: Block_Date) } nfts: count(distinct: Trade_Buy_Ids) difffernt_nfts: count(distinct: Trade_Buy_Currency_SmartContract) total_money_paid: sum(of: Trade_Sell_Amount) Trade { Buy { Buyer } } } } } ``` You can find the graphql query [here](https://ide.bitquery.io/Total-buy-sell-of-an-NFT-on-opensea). ## Specific Buyer stats of an NFT on Opensea This query retrieves the Specific Buyer stats of an NFT on Opensea. ```graphql query MyQuery { EVM(dataset: combined, network: eth) { DEXTrades( where: {Trade: {Dex: {ProtocolName: {in: "seaport_v1.4"}}, Buy: {Currency: {SmartContract: {is: "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"}}, Buyer: {is: "0x2f9ecaa66e12b6168996a6b80cda9bb142f80dd0"}}}, Transaction: {To: {is: "0x00000000000000adc04c56bf30ac9d3c0aaf14dc"}}} orderBy: {descendingByField: "count"} limit: {count: 10} ) { count uniq_tx: count(distinct: Transaction_Hash) Block { first_date: Time(minimum: Block_Date) last_date: Time(maximum: Block_Date) } nfts: count(distinct: Trade_Buy_Ids) Trade { Buy { Buyer Currency { Name ProtocolName Symbol Fungible SmartContract } } } } } } ``` You can find the graphql query [here](https://ide.bitquery.io/Top-buyer-of-specific-NFT). ## Latest NFT Trades on Ethereum for Seaport protocol This query retrieves the latest NFT Trades on Ethereum for Seaport v1.4 protocol. Many marketplaces utilize the Seaport protocol, we can add a Smart contract in Trade → Dex → SmartContract to get a specific marketplace for this protocol. ```graphql query MyQuery { EVM { DEXTrades( limit: {offset: 0, count: 10} orderBy: {descendingByField: "Block_Time"} where: {Trade: {Dex: {ProtocolName: {is: "seaport_v1.4"}}}} ) { Trade { Dex { ProtocolName } Buy { Price Seller Buyer Currency { HasURI Name Fungible SmartContract } } Sell { Price Amount Currency { Name } Buyer Seller } } Transaction { Hash } Block { Time } } } } ``` You can find the graphql query [here](https://ide.bitquery.io/latest-NFT-trades-on-Ethereum-network). --- ## Ethereum NFT Transfer API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/nft/nft-transfer-api/ Ethereum NFT Transfer API: monitor Ethereum native and token transfers in real time with Bitquery GraphQL APIs. Copy GraphQL snippets for production apps. # NFT Transfer API The NFT Transfer API provides access to diverse NFT transfer data on supported blockchains and have various use cases. For instance we can retrieve daily transfers, monitor top NFT transfers, track the latest transfers of specific NFTs, and subscribe to real-time transfers for instant updates etc. ## Daily NFT Transfers Here's an example query that retrieves the daily NFT transfers, providing the quantity of transfers occurring on a day-to-day basis within a specified date range. ```graphql { EVM(dataset: combined, network: eth) { Transfers( orderBy: {ascending: Block_Date} where: {Block: {Date: {since: "2023-05-02", till: "2023-05-09"}}, Transfer: {Currency: {Fungible: false}}} ) { Block { Date } count } } } ``` **Parameters** - `network` : Specifies the Ethereum network. - `dataset` : Indicates the [combined](/docs/graphql/dataset/combined) dataset to be used. - `orderBy` : Orders the results in ascending order based on the Block_Date. - `where` : It filters the results based on the specified conditions. In this case, it selects transfers where currency is non-fungible and block date is between "2023-05-02" and "2023-05-09". **Returned Data** - `count` : The count of NFT transfers that occurred within the specified date range. - `Block` : The `date` specifies the date of the block associated with each transfer. You can find the graphql query [here](https://ide.bitquery.io/NFT-Token-Transfers-By-Date). ## Top Transferred NFT on Ethereum This query fetches the most frequently transferred NFTs on the Ethereum Blockchain within the specified date range. ```graphql { EVM(dataset: combined network: eth){ Transfers( orderBy: {descendingByField: "count"} limit: {offset: 10 count: 100} where: { Block: {Date: {since: "2023-05-02" till: "2023-05-09" }} Transfer: {Currency: {Fungible: false}}} ){ Transfer { Currency { Symbol SmartContract } } count senders: uniq(of: Transfer_Sender method: approximate) receivers: uniq(of: Transfer_Receiver method: approximate) ids: uniq(of: Transfer_Id method: approximate) } } } ``` You can find the graphql query [here](https://ide.bitquery.io/Top-transfered-NFT-tokens-in-network). ## Recent Transfers of an NFT Using this query, we can retrieve the most recent transfers of an NFT, ordered by block time. Includes details such as transfer amount, currency information, sender, receiver, transfer type, NFT ID, and more. ```graphql { EVM(dataset: archive, network: eth) { Transfers( where: {Transfer: {Currency: {SmartContract: {is: "0xdba45c28b32f2750bdc3c25d6a0118d8e1c8ca80"}}}} limit: {count: 10} orderBy: {descending: Block_Time} ) { Transfer { Amount Currency { Name Symbol } Receiver Sender Type Id URI Data } } } } ``` You can find the graphql query [here](https://ide.bitquery.io/latest-nft-transfers). ## Latest NFT transfers Involving Specific User This query retrieves the latest transfers of an NFT involving a specific user. The `sent` field retrieves transfers where the user is the sender, while the `recieved` field retrieves transfers where the user is the receiver. ```graphql { EVM(dataset: archive, network: eth) { sent: Transfers( where: {Transfer: {Sender: {is: "0x415bdfed5a7c490e1a89332648d8eb339d4eea69"}}} limit: {count: 10} orderBy: {descending: Block_Time} ) { Transfer { Amount Currency { Name Symbol } Receiver Sender Type Id URI } } recieved: Transfers( where: {Transfer: {Receiver: {is: "0x415bdfed5a7c490e1a89332648d8eb339d4eea69"}}} limit: {count: 10} orderBy: {descending: Block_Time} ) { Transfer { Amount Currency { Name Symbol } Receiver Sender Type Id URI } } } } ``` You can find the graphql query [here](https://ide.bitquery.io/latest-nft-transfers-by-a-user). ## Realtime NFT Transfer Subscriptions Using Streaming APIs, you can subscribe to real-time changes on blockchains. We use a GraphQL subscription,which function similarly to WebSockets. Below example, shows how to subscribe to the latest transfers of the NFT token with the smart contract address `0xdba45c28b32f2750bdc3c25d6a0118d8e1c8ca80`. ```graphql subscription { EVM(network: eth, trigger_on: head) { Transfers( where: {Transfer: {Currency: {SmartContract: {is: "0xdba45c28b32f2750bdc3c25d6a0118d8e1c8ca80"}}}} limit: {count: 10} orderBy: {descending: Block_Time} ) { Transfer { Amount Currency { Name Symbol } Receiver Sender Type Id URI Data } } } } ``` You can find the graphql query [here](https://ide.bitquery.io/Subscription-WebSocket---Latest-NFT-Transfers). --- ## Ethereum Pancakeswap API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/pancakeswap-api/ Ethereum Pancakeswap API: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. Great for bots, dashboards, and alerts. # PancakeSwap API Bitquery provides PancakeSwap data through APIs, Streams and Data Dumps. The below graphQL APIs and Streams are examples of data points you can get with Bitquery. If you have any question on other data points reach out to [support](https://t.me/Bloxy_info) Need zero-latency Pumpfun data? [Read about our Kafka Streams and Contact us for a Trial](/docs/streams/protobuf/chains/EVM-protobuf/). The PancakSwap DEX Data is also available for view as a dashboard [at DEXRABBIT](https://dexrabbit.bitquery.io/eth/dex_market/pancake_swap_v3) ## Latest Trades on PancakeSwap V3 on Ethereum > Note : You can change the network from "eth" to "bsc" to PancakeSwap data on BNB [Run Query ➤](https://ide.bitquery.io/Latest-Trades-on-PancakeSwap-V3-ETH)
Click to expand GraphQL query ```graphql query LatestTrades { EVM(network: eth) { DEXTradeByTokens( orderBy: {descending: Block_Time} limit: {count: 50} where: {TransactionStatus: {Success: true}, Trade: {Dex: {ProtocolName: {is: "pancake_swap_v3"}}}, Block: {Time: {since: "2025-06-17T09:50:13Z"}}} ) { Block { Time } Transaction { Hash } Trade { Dex { OwnerAddress ProtocolFamily ProtocolName } AmountInUSD Price Amount Side { Type Currency { Symbol SmartContract Name } AmountInUSD Amount } Currency { Symbol SmartContract Name } } } } } ```
## Top Traded Pairs on PancakeSwap V3 on ETH [Run Query ➤](https://ide.bitquery.io/Top-token-pairs-on-PancakeSwap-v3)
Click to expand GraphQL query ```graphql query pairs($min_count: String, $market: String, $network: evm_network, $time_10min_ago: DateTime, $time_1h_ago: DateTime, $time_3h_ago: DateTime, $time_ago: DateTime, $eth: String!, $weth: String!, $usdc: String!, $usdt: String!) { EVM(network: $network) { DEXTradeByTokens( where: {TransactionStatus: {Success: true}, Block: {Time: {since: $time_ago}}, any: [{Trade: {Side: {Currency: {SmartContract: {is: $eth}}}}}, {Trade: {Side: {Currency: {SmartContract: {is: $usdt}}}, Currency: {SmartContract: {notIn: [$eth]}}}}, {Trade: {Side: {Currency: {SmartContract: {is: $usdc}}}, Currency: {SmartContract: {notIn: [$eth, $usdt]}}}}, {Trade: {Side: {Currency: {SmartContract: {is: $weth}}}, Currency: {SmartContract: {notIn: [$eth, $usdc, $usdt]}}}}, {Trade: {Side: {Currency: {SmartContract: {notIn: [$usdc, $usdt, $weth, $eth]}}}, Currency: {SmartContract: {notIn: [$usdc, $usdt, $weth, $eth]}}}}], Trade: {Success: true, Dex: {ProtocolName: {is: $market}}}} orderBy: {descendingByField: "usd"} limit: {count: 70} ) { Block { Time(maximum: Block_Time, selectWhere: {after: $time_1h_ago}) } Trade { Currency { Symbol Name SmartContract ProtocolName } Side { Currency { Symbol Name SmartContract ProtocolName } } price_last: PriceInUSD(maximum: Block_Number) price_10min_ago: PriceInUSD( maximum: Block_Number if: {Block: {Time: {before: $time_10min_ago}}} ) price_1h_ago: PriceInUSD( maximum: Block_Number if: {Block: {Time: {before: $time_1h_ago}}} ) price_3h_ago: PriceInUSD( maximum: Block_Number if: {Block: {Time: {before: $time_3h_ago}}} ) } dexes: uniq(of: Trade_Dex_OwnerAddress) amount: sum(of: Trade_Side_Amount) usd: sum(of: Trade_Side_AmountInUSD) sellers: uniq(of: Trade_Seller) buyers: uniq(of: Trade_Buyer) count(selectWhere: {ge: $min_count}) } } } { "network": "eth", "market": "pancake_swap_v3", "eth": "0x", "usdc": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "usdt": "0xdac17f958d2ee523a2206206994597c13d831ec7", "weth": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "min_count": "100", "time_10min_ago": "2025-06-18T09:43:37Z", "time_1h_ago": "2025-06-18T08:53:37Z", "time_3h_ago": "2025-06-18T06:53:37Z", "time_ago": "2025-06-17T09:53:37Z" } ```
## Top Traders on PancakeSwap V3 on ETH [Run Query ➤](https://ide.bitquery.io/Top-Traders-of-a-token-on-PancakeSwap-on-ETH)
Click to expand GraphQL query ```graphql query topTraders { EVM(network: eth) { DEXTradeByTokens( orderBy: {descendingByField: "volumeUsd"} limit: {count: 100} where: {Trade: {Currency: {SmartContract: {is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}}, Dex: {ProtocolName: {is:"pancake_swap_v3"}}}} ) { Trade { Buyer } bought: sum(of: Trade_Amount, if: {Trade: {Side: {Type: {is: buy}}}}) sold: sum(of: Trade_Amount, if: {Trade: {Side: {Type: {is: sell}}}}) volume: sum(of: Trade_Amount) volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } ```
--- ## Ethereum Pepe API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/pepe-api/ PEPE coin on Ethereum: live trades and OHLCV, price on Uniswap V3, whale activity, volume by DEX, top buyers, sellers and holders, and wallet balances. # PEPE Coin API Query real-time and historical on-chain data for [PEPE](https://explorer.bitquery.io/ethereum/token/0x6982508145454ce325ddbe47a25d4ec3d2311933), a popular ERC-20 memecoin on Ethereum. All examples below target PEPE's contract address: `0x6982508145454ce325ddbe47a25d4ec3d2311933`. --- ## Real Time PEPE Trades Stream Every PEPE DEX trade as it is confirmed on-chain in real time using Bitquery subscription. [Run In IDE ➤](https://ide.bitquery.io/pepe-live-trades-stream) ```graphql subscription { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { Currency: { SmartContract: { is: "0x6982508145454ce325ddbe47a25d4ec3d2311933" } } } } ) { Block { Time Number } Transaction { Hash } Trade { AmountInUSD Price Side { Type AmountInUSD Currency { Symbol } } Buyer Seller Dex { ProtocolName SmartContract } Currency { Symbol } } } } } ``` --- ## Real Time PEPE OHLCV Stream Stream live PEPE price data with 1-minute candles, moving averages, and USD volume. > Note: `Volume: { Usd: { gt: 5 } }` is included to filter outlier ticks; the stream already pre-filters outliers—this is an additional check. [Run In IDE ➤](https://ide.bitquery.io/pepe-ohlcv-stream) ```graphql subscription { Trading { Tokens( where: { Token: { Address: { is: "0x6982508145454ce325ddbe47a25d4ec3d2311933" } } Interval: { Time: { Duration: { eq: 60 } } } Volume: { Usd: { gt: 5 } } } ) { Token { Symbol Name Network Address } Block { Time Timestamp } Interval { Time { Start Duration End } } Price { IsQuotedInUsd Ohlc { Open High Low Close } Average { Mean SimpleMoving WeightedSimpleMoving ExponentialMoving } } } } } ``` --- ## Historical PEPE OHLCV (Last 30 Days) Fetch hourly OHLCV candles for the past 30 days. Change `Duration` for different intervals, such as 60 (1 minute) or 300 (5 minutes). [Run In IDE ➤](https://ide.bitquery.io/pepe-historical-ohlcv-30days) ```graphql { Trading { Tokens( where: { Token: { Address: { is: "0x6982508145454ce325ddbe47a25d4ec3d2311933" } } Interval: { Time: { Duration: { eq: 3600 } } } Volume: { Usd: { gt: 5 } } Block: { Time: { since_relative: { days_ago: 30 } } } } limit: { count: 1000 } orderBy: { descending: Interval_Time_Start } ) { Interval { Time { Start End Duration } } Price { IsQuotedInUsd Ohlc { Open High Low Close } Average { Mean ExponentialMoving SimpleMoving } } Volume { Usd } } } } ``` --- ## Monitor Whale Activities for PEPE in Real Time Subscribe to PEPE transfers above 1 billion tokens the moment they hit the chain. [Run In IDE ➤](https://ide.bitquery.io/pepe-whale-transfer-stream) ```graphql subscription { EVM(network: eth) { Transfers( where: { Transfer: { Currency: { SmartContract: { is: "0x6982508145454ce325ddbe47a25d4ec3d2311933" } } Amount: { ge: "1000000000000" } } } ) { Block { Time Number } Transaction { Hash } Transfer { Amount AmountInUSD Sender Receiver Currency { Symbol } } } } } ``` --- ## Latest Trading Volume and Market Cap for PEPE This query provides the latest trade volume for the past one hour along with the latest market cap. [Run In IDE ➤](https://ide.bitquery.io/pepe-volume-marketcap) ```graphql { Trading { Tokens( where: { Token: { Address: { is: "0x6982508145454ce325ddbe47a25d4ec3d2311933" } } Interval: { Time: { Duration: { eq: 3600 } } } } orderBy: {descending: Interval_Time_End} limit: {count: 1} ) { Interval{ Time{ Start End } } Price { Ohlc { Close } } Volume { Usd Base Quote } Supply { TotalSupply MarketCap FullyDilutedValuationUsd } } } } ``` --- ## PEPE Volume by DEX (Last 24 Hours) Break down PEPE trading volume across all DEXs. [Run In IDE ➤](https://ide.bitquery.io/pepe-volume-by-dex) ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { Currency: { SmartContract: { is: "0x6982508145454ce325ddbe47a25d4ec3d2311933" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } orderBy: { descendingByField: "volumeUsd" } ) { Trade { Dex { ProtocolName ProtocolFamily SmartContract } } volumeUsd: sum(of: Trade_AmountInUSD) tradeCount: count(of: Transaction_Hash) } } } ``` --- ## Historical Daily Volume for 30 Days The below query returns the daily trading volume for the past 30 days. [Run In IDE ➤](https://ide.bitquery.io/pepe-daily-volume-30days) ```graphql query MyQuery { Trading { Trades( where: { Block: {Time: {since_relative: {days_ago: 30}}}, Pair: {Token: {Address: {is: "0x6982508145454ce325ddbe47a25d4ec3d2311933"}}} } orderBy: {ascending: Block_Date} ) { Block{ Date } volume: sum(of: AmountsInUsd_Base) trades: count traders: uniq(of: Trader_Address) } } } ``` --- ## Top PEPE Buyers for Last 24 Hours Rank wallets by total USD spent buying PEPE. [Run In IDE ➤](https://ide.bitquery.io/pepe-top-buyers-24h) ```graphql query MyQuery { Trading { Trades( where: { Block: {Time: {since_relative: {hours_ago: 24}}}, Pair: {Token: {Address: {is: "0x6982508145454ce325ddbe47a25d4ec3d2311933"}}}, Side: {is: "Buy"} } limit: {count: 20} orderBy: {descendingByField: "volume"} ) { Trader { Address } volume: sum(of: AmountsInUsd_Base) trades: count } } } ``` --- ## Top PEPE Sellers for Last 24 Hours Rank wallets by total USD value of PEPE sold. [Run In IDE ➤](https://ide.bitquery.io/pepe-top-sellers-24h) ```graphql query MyQuery { Trading { Trades( where: { Block: {Time: {since_relative: {hours_ago: 24}}}, Pair: {Token: {Address: {is: "0x6982508145454ce325ddbe47a25d4ec3d2311933"}}}, Side: {is: "Sell"} } limit: {count: 20} orderBy: {descendingByField: "volume"} ) { Trader { Address } volume: sum(of: AmountsInUsd_Base) trades: count } } } ``` --- ## PEPE Top Holders by Balance [Run In IDE ➤](https://ide.bitquery.io/pepe-top-holders_3) ```graphql query MyQuery { Trading { Trades( where: { Pair: {Token: {Address: {is: "0x6982508145454ce325ddbe47a25d4ec3d2311933"}}}, } limit: {count: 20} orderBy: {descendingByField: "holdings"} ) { Trader { Address } buy_volume: sum(of: AmountsInUsd_Base if: {Side: {is: "Buy"}}) sell_volume: sum(of: AmountsInUsd_Base if: {Side: {is: "Sell"}}) holdings: calculate(expression: "$buy_volume - $sell_volume") trades: count } } } ``` --- --- ## Ethereum Self-Destruct Balance Tracker URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-self-destruct-balance-api/ Ethereum Self-Destruct Balance Tracker: stream Ethereum balance changes with reason codes using Bitquery GraphQL subscriptions. # Ethereum Self-Destruct Balance Tracker The Ethereum Self-Destruct Balance Tracker API provides real-time balance updates for contracts that self-destruct and addresses that receive funds from self-destructed contracts. This API helps you monitor contract destruction events, track ephemeral contracts (like MEV bots), and analyze security incidents. ## What is Self-Destruct? The `selfdestruct` opcode allows a smart contract to permanently remove its bytecode from the blockchain and send its remaining ETH balance to a specified recipient address. Once a contract self-destructs, it can no longer execute code or receive transactions. ### Common Use Cases - **MEV Builder Payments**: Ephemeral contracts created to pay MEV builders/block builders (e.g., `quasarbuilder.eth`) as part of the Proposer-Builder Separation (PBS) infrastructure, then immediately self-destructed - **Ephemeral MEV/Arbitrage Executors**: Contracts created and destroyed within the same transaction to execute atomic profit extraction - **Security Incidents**: Malicious actors destroying contracts - **Emergency Shutdowns**: Contract owners destroying contracts to reclaim funds or retire functionality - **Upgrade Patterns**: Destroying old contract versions during upgrades - **Paymasters/Relayers**: Short-lived helper contracts that clean up after sponsoring gas ## Balance Change Reason Codes The API tracks self-destruct events using specific balance change reason codes: - **Code 12**: `BalanceIncreaseSelfdestruct` - Balance added to the recipient as indicated by a self-destructing account - **Code 13**: `BalanceDecreaseSelfdestruct` - Balance deducted from a contract due to self-destruct - **Code 14**: `BalanceDecreaseSelfdestructBurn` - ETH sent to an already self-destructed account within the same transaction ## Track All Self-Destruct Event Balances Monitor all contract self-destruct event balances in real-time using this GraphQL subscription. [Run Stream](https://ide.bitquery.io/All-Self-Destruct-Event-Balances-Stream) You can also run this as a query by replacing the word `subscription` with `query` ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { in: [12, 13, 14] } } } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash } } } } ``` ## Track Contract Self-Destruct Balance Decrease Monitor contract balance decrease when contracts are self-destructing. [Run Query](https://ide.bitquery.io/Self-Destruct-Balance-Decrease-API) ```graphql { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 13 } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Time Number } TokenBalance { Currency { Symbol SmartContract } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash } } } } ``` ## Track Recipients of Self-Destructed Fund Balances Monitor contract balance increase when contracts are self-destructing. [Run query](https://ide.bitquery.io/Self-Destruct-Balance-Increase-API) ```graphql { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 12 } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Time Number } TokenBalance { Currency { Symbol SmartContract } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash } } } } ``` ## Track Self-Destruct Balance Changes for Specific Address Monitor self-destruct balance changes for a specific contract address using this GraphQL query: Try the API [here](https://ide.bitquery.io/Track-Self-Destruct-Balance-Changes-for-Specific-Address). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { Address: { is: "0x863DF6BFa4469f3ead0bE8f9F2AAE51c91A907b4" } BalanceChangeReasonCode: { in: [12, 13, 14] } } } ) { Block { Time Number } TokenBalance { Currency { Symbol SmartContract } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash } } } } ``` ## Track Large Self-Destruct Transaction Balances Monitor significant self-destruct balance changes (e.g., > $1000 USD) using this subscription: Try the API [here](https://ide.bitquery.io/Track-Large-Self-Destruct-Transaction-Balances). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { in: [12, 13] } PostBalanceInUSD: { gt: "1000" } } } ) { Block { Time Number } TokenBalance { Currency { Symbol SmartContract } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash } } } } ``` ## Track Ephemeral MEV Contract Balance Changes Monitor balance changes for short-lived contracts that are created and destroyed in the same transaction (typical pattern for MEV bots) using this subscription: Try the API [here](https://ide.bitquery.io/Track-Ephemeral-MEV-Contract-Balance-Changes). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 13 } } } ) { Block { Time Number } TokenBalance { Currency { Symbol SmartContract } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash From To } } } } ``` ## Aggregate Self-Destruct Statistics Calculate total ETH destroyed or received from self-destructs using aggregation functions: Try the API [here](https://ide.bitquery.io/Aggregate-Self-Destruct-Statistics). ```graphql { EVM(dataset: realtime, network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { in: [12, 13] } } } ) { TokenBalance { Currency { Symbol SmartContract } } totalDestroyed: sum(of: TokenBalance_PostBalance) destructCount: count } } } ``` ## Self-Destruct Usecase Examples ### 1. MEV Builder Payment (Ephemeral Executor) A common pattern in the MEV ecosystem involves **ephemeral contracts** that are created to pay MEV builders/block builders, then immediately self-destruct. This pattern is part of the **Proposer-Builder Separation (PBS)** infrastructure. Contrack Flow: Deploy → Transfer to MEV builder → Self-destruct **What's happening:** 1. A searcher/bundler deploys a temporary helper contract 2. The contract holds the exact ETH amount owed as a fee/bribe to the MEV builder 3. The contract transfers ETH to the builder 4. The contract immediately self-destructs, cleaning up and leaving minimal trace **Why this pattern:** - **Ephemeral by design** - avoids leaving identifiable payment trails per bundle - **Safety** - one-use contract prevents reuse or exploitation - **Gas efficiency** - minimal runtime deployment is cheaper than maintaining reusable state - **Privacy** - prevents tracking of bundle logic across blocks **API Subscription: Track payments to known MEV builders:** Try the API [here](https://ide.bitquery.io/Track-payments-to-known-MEV-builders). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 12 } Address: { in: [ "0x396343362be2A4dA1cE0C1C210945346fb82Aa49" # Add other known MEV builder addresses ] } } } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash From To } } } } ``` ### 3. Ephemeral MEV/Arbitrage Contracts Many MEV bots and arbitrage executors create contracts that are destroyed within the same transaction. These short-lived contracts are used for: - Atomic multi-swap execution - Flash loan arbitrage - Obfuscation of execution patterns - Cleanup of bytecode footprint **API Query: Track recent ephemeral contract patterns:** Try the API [here](https://ide.bitquery.io/Track-recent-ephemeral-contract-patterns_1). ```graphql { EVM(dataset: realtime, network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 13 } } } limit: { count: 100 } orderBy: { descendingByField: "Block_Time" } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash From To } } } } ``` ## API Use Cases ### Security Monitoring - Track Malicious Self-Destructs Track self-destruct events to identify potential security incidents or malicious contract destruction: Try the API [here](https://ide.bitquery.io/Track-Malicious-Self-Destructs). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 13 } PostBalanceInUSD: { gt: "10000" } } } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash From } } } } ``` ## Notes - **Balance Change Reason Codes 12, 13, and 14** are only available for native currency (ETH) transactions, not for fungible tokens or NFTs - Code 12 indicates funds **received** from a self-destructed contract - Code 13 indicates funds **destroyed** from a self-destructing contract - Code 14 indicates ETH sent to an already self-destructed account within the same transaction - Self-destructed contracts cannot be recovered or interacted with after destruction - The `PreBalance` field shows the balance before the self-destruct, and `PostBalance` shows the balance after (typically 0 for the destroyed contract) --- ## Ethereum Smartcontract Filterby URL: https://docs.bitquery.io/docs/blockchain/Ethereum/calls/smartcontract-filterby/ Ethereum smart contract calls filtered by method signature, opcode or call arguments, with GraphQL query examples for each filter type. # SmartContract API ## Smart Contract Calls by Method Signature This query retrieves the 10 most recent smart contract calls that match a specific function signature (harvest()) on the Binance Smart Chain (BSC) network. It also includes transaction and block data associated with each call. You can find the GraphQL query [here](https://ide.bitquery.io/Calls-by-Method-Signature) ```graphql query MyQuery { EVM(dataset: archive, network: bsc) { Calls( limit: {count: 10} orderBy: {descending: Block_Date} where: {Call: {Signature: {Signature: {is: "harvest()"}}}, Block: {Date: {after: "2023-01-01"}}} ) { Call { LogCount InternalCalls } Transaction { Gas Hash From To Type Index } Block { Date } } } } ``` **Parameters** - `EVM(dataset: archive, network: bsc)`: This parameter specifies the blockchain network and dataset to query. In this case, we are querying the Binance Smart Chain network with the [combined](/docs/graphql/dataset/combined) dataset. - `Calls`: This parameter retrieves the list of smart contract calls that match the specified conditions. - `limit`: \{count: 10\}: This parameter limits the number of results returned to 10. - `orderBy`: \{descending: Block_Date\}: This parameter orders the results in descending order based on the block date of the calls. - `where: {Call: {Signature: {Signature: \{is: "harvest()"\}}}, Block: {Date: \{after: "2023-01-01"\}}}:` This parameter specifies the conditions to filter the smart contract calls. In this case, we filter calls based on the function signature harvest() and a block date after January 1, 2023. **Returned Data** The query returns the following data for each smart contract call: - `Call.LogCount`: The number of log entries emitted by the call. - `Call.InternalCalls`: The list of internal calls made by the call. - `Gas`: The amount of gas used by the transaction. - `Hash`: The hash of the transaction. - `From`: The address of the sender of the transaction. - `To`: The address of the receiver of the transaction. - `Type`: The type of the transaction (e.g., contract creation or message call). - `Index`: The index of the transaction within the block. - `Block.Date`: The date and time when the block was added to the blockchain. ## Smart Contract Calls by Opcode This GraphQL query retrieves information about the latest STATICCALL EVM (Ethereum Virtual Machine) calls on the Binance Smart Chain network. You can find the GraphQL query [here](https://ide.bitquery.io/Smart-Contract-Calls-by-Opcode) ```graphql query MyQuery { EVM(dataset: archive, network: bsc) { Calls( limit: {count: 10} orderBy: {descending: Block_Date} where: {Block: {Date: {after: "2023-01-01"}}, Call: {Opcode: {Name: {is: "STATICCALL"}}}} ) { Call { LogCount InternalCalls Opcode { Name } } Transaction { Gas Hash From To Type Index } Block { Date } } } } ``` **Parameters** - `dataset` parameter specifies the dataset to be queried, which is set to combined. - `network` parameter specifies the network to be queried, which is set to bsc. - `limit` parameter is used to limit the number of results returned and is set to 10. - `orderBy` parameter is used to sort the results by the Block_Date field in descending order. - `where` parameter is used to filter the results based on certain conditions. In this case, the where parameter filters the results to include only STATICCALL calls made after January 1st, 2023. **Returned Data** - `Call`: Returns information about the STATICCALL call, including the number of logs generated, internal calls made, and the name of the opcode used. - `Transaction`: Returns information about the transaction that contains the STATICCALL call, including the gas used, transaction hash, sender address, recipient address, transaction type, and transaction index. - `Block`: Returns the date of the block in which the STATICCALL call was made. ## Smart Contract Calls by Arguments The Array-like structure of [Arguments and Returns](/docs/schema/evm/arguments/) in Smart Contract Calls allows us to insert specific filters, enabling us to effectively narrow down our search. Further we can better understand the details of smart contract interactions in specific contexts. **Example 1** This [query](https://ide.bitquery.io/smart_contract_argument_transfer) demonstrates how we can trace transfer calls to a particular token contract, Matic Token in this case, that are being transferred to a specified wallet address. This is useful for monitoring the inflow of a specific token to a certain wallet. ```graphql query MyQuery { EVM(dataset: archive, network: eth) { Calls( where: {Call: {Signature: {Name: {is: "transfer"}}, To: {is: "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0"}}, Arguments: {includes: {Index: {eq: 0}, Name: {is: "to"}, Type: {is: "address"}, Value: {Address: {is: "0xB53E1f6322629b9435E95AeC13eC34aF9C8fB8bA"}}}}} limit: {count: 10} ) { Arguments { Name Value { ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_Boolean_Value_Arg { bool } } } Returns { Type Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } } } } } } ``` **Parameters** - `dataset` : parameter specifies the combined dataset and `network` parameter specifies the network. - `where` : parameter sets filters on the function calls and arguments. The 'Signature' filter specifies "transfer" function calls made to Matic's token contract. The 'includes' filter under Arguments targets the recipient of the transfer (argument with index 0) with a specific wallet address. **Returned Data** The response includes the first 10 matching calls along with the arguments details and the return values for each call. As usual, you can adjust the filter values and arguments based on your specific use case. **Example 2** Let's consider a scenario where we're interested in tracking large liquidity additions to a specific Uniswap pair, like the ETH/USDT pair. By [this](https://ide.bitquery.io/addLiquidityETH_function) query, We can track calls to the function ` addLiquidityETH ` which is a common function used in Uniswap for adding liquidity to a pool. ```graphql query MyQuery { EVM(dataset: archive, network: eth) { Calls( where: {Transaction: {Hash: {is: "0x60ce9acd0053f20092e7871868afe5187c95ff6d7750ad65a8d4ff99a052c357"}}, Call: {Signature: {Name: {is: "addLiquidityETH"}}}, Arguments: {length: {eq: 6}, includes: [{Index: {eq: 0}, Value: {Address: {is: "0x9cbc0be914e480beee4014e190fdbfc48ed5a4a8"}}}, {Index: {eq: 3}, Value: {BigInteger: {ge: "1000000000000000000"}}}, {Index: {eq: 5}, Value: {BigInteger: {ge: "1690878863"}}}]}} limit: {count: 10} ) { Arguments { Index Name Type Path { Name Index Type } Name Value { ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_Boolean_Value_Arg { bool } } } Call { Signature { Name Signature } } } } } ``` **Parameters** - `dataset` : parameter specifies the combined dataset and `network` parameter specifies the network - `where` : parameter mentions the filters on the Call and Arguments. The 'Signature' filter specifies that we want function calls where the function name is "addLiquidityETH".The 'includes' filter under Arguments specifies that we want the first argument (Index 0) to be the specific token contract address, the third argument (Index 3) 'uint256' value greater than or equal to 1000000000000000000, and the last argument (Index 5) to be a deadline timestamp that is greater than or equal to "1690878863". **Returned Data** The response will contain the first 10 calls that match these filter conditions, along with the details of the arguments and the function signature of each call. --- ## Ethereum Token Balance API: ERC-20 Balances, Supply and Market Cap URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/transaction-balance-tracker/token-balance-api/ ERC-20 balances on Ethereum with Bitquery GraphQL: one token for a wallet, every token a wallet holds, several wallets, history, supply and market cap. # Ethereum Token Balance API: ERC-20 Balances, Supply and Market Cap Every transaction that moves an ERC-20 token writes one row per affected address into the `TransactionBalances` cube, with the balance after the transaction, its USD value, and the token's total supply and on-chain market cap at that moment. That makes the cube a balance API for any wallet that has been active recently: the newest row for a wallet and a token is its current balance. Token rows carry no reason code and no pre-balance; those belong to native ETH rows, covered on the [transaction balance tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-transaction-balance-tracker). The cube holds the recent realtime window only, so a wallet that has not moved a token inside it has no row; for those use the [Balances cube](/docs/cubes/balances-cube), which does not depend on recent activity. Every example runs in the [IDE](https://ide.bitquery.io) on a free account. The worked wallet is a busy one that moves stablecoins and meme tokens all day, `0x9642b23Ed1E01Df1092B92641051881a322F5D4E`, and the worked token is USDT, `0xdac17f958d2ee523a2206206994597c13d831ec7`. ## Balance of one token for one wallet Filter on the wallet and the token contract and take the newest row. Saved query [here](https://ide.bitquery.io/Get-Latest-Token-Balance-for-an-Address). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 1 } orderBy: { descending: Block_Time } where: { TokenBalance: { Address: { is: "0x9642b23Ed1E01Df1092B92641051881a322F5D4E" } Currency: { SmartContract: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } } } } ) { Block { Time } TokenBalance { PostBalance PostBalanceInUSD Currency { Symbol Name SmartContract Decimals } } Transaction { Hash } } } } ``` ## Every token a wallet holds `limitBy` on the token contract keeps the newest row per token, so one query returns the wallet's current balance in every token it moved inside the window, largest USD value first once you sort the rows. Saved query [here](https://ide.bitquery.io/Get-All-Token-Balances-for-an-Address). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 50 } limitBy: { by: TokenBalance_Currency_SmartContract, count: 1 } orderBy: { descending: Block_Time } where: { TokenBalance: { Address: { is: "0x9642b23Ed1E01Df1092B92641051881a322F5D4E" } Currency: { Native: false, Fungible: true } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Block { Time } TokenBalance { PostBalance PostBalanceInUSD Currency { Symbol SmartContract } } } } } ``` Add `PostBalanceInUSD: { gt: "1000000" }` inside `TokenBalance` to keep only positions worth more than a million dollars, which is the saved [minimum balance](https://ide.bitquery.io/Filter-Tokens-by-Minimum-Balance) query. ## Several wallets at once `in` takes a list of addresses; with the token fixed and `limitBy` on the address, the result is the latest USDT balance of each wallet in one call. Saved query [here](https://ide.bitquery.io/Get-Token-Balances-for-Multiple-Addresses). ```graphql { EVM(network: eth) { TransactionBalances( limitBy: { by: TokenBalance_Address, count: 1 } orderBy: { descending: Block_Time } where: { TokenBalance: { Address: { in: [ "0x9642b23Ed1E01Df1092B92641051881a322F5D4E" "0xf977814e90da44bfa03b6295a0616a897441acec" ] } Currency: { SmartContract: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Block { Time } TokenBalance { Address PostBalance PostBalanceInUSD } } } } ``` ## Balance history of one token Every row for the wallet and token, newest first, is the balance after each transaction that touched it. Saved query [here](https://ide.bitquery.io/Get-Token-Balance-History). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 100 } orderBy: { descending: Block_Time } where: { TokenBalance: { Address: { is: "0x9642b23Ed1E01Df1092B92641051881a322F5D4E" } Currency: { SmartContract: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } } } } ) { Block { Time Number } TokenBalance { PostBalance PostBalanceInUSD } Transaction { Hash } } } } ``` ## Total supply and market cap of a token Token rows carry `TotalSupply` and `TotalSupplyInUSD` as of that transaction, so the newest row for a token, from any wallet, is its current supply and on-chain market cap. Saved query [here](https://ide.bitquery.io/Get-Token-Total-Supply-and-Market-Cap). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 1 } orderBy: { descending: Block_Time } where: { TokenBalance: { Currency: { SmartContract: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } } } } ) { Block { Time } TokenBalance { Currency { Symbol Name } TotalSupply TotalSupplyInUSD } } } } ``` ## Stream balance changes of a token The token filter as a subscription delivers a row for every address whose USDT balance changes, as each transaction is indexed. Add the wallet to the filter to follow one holder. Saved stream [here](https://ide.bitquery.io/Track-Token-Balance-Changes-by-Transaction). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { Currency: { SmartContract: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } } } } ) { Block { Time } TokenBalance { Address PostBalance PostBalanceInUSD } Transaction { Hash From To } } } } ``` ## Related pages - [Ethereum transaction balance tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-transaction-balance-tracker) - [Ethereum NFT balance API](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/nft-balance-api) - [Balances and Holders cubes](/docs/cubes/balances-cube) - [Ethereum token market cap API](/docs/blockchain/Ethereum/token-supply/ethereum-token-marketcap-api) --- ## Ethereum Token Holder API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/token-holders/token-holder-api/ Rank Ethereum token holders with the Bitquery Holders cube: top holders, holder counts, dated snapshots, balance thresholds and distribution statistics. # Token Holders API :::note Holder rankings, snapshots and distribution stats are productized in the [Token Holder API](https://bitquery.io/products/token-holder-api) — see the page for chains, plans and trial access. ::: The **Holders** API returns token holder data for ERC-20 tokens on Ethereum: top holders, holder counts, and balance thresholds. Non-zero balances use `Amount(selectWhere: { gt: "0" })` on the `Balance` field (not in `where`). Use `dataset: combined` or `dataset: archive` as follows: | Dataset | When to use | |---------|-------------| | **`combined`** | Latest holder count, top holders, and balances. Queries **realtime and archive** databases and merges results. | | **`archive`** | Addresses not recently active (not in the realtime window). | Examples: [Top Holders](#top-holders-of-a-currency-current) · [Holder Count](#token-holder-count-for-an-erc-20-token) · [Whales](#holder-count-with-balance-above-a-threshold) · [Historical Top Holders](#historical-top-holders-by-date) · [Holder Activity](#token-holder-activity) · [Statistics](#token-holder-statistics) ## Top Holders of a Currency (Current) The most common starting point for traders and analysts: who holds the most of a token right now. Use `dataset: combined` for the latest top holders (realtime + archive). [Run in IDE](https://ide.bitquery.io/ethereum-holders-top)
Click to expand GraphQL query ```graphql { EVM(network: eth, dataset: combined) { Holders( date: "2026-06-30" where: {Currency: {SmartContract: {is: "0x54D2252757e1672EEaD234D27B1270728fF90581"}}} orderBy: {descending: Balance_Amount} limit: {count: 10} ) { Holder { Address } Balance { Amount(selectWhere: {gt: "0"}) FirstChangeTime LastChangeTime } } } } ```
## Token Holder Count for an ERC-20 Token How many wallets hold a token. Count distinct addresses with `uniq(of: Holder_Address)` and `dataset: combined`. [Run in IDE](https://ide.bitquery.io/ethereum-holders-count-combined)
Click to expand GraphQL query ```graphql query { EVM(network: eth, dataset: combined) { Holders( where: { Currency: { SmartContract: { is: "0x54D2252757e1672EEaD234D27B1270728fF90581" } } } ) { uniq(of: Holder_Address) } } } ```
## Token Holder Snapshot The number of unique holders, token supply, and Gini coefficient for the balance amount before a specific timestamp can be derived using the query below. These stats provide a useful holder snapshot for any given time. [Run in IDE](https://ide.bitquery.io/token-holder-snapshot_1)
Click to expand GraphQL query ```graphql query MyQuery($network: evm_network!, $address: String!) { EVM(network: $network, dataset: archive) { Holders( where: { Currency: {SmartContract: {is: $address}}, Balance: { Amount: {gt: "0"}, LastChangeTime: {till: "2026-05-20T00:00:00Z"} }, Holder: {Address: {not: "0x"}}} ) { Balance { LastChangeTime(maximum: Balance_LastChangeTime) } holders: uniq(of: Holder_Address) supply: sum(of: Balance_Amount) gini(of: Balance_Amount) } } } ``` ```json { "network": "eth", "address": "0x00000000001594c61dd8a6804da9ab58ed2483ce" } ```
## Holder Count with Balance Above a Threshold Count holders above a minimum balance (whale / large-holder filters). Use `uniq(of: Holder_Address, if: { Balance: { Amount: { gt: "..." } } })` with your threshold. [Run in IDE](https://ide.bitquery.io/count-ethereum-holders-count-above-threshold)
Click to expand GraphQL query ```graphql query { EVM(network: eth, dataset: combined) { Holders( where: { Currency: { SmartContract: { is: "0x54D2252757e1672EEaD234D27B1270728fF90581" } } } ) { uniq( of: Holder_Address if: { Balance: { Amount: { gt: "10000000" } } } ) } } } ```
## Track Whale Wallets and Token Holdings For whale monitoring, combine **[Top Holders](#top-holders-of-a-currency-current)** (`orderBy: { descending: Balance_Amount }`, `limit`) with **[Holder Count Above a Threshold](#holder-count-with-balance-above-a-threshold)**. Pair with [ERC-20 transfers](/docs/blockchain/Ethereum/transfers/erc20-token-transfer-api) to see recent inflows and outflows from large wallets. ## Historical Top Holders by Date The **Holders** cube does not support `Block.Date`. Filter by `Balance.LastChangeTime` using datetime format (for example `"2026-05-01T00:00:00Z"`). For address balances on a calendar date, use the [Balances API](/docs/blockchain/Ethereum/balances/balance-api/#balance-on-a-specific-date) with `Block.Date`. [Run in IDE](https://ide.bitquery.io/ethereum-holders-top-by-date)
Click to expand GraphQL query ```graphql query { EVM(network: eth, dataset: combined) { Holders( where: { Balance: { LastChangeTime: { till: "2026-05-01T00:00:00Z" } } Currency: { SmartContract: { is: "0x54D2252757e1672EEaD234D27B1270728fF90581" } } } orderBy: { descending: Balance_Amount } limit: { count: 100 } ) { Holder { Address } Balance { Amount(selectWhere: { gt: "0" }) LastChangeTime } } } } ```
## Token Holder Count History Over Time Build holder-count time series by running the count query with `Balance.LastChangeTime.till` at different timestamps, then aggregating in your app or scheduler. [Run in IDE](https://ide.bitquery.io/ethereum-holders-count-by-date)
Click to expand GraphQL query ```graphql query { EVM(network: eth, dataset: combined) { Holders( where: { Balance: { LastChangeTime: { till: "2026-05-01T00:00:00Z" } } Currency: { SmartContract: { is: "0x54D2252757e1672EEaD234D27B1270728fF90581" } } } ) { uniq(of: Holder_Address) } } } ```
## Wallet Balance at a Point in Time One wallet’s balance for a token on a given date uses the **[Balances API](/docs/blockchain/Ethereum/balances/balance-api/)**, not Holders: set `Balance.Address`, `Currency.SmartContract`, and `Block.Date.till`. Use `dataset: archive`, `orderBy: { descending: Block_Date }`, and `limit: { count: 1 }`. [Run in IDE](https://ide.bitquery.io/ethereum-wallet-balance-token-at-date) · [Balances API docs](/docs/blockchain/Ethereum/balances/balance-api/#wallet-balance-for-a-specific-token-on-a-date)
Click to expand GraphQL query ```graphql query { EVM(network: eth, dataset: archive) { Balances( where: { Block: { Date: { till: "2026-05-05" } } Balance: { Address: { is: "0xA46320Aa0b4877b9a46a07B4F3DB93719bd422dE" } } Currency: { SmartContract: { is: "0x54D2252757e1672EEaD234D27B1270728fF90581" } } } limit: { count: 1 } orderBy: { descending: Block_Date } ) { Currency { Symbol SmartContract } Balance { Amount(selectWhere: { gt: "0" }) AmountInUSD Address } } } } ```
## Token Holder Activity Drill into a **specific wallet** for a token: transfer count and first/last activity times. Uses the **Holders** API (`UpdateCount`, `FirstChangeTime`, `LastChangeTime`). ### Count of Transactions for a Token from a Token Holder [Run in IDE](https://ide.bitquery.io/Number-of-token-transactions-for-a-wallet)
Click to expand GraphQL query ```graphql query { EVM(network: eth, dataset: combined) { Holders( where: { Currency: { SmartContract: { is: "0x54D2252757e1672EEaD234D27B1270728fF90581" } } Holder: { Address: { is: "0xB953E202C5E51C7C010E80402a63C02f37F14059" } } } ) { Balance { UpdateCount } } } } ```
### First and Last Transfer Dates for a Token Holder [Run in IDE](https://ide.bitquery.io/Frst-and-last-date-time-for-token-holder)
Click to expand GraphQL query ```graphql query { EVM(network: eth, dataset: combined) { Holders( where: { Currency: { SmartContract: { is: "0x54D2252757e1672EEaD234D27B1270728fF90581" } } Holder: { Address: { is: "0xB953E202C5E51C7C010E80402a63C02f37F14059" } } } ) { Balance { UpdateCount LastChangeTime FirstChangeTime } } } } ```
## Token Holder Statistics Distribution metrics (average, median, Gini, Nakamoto index, and more) come from aggregate functions on the **`Holders`** cube. See [statistics docs](/docs/graphql/metrics/statistics/) for the full metric list, and the [Balances & Holders cubes](/docs/cubes/balances-cube) reference for how `Holders` differs from `Balances`. ### Average Balance of a Token Holder [Run in IDE](https://ide.bitquery.io/avg-usdt-balance-on-ethereum-using-token-holders-api)
Click to expand GraphQL query ```graphql { EVM(dataset: archive, network: eth) { Holders( date: "2026-05-01" where: { Currency: { SmartContract: { is: "0xdAC17F958D2ee523a2206206994597C13D831ec7" } }, Balance: { Amount: { ge: "0" } } } ) { average(of: Balance_Amount) } } } ```
### Median Balance of a Token Holder [Run in IDE](https://ide.bitquery.io/median-balance-of-usdt-holders-on-ethereum-with-token-holders-api)
Click to expand GraphQL query ```graphql { EVM(dataset: archive, network: eth) { Holders( date: "2026-05-01" where: { Currency: { SmartContract: { is: "0xdAC17F958D2ee523a2206206994597C13D831ec7" } }, Balance: { Amount: { ge: "0" } } } ) { median(of: Balance_Amount) } } } ```
## Find Token Holders Outside a Certain Range Advanced filter: holders with balance above an upper bound or below a lower bound (e.g. excluding mid-tier wallets). [Run in IDE](https://ide.bitquery.io/Find-holders-outside-a-range)
Click to expand GraphQL query ```graphql { EVM(dataset: archive) { Holders( date: "2026-05-01" where: { Currency: { SmartContract: { is: "0x0fcbd68251819928c8f6d182fc04be733fa94170" } }, any: [ { Balance: { Amount: { gt: "100" } } } { Balance: { Amount: { lt: "20" } } } ] Balance: { Amount: { gt: "0" } } } orderBy: { descending: Balance_Amount } limit: { count: 10 } ) { Balance { Amount } Holder { Address } Currency { Name Symbol } } } } ```
## Video Tutorial on How to Identify Top Token Holders for Any Cryptocurrency --- ## Ethereum Token Market Cap API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/token-supply/ethereum-token-marketcap-api/ Ethereum Token Market Cap API: stream Ethereum market cap, FDV, supply, and price using Bitquery Trading GraphQL APIs. See examples in the Bitquery IDE. # Ethereum Token Market Cap API Use Bitquery’s **Trading** API **`Tokens`** cube to stream or query **market cap**, **fully diluted valuation (USD)**, **total supply**, **price** (OHLC and averages), and **volume** for tokens traded on **Ethereum**. Rows are tied to a time **interval**; filter Ethereum assets via token/currency **`Id`** (for example `eth:` plus the contract address). For schema details and field meanings, see the **[Tokens cube](/docs/trading/crypto-price-api/tokens)** and **[Supply fields](/docs/trading/crypto-price-api/supply-fields)**. :::note Trading API and EVM addresses In the **Trading** API, use **lowercase** hex for EVM contract addresses in token/currency **`Id`** values (e.g. `eth:0xabc…`, not checksum `0xAbC…`). ::: ## Related APIs - **[Base Token Market Cap API](/docs/blockchain/Base/base-token-marketcap-api)** — same **`Trading.Tokens`** patterns on Base (`base:` ids) - **[Arbitrum Token Market Cap API](/docs/blockchain/Arbitrum/arbitrum-token-marketcap-api)** — same **`Trading.Tokens`** patterns on Arbitrum (`arbitrum:` ids) - **[Polygon (Matic) Token Market Cap API](/docs/blockchain/Matic/matic-token-marketcap-api)** — same **`Trading.Tokens`** patterns on Polygon (`matic:` ids) - **[BSC Token Market Cap API](/docs/blockchain/BSC/bsc-token-marketcap-api)** — same **`Trading.Tokens`** patterns on BNB Smart Chain (`bsc:` ids) - **[Solana Token Market Cap API](/docs/blockchain/Solana/solana-token-marketcap-api)** — same **`Trading.Tokens`** patterns on Solana (`solana:` ids) - **[EVM Token Supply API](/docs/blockchain/Ethereum/token-supply/evm-token-supply)** — on-chain total supply via `EVM` / `TransactionBalances` - **[Crypto Price API — Tokens](/docs/trading/crypto-price-api/tokens)** — full `Tokens` cube reference --- ## How do I stream live Ethereum token market cap, price, and volume? Subscribe to **`Tokens`** updates for assets whose **currency id** includes **`eth`** (Ethereum), with an **interval duration** greater than **1** (second). Each payload can include **token metadata**, **block time**, **supply** (including **MarketCap** and **FullyDilutedValuationUsd**), **price** (OHLC and average mean), and **volume**. You can run this subscription [in the Bitquery IDE](https://ide.bitquery.io/ethereum-token-marketcap-stream_1). ```graphql subscription MyQuery { Trading { Tokens( where: { Currency: { Id: { includes: "eth" } } Interval: { Time: { Duration: { gt: 1 } } } } ) { Token { Name Id Address Symbol } Block { Time } Supply { TotalSupply FullyDilutedValuationUsd MarketCap } Price { Average { Mean } Ohlc { Open Low High Close } } Volume { Base BaseAttributedToUsd Quote Usd } } } } ``` --- ## How do I get the latest market cap for a specific Ethereum token? Return the **most recent** row for one token by **`Token.Id`** (e.g. `eth:` + **lowercase** contract address). Use **`limit: { count: 1 }`** and **`orderBy: { descending: Block_Time }`**. You can run this query [in the Bitquery IDE](https://ide.bitquery.io/specific-ethereum-token-latest-marketcap_1). ```graphql query { Trading { Tokens( limit: { count: 1 } orderBy: { descending: Block_Time } where: { Token: { Id: { includes: "eth:0xe53ec727dbdeb9e2d5456c3be40cff031ab40a55" } } Interval: { Time: { Duration: { gt: 1 } } } } ) { Token { Name Id Address Symbol } Block { Time } Supply { TotalSupply FullyDilutedValuationUsd MarketCap } Price { Average { Mean } Ohlc { Open Low High Close } } Volume { Base BaseAttributedToUsd Quote Usd } } } } ``` Replace the `includesCaseInsensitive` value with your token’s **`eth:`** id. --- ## How do I stream Ethereum tokens with market cap above $1 million? Subscribe to **`Tokens`** where the token id matches Ethereum (**`eth`**) and **`Supply.MarketCap`** is **greater than 1,000,000** (USD). The example selects **currency**, **supply**, and **market cap** fields suitable for dashboards and alerts. You can run this subscription [in the Bitquery IDE](https://ide.bitquery.io/realtime-stream-ethereum-tokens-with-marketcap-above-1-million). ```graphql subscription { Trading { Tokens( where: { Token: { Id: { includes: "eth" } } Interval: { Time: { Duration: { gt: 1 } } } Supply: { MarketCap: { gt: 1000000 } } } ) { Currency { Name Id Symbol } Supply { TotalSupply FullyDilutedValuationUsd MarketCap } } } } ``` :::tip Threshold and interval Adjust **`Supply.MarketCap`** and **`Interval.Time.Duration`** filters to match your use case. See **[Tokens cube](/docs/trading/crypto-price-api/tokens)** for other filter fields. ::: --- ## How do I get top Ethereum tokens by market cap? This query ranks **Ethereum** tokens by **`Supply.MarketCap`** (latest in the window). It uses data from roughly the **last 24 hours** (`since_relative: { hours_ago: 24 }`), **1-second** intervals (`Duration: { eq: 1 }`), at least **$1,000** **USD volume**, **`limitBy`** one row per **`Token_Id`**, and returns up to **50** tokens. You can run this query [in the Bitquery IDE](https://ide.bitquery.io/Top-Tokens-by-Market-Cap-on-Ethereum). ```graphql { Trading { Tokens( limit: { count: 50 } limitBy: { count: 1, by: Token_Id } orderBy: { descending: Supply_MarketCap } where: { Block: { Time: { since_relative: { hours_ago: 24 } } } Interval: { Time: { Duration: { eq: 1 } } } Volume: { Usd: { gt: 1000 } } Token: { Network: { is: "Ethereum" } } } ) { Currency { Id Name Symbol } Price { Average { Mean(maximum: Block_Time) } } Volume { Base(maximum: Block_Time) Quote(maximum: Block_Time) Usd(maximum: Block_Time) } Token { Network Symbol Address } Supply { MarketCap(maximum: Block_Time) FullyDilutedValuationUsd(maximum: Block_Time) TotalSupply(maximum: Block_Time) } } } } ``` --- ## How do I get top Ethereum tokens by market cap change in 1 hour? This query uses a **1-hour** OHLC interval (`Duration: { eq: 3600 }`) and orders by a calculated field **`change_mcap`**: **(close − open) × total supply**, approximating **USD market cap change** over the period. Filter **`Token.Network`** is **Ethereum**. You can run this query [in the Bitquery IDE](https://ide.bitquery.io/top-Eth-tokens-by-Market-Cap-Change-1h_1). ```graphql { Trading { Tokens( limit: { count: 50 } orderBy: { descendingByField: "change_mcap" } where: { Interval: { Time: { Duration: { eq: 3600 } } } Token: { Network: { is: "Ethereum" } } } ) { Currency { Id Name Symbol } Token { Network Symbol Address } Supply { MarketCap FullyDilutedValuationUsd CirculatingSupply TotalSupply MaxSupply } change_mcap: calculate( expression: "($Price_Ohlc_Close-$Price_Ohlc_Open) * Supply_TotalSupply" ) Price { Ohlc { Open Close } } } } } ``` ## Video tutorial --- ## Ethereum Token Trades APIs URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/token-trades-apis/ Ethereum Token Trades Apis: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. See examples in the Bitquery IDE. # Token Trades API :::tip Need real-time token trade data or anything from the last ~30 days? For **real-time + last ~30 days**, use the [**Trading cube**](/docs/trading/trading-data-overview): [`Trading.Trades`](/docs/trading/crypto-trades-api/trades-api) gives you clean, MEV-filtered token trade swaps with **USD price, market cap, and supply on every row** across **10 chains in one API**. Use the `EVM` queries on this page for raw per-swap detail or call and event context. An `EVM` query without a `dataset` argument runs on the realtime dataset, which holds only the last few days; add `dataset: combined` or `dataset: archive` for **historical token trade data**, as several examples below do. ::: We have three main APIs to get DEX trading data. - DEXTrades - DEXTradeByTokens - Trades cube Read [DEXTrades vs DEXTradeByTokens vs Trades cube](/docs/cubes/dextrades-dextradebytokens-trading-trades) to get a better understanding on when to use which cube. ## Subscribe to realtime DEXTrades on Ethereum Mainnet This subscription streams [every DEX trade on Ethereum mainnet as it happens](https://ide.bitquery.io/subscribe-to-dex-trades-on-ethereum-mainnet_2).
Subscription: every Ethereum DEX trade as it happens ```graphql subscription MyQuery { EVM(network: eth) { DEXTrades { Block { Time Number } Transaction { Hash } Call { Signature { Name Signature } } Log { Index SmartContract Signature { Signature Name } } Trade { Sender Buy { Buyer AmountInUSD Amount Seller PriceInUSD Price Currency { Name Symbol SmartContract } } Dex { SmartContract ProtocolName ProtocolVersion } Sell { Buyer AmountInUSD Amount Seller PriceInUSD Price Currency { Name Symbol SmartContract } } } } } } ```
## Get the Buys, Sells, Buy Volume, Sell Volume and Makers Fetch buys, sells, volumes, and the number of makers for a specific pool (`0x842293fa6ee0642bf61ebf8310e7e546039ba7f4`). A [video walks through building DexScreener-style trade stats with this query](https://www.youtube.com/watch?v=K_H3to_nIdY).
Buys, sells, volume and makers for one pool, with variables ```graphql query MyQuery( $network: evm_network $token: String $pairAddress: String $min5_timestamp: DateTime $hr1_timestamp: DateTime ) { EVM(dataset: realtime, network: $network) { DEXTradeByTokens( where: { TransactionStatus: { Success: true } Trade: { Currency: { SmartContract: { is: $token } } Dex: { SmartContract: { is: $pairAddress } } } Block: { Time: { since: $hr1_timestamp } } } ) { Trade { Currency { Name SmartContract Symbol } startPrice: PriceInUSD(minimum: Block_Time) Price_at_min5: PriceInUSD( minimum: Block_Time if: { Block: { Time: { after: $min5_timestamp } } } ) current_price: PriceInUSD(maximum: Block_Time) Dex { ProtocolName ProtocolFamily SmartContract } Side { Currency { Symbol Name SmartContract } } } makers: count(distinct: Transaction_From) makers_5min: count( distinct: Transaction_From if: { Block: { Time: { after: $min5_timestamp } } } ) buyers: count( distinct: Transaction_From if: { Trade: { Side: { Type: { is: sell } } } } ) buyers_5min: count( distinct: Transaction_From if: { Trade: { Side: { Type: { is: sell } } } Block: { Time: { after: $min5_timestamp } } } ) sellers: count( distinct: Transaction_From if: { Trade: { Side: { Type: { is: buy } } } } ) sellers_5min: count( distinct: Transaction_From if: { Trade: { Side: { Type: { is: buy } } } Block: { Time: { after: $min5_timestamp } } } ) trades: count trades_5min: count(if: { Block: { Time: { after: $min5_timestamp } } }) traded_volume: sum(of: Trade_Side_AmountInUSD) traded_volume_5min: sum( of: Trade_Side_AmountInUSD if: { Block: { Time: { after: $min5_timestamp } } } ) buy_volume: sum( of: Trade_Side_AmountInUSD if: { Trade: { Side: { Type: { is: sell } } } } ) buy_volume_5min: sum( of: Trade_Side_AmountInUSD if: { Trade: { Side: { Type: { is: sell } } } Block: { Time: { after: $min5_timestamp } } } ) sell_volume: sum( of: Trade_Side_AmountInUSD if: { Trade: { Side: { Type: { is: buy } } } } ) sell_volume_5min: sum( of: Trade_Side_AmountInUSD if: { Trade: { Side: { Type: { is: buy } } } Block: { Time: { after: $min5_timestamp } } } ) buys: count(if: { Trade: { Side: { Type: { is: sell } } } }) buys_5min: count( if: { Trade: { Side: { Type: { is: sell } } } Block: { Time: { after: $min5_timestamp } } } ) sells: count(if: { Trade: { Side: { Type: { is: buy } } } }) sells_5min: count( if: { Trade: { Side: { Type: { is: buy } } } Block: { Time: { after: $min5_timestamp } } } ) } } } ``` ```json { "network": "eth", "token": "0x6982508145454Ce325dDbE47a25d4ec3d2311933", "pairAddress": "0xA43fe16908251ee70EF74718545e4FE6C5cCEc9f", "hr1_timestamp": "2024-11-14T03:20:00Z", "min5_timestamp": "2024-11-14T04:15:00Z" } ```
## Get the Buys, Sells, Buy Volume, Sell Volume and Makers of Multiple Tokens Same metrics as above, but for multiple pools at once.
The same metrics for several pools, with variables ```graphql query MyQuery( $network: evm_network, $token: String, $pairAddress: [String!], $min5_timestamp: DateTime, $hr1_timestamp: DateTime ) { EVM(dataset: realtime, network: $network) { DEXTradeByTokens( where: { TransactionStatus: { Success: true }, Trade: { Dex: { SmartContract: { in: $pairAddress } }, Side: { Currency: { SmartContract: { is: $token } } } }, Block: { Time: { since: $hr1_timestamp } } } ) { /* same fields as previous */ } } } ``` ```json { "network": "eth", "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "pairAddress": [ "0x055FB841Cce69000FBAFF2691Ad39Fa6E23826a1", "0x8d345583C9289D69d4a55797CcadC5A1eA150A44" ], "hr1_timestamp": "2025-06-18T07:34:00Z", "min5_timestamp": "2025-06-18T08:28:00Z" } ```
## Get First 500 Buyers of a specific token This returns the [first 500 buyers of an ERC-20 token](https://ide.bitquery.io/first-500-buyers-of-a-ERC20-token_1#), `0x3c3a81e81dc49A522A592e7622A7E711c06bf354` in this example.
First 500 buyers of an ERC-20 token ```graphql query MyQuery { EVM(network: eth, dataset: combined) { DEXTrades( limit: { count: 500 } orderBy: { ascending: Block_Time } limitBy: { count: 1, by: Trade_Sell_Buyer } where: { Trade: { Sell: { Currency: { SmartContract: { is: "0x3c3a81e81dc49A522A592e7622A7E711c06bf354" } } } } } ) { Block { Time } Trade { Sell { Buyer } } Transaction { From Hash } } } } ```
## Historical Token Trades & Price API Use the DEXTrades API for historical buyside and sellside trades of BLUR token by the 1inch router.
BLUR trades routed through 1inch, from the archive (fields omitted) ```graphql { EVM(dataset: archive, network: eth) { buyside: DEXTrades( limit: { count: 10 } orderBy: { descending: Block_Time } where: { Trade: { Buy: { Currency: { SmartContract: { is: "0x5283d291dbcf85356a21ba090e6db59121208b44" } } Seller: { is: "0x1111111254eeb25477b68fb85ed929f73a960582" } } } Block: { Time: { since: "2023-03-03T01:00:00Z", till: "2023-03-05T05:15:23Z" } } } ) { /* buyside fields */ } sellside: DEXTrades( limit: { count: 10 } orderBy: { descending: Block_Time } where: { Trade: { Sell: { Currency: { SmartContract: { is: "0x5283d291dbcf85356a21ba090e6db59121208b44" } } Buyer: { is: "0x1111111254eeb25477b68fb85ed929f73a960582" } } } Block: { Time: { since: "2023-03-03T01:00:00Z", till: "2023-03-05T05:15:23Z" } } } ) { /* sellside fields */ } } } ```
## Get Price Change 5min, 1h, 6h and 24h of a specific token This returns the [price change over 5 minutes, 1, 6 and 24 hours for one token](https://ide.bitquery.io/Price-change-5min-1hr-6hr-precentage-of-a-specific-token_1#). Change `Currency{SmartContract}` and `Dex{SmartContract}` to your token and pool.
Price change over 5 minutes, 1, 6 and 24 hours ```graphql query MyQuery { EVM(dataset: combined) { DEXTradeByTokens( where: {Trade: {Currency: {SmartContract: {is: "0x4393b54385e91824A2Ae5DFd35e226A3313A1a18"}}, Dex: {SmartContract: {is: "0x2bE4042B40359555b41C1A8b80bf604267DE0C5A"}}}, TransactionStatus: {Success: true}, Block: {Time: {since_relative: {hours_ago: 24}}}} ){ Trade { Price_5min_ago: PriceInUSD(minimum:Block_Number if:{Block:{Time:{since_relative:{minutes_ago:5}}}}) Price_1h_ago: PriceInUSD(minimum:Block_Number if:{Block:{Time:{since_relative:{hours_ago:1}}}}) Price_6h_ago: PriceInUSD(minimum: Block_Number if:{Block:{Time:{since_relative:{hours_ago:6}}}}) Price_24h_ago: PriceInUSD(minimum: Block_Number) CurrentPrice: PriceInUSD(maximum: Block_Number) } volume_5min: sum( of: Trade_Side_AmountInUSD if: {Block: {Time: {since_relative: {minutes_ago: 5}}}} ) volume_1h: sum( of: Trade_Side_AmountInUSD if: {Block: {Time: {since_relative: {hours_ago: 1}}}} ) volume_6h: sum( of: Trade_Side_AmountInUSD if: {Block: {Time: {since_relative: {hours_ago: 6}}}} ) volume_24h: sum( of: Trade_Side_AmountInUSD ) Price_Change_5min: calculate(expression: "(($Trade_CurrentPrice - $Trade_Price_5min_ago) / $Trade_Price_5min_ago) * 100") Price_Change_1h: calculate(expression: "(($Trade_CurrentPrice - $Trade_Price_1h_ago) / $Trade_Price_1h_ago) * 100") Price_Change_6h: calculate(expression: "(($Trade_CurrentPrice - $Trade_Price_6h_ago) / $Trade_Price_6h_ago) * 100") Price_Change_24h: calculate(expression: "(($Trade_CurrentPrice - $Trade_Price_24h_ago) / $Trade_Price_24h_ago) * 100") } } } ```
## Top 10 Eth Tokens by Price Change in last 1h This returns the [10 Ethereum tokens with the biggest price change in the last hour](https://ide.bitquery.io/Top-10-eth-tokens-by-price-change-in-last-1-hr_2).
Ten Ethereum tokens with the biggest 1-hour price change ```graphql query MyQuery { EVM(dataset: combined) { DEXTradeByTokens( limit: {count: 10} orderBy: {descendingByField: "Price_Change_1h"} where: {TransactionStatus: {Success: true}, Block: {Time: {since_relative: {hours_ago: 24}}}, Trade: {Side: {Currency: {SmartContract: {is: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"}}}}} ) { Trade { Currency { Name Symbol SmartContract } Price_5min_ago: PriceInUSD( minimum: Block_Number if: {Block: {Time: {since_relative: {minutes_ago: 5}}}} selectWhere:{ne:0} ) Price_1h_ago: PriceInUSD( minimum: Block_Number if: {Block: {Time: {since_relative: {hours_ago: 1}}}} selectWhere:{ne:0} ) Price_6h_ago: PriceInUSD( minimum: Block_Number if: {Block: {Time: {since_relative: {hours_ago: 6}}}} selectWhere:{ne:0} ) Price_24h_ago: PriceInUSD(minimum: Block_Number selectWhere:{ne:0}) CurrentPrice: PriceInUSD(maximum: Block_Number selectWhere:{ne:0}) Side { Currency { Name Symbol SmartContract } } Dex { SmartContract } } volume_5min: sum( of: Trade_Side_AmountInUSD if: {Block: {Time: {since_relative: {minutes_ago: 5}}}} ) volume_1h: sum( of: Trade_Side_AmountInUSD if: {Block: {Time: {since_relative: {hours_ago: 1}}}} ) volume_6h: sum( of: Trade_Side_AmountInUSD if: {Block: {Time: {since_relative: {hours_ago: 6}}}} ) volume_24h: sum(of: Trade_Side_AmountInUSD) Price_Change_5min: calculate( expression: "(($Trade_CurrentPrice - $Trade_Price_5min_ago) / $Trade_Price_5min_ago) * 100" ) Price_Change_1h: calculate( expression: "(($Trade_CurrentPrice - $Trade_Price_1h_ago) / $Trade_Price_1h_ago) * 100" ) Price_Change_6h: calculate( expression: "(($Trade_CurrentPrice - $Trade_Price_6h_ago) / $Trade_Price_6h_ago) * 100" ) Price_Change_24h: calculate( expression: "(($Trade_CurrentPrice - $Trade_Price_24h_ago) / $Trade_Price_24h_ago) * 100" ) } } } ```
## Latest Trades of a Token Fetch the most recent 50 trades for a given token:
The 50 latest trades of one token ```graphql query LatestTrades { EVM(network: eth) { DEXTradeByTokens( orderBy: { descending: Block_Time } limit: { count: 50 } where: { Trade: { Currency: { SmartContract: { is: "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599" } } Price: { gt: 0 } } } ) { Block { allTime: Time } Trade { Dex { OwnerAddress ProtocolFamily ProtocolName } AmountInUSD Buyer Seller Side { Type Buyer Seller } Price Amount Side { Currency { Symbol SmartContract Name } AmountInUSD Amount } } } } } ```
![DEXrabbit's WBTC Latest Trades tab listing each trade's time, side, price, both currencies and amounts, and USD value](https://github.com/user-attachments/assets/e4273aea-bf8d-41e4-80e8-b676005e0ce7) Our DEX Dashboard gives you a easier way to check the data -> [DEXrabbit](https://dexrabbit.bitquery.io/eth/token/0x2260fac5e5542a773aa44fbcfedf7c193bc2c599#last_trades). ## Latest Trades of Multiple Tokens [Run Query](https://ide.bitquery.io/latest-trades-of-multiple-tokens-against-weth-usdt)
{" "} Latest trades of WBTC and LINK ```graphql query LatestTrades { EVM(network: eth) { DEXTradeByTokens( orderBy: { descending: Block_Time } limit: { count: 50 } where: { TransactionStatus: { Success: true } Trade: { Side: { Currency: { SmartContract: { in: [ "0x", "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "0xdac17f958d2ee523a2206206994597c13d831ec7" ] } } } Currency: { SmartContract: { in: [ "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", "0x514910771af9ca656af840dff83e8264ecf986ca" ] } } Success: true } Block: { Time: { since: "2025-08-17T08:55:31Z" } } } ) { Block { Time } Transaction { Hash } Trade { Dex { SmartContract ProtocolFamily ProtocolName } AmountInUSD Buyer Seller Side { Type Buyer Seller } PriceInUSD Amount Side { Currency { Symbol SmartContract Name } AmountInUSD Amount } } } } } ```
## Token Trade Analytics Trade totals for one BNB Chain token over its full history: pairs, DEXs, amount and USD volume, and the number of accounts that bought and sold it. The USD sums leave out mispriced trades.
Pairs, DEXs, volume and traders for one BNB Chain token ```graphql { EVM(network: bsc, dataset: combined) { DEXTradeByTokens( where: { Trade: { Currency: { SmartContract: { is: "0xc342774492b54ce5f8ac662113ed702fc1b34972" } } } } orderBy: { descendingByField: "usd" } limit: { count: 1000 } ) { Trade { Currency { Decimals Symbol SmartContract Fungible Name } Amount(maximum: Block_Number) AmountInUSD(maximum: Block_Number) } pairs: uniq(of: Trade_Side_Currency_SmartContract) dexes: uniq(of: Trade_Dex_OwnerAddress) amount: sum(of: Trade_Amount) usd: sum(of: Trade_AmountInUSD, if: { Trade: { PriceAsymmetry: { lt: 0.1 } } }) usd2: sum(of: Trade_Side_AmountInUSD, if: { Trade: { PriceAsymmetry: { lt: 0.1 } } }) buyers: uniq(of: Transaction_From, if: { Trade: { Side: { Type: { is: sell } } } }) sellers: uniq(of: Transaction_From, if: { Trade: { Side: { Type: { is: buy } } } }) count } } } ```
## Aggregated Token Data (Volume & Price, Last 24h) Use this API to get historical price and volume for a specific token (example: bid:solana:9WHhgXJBGgxghkh5wAUWJFHVbnsRbonRYTnH2EChpump) over the past 24 hours, with 1h, 4h, and 24h breakdowns. Try it on IDE: [Historical Price & Volume API](https://ide.bitquery.io/historical-price-and-historical-volume)
Trading.Tokens volume and price for the past 24 hours ```graphql { Trading { Tokens( where: { Interval: { Time: { Duration: { eq: 1 } } } Block: { Time: { since_relative: { hours_ago: 24 } } } Token: { Id: { in: ["bid:solana:9WHhgXJBGgxghkh5wAUWJFHVbnsRbonRYTnH2EChpump"] } } } ) { Currency { Id Name Symbol } Price { Average { currentPrice: Mean(maximum: Block_Time) H1Ago: Mean( minimum: Block_Time if: { Block: { Time: { since_relative: { hours_ago: 1 } } } } ) H4Ago: Mean( minimum: Block_Time if: { Block: { Time: { since_relative: { hours_ago: 4 } } } } ) H24Ago: Mean( minimum: Block_Time if: { Block: { Time: { since_relative: { hours_ago: 24 } } } } ) } } v1h: sum( of: Volume_Usd if: { Block: { Time: { since_relative: { hours_ago: 1 } } } } ) v4h: sum( of: Volume_Usd if: { Block: { Time: { since_relative: { hours_ago: 4 } } } } ) v24h: sum(of: Volume_Usd) } } } ```
## Top Traders of a Token Returns the top 100 traders of a token by USD volume. It ranks `Transaction.From`, the account that sent each swap, since on a sale `Trade.Buyer` is the pool or a router. `Side.Type` describes the counter-side of each trade, so `bought` sums the rows where `Side.Type` is `sell`. `PriceAsymmetry: { lt: 0.1 }` leaves out trades whose two sides disagree on value ([PriceAsymmetry reference](/docs/graphql/metrics/priceAsymmetry/)).
Top 100 traders of a token, with variables ```graphql query topTraders($network: evm_network, $token: String) { EVM(network: $network) { DEXTradeByTokens( orderBy: { descendingByField: "volumeUsd" } limit: { count: 100 } where: { Trade: { Currency: { SmartContract: { is: $token } }, PriceAsymmetry: { lt: 0.1 } } } ) { Transaction { From } bought: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: sell } } } }) sold: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: buy } } } }) volume: sum(of: Trade_Amount) volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } { "network": "eth", "token": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599" } ```
You can check the data here on [DEXrabbit](https://dexrabbit.bitquery.io/eth/token/0x2260fac5e5542a773aa44fbcfedf7c193bc2c599#top_traders). ## Get all Trading Pairs data of a specific token
Pairs a token trades in, with variables ```graphql query tokenTrades( $network: evm_network, $token: String, $time_10min_ago: DateTime, $time_1h_ago: DateTime, $time_3h_ago: DateTime ) { EVM(network: $network) { DEXTradeByTokens( orderBy: { descendingByField: "usd" } where: { Trade: { Currency: { SmartContract: { is: $token } } }, Block: { Time: { after: $time_3h_ago } } } limit: { count: 200 } ) { Trade { Currency { Symbol Name SmartContract Fungible } Side { Currency { Symbol Name SmartContract } } price_usd: PriceInUSD(maximum: Block_Number) price_last: Price(maximum: Block_Number) price_10min_ago: Price( maximum: Block_Number if: { Block: { Time: { before: $time_10min_ago } } } ) price_1h_ago: Price( maximum: Block_Number if: { Block: { Time: { before: $time_1h_ago } } } ) price_3h_ago: PriceInUSD(minimum: Block_Number) } usd: sum(of: Trade_AmountInUSD) count } } } { "network": "eth", "token": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", "time_10min_ago": "2024-09-22T12:39:26Z", "time_1h_ago": "2024-09-22T11:49:26Z", "time_3h_ago": "2024-09-22T09:49:26Z" } ```
![DEXrabbit's WBTC Traded Pairs tab with last price, USD price, 10-minute, 1-hour and 3-hour change, daily volume and daily trades per pair](https://github.com/user-attachments/assets/dfe5ad4b-cb32-4a53-a52c-3985d438da2b) You can check the data here on [DEXrabbit](https://dexrabbit.bitquery.io/eth/token/0x2260fac5e5542a773aa44fbcfedf7c193bc2c599#token_trades). ## Get all DEXs where a specific token is listed
DEXs that trade a token, with variables ```graphql query tokenDexMarkets($network: evm_network, $token: String) { EVM(network: $network) { DEXTradeByTokens( orderBy: { descendingByField: "amount" } where: { Trade: { Currency: { SmartContract: { is: $token } } } } ) { Trade { Dex { ProtocolFamily ProtocolName } } amount: sum(of: Trade_Amount) pairs: uniq(of: Trade_Side_Currency_SmartContract) trades: count } } } { "network": "eth", "token": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599" } ```
![DEXrabbit's WBTC DEX Markets tab listing each DEX and protocol with its trade count, pair count and WBTC volume](https://github.com/user-attachments/assets/f0de1013-b634-4058-8423-78d7130fcc10) You can check the data here on [DEXrabbit](https://dexrabbit.bitquery.io/eth/token/0x2260fac5e5542a773aa44fbcfedf7c193bc2c599#token_dex_list). ## Latest Trades of a Token pair
Latest trades of one pair, with variables ```graphql query LatestTrades($network: evm_network, $token: String, $base: String) { EVM(network: $network) { DEXTradeByTokens( orderBy: { descending: Block_Time } limit: { count: 50 } where: { Trade: { Side: { Amount: { gt: "0" }, Currency: { SmartContract: { is: $base } } }, Currency: { SmartContract: { is: $token } }, Price: { gt: 0 } } } ) { Block { allTime: Time } Trade { Dex { OwnerAddress ProtocolFamily ProtocolName } Currency { Symbol SmartContract Name } Price AmountInUSD Amount Side { Type Currency { Symbol SmartContract Name } AmountInUSD Amount } } } } } { "network": "eth", "token": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "base": "0x0ccae1bc46fb018dd396ed4c45565d4cb9d41098" } ```
![DEXrabbit's WETH / MISHA Latest Trades tab with time, side, price, WETH and MISHA amounts, and USD value](https://github.com/user-attachments/assets/b06fe6ff-e8ba-43f7-b9de-22666dde7bc6) You can check the data here on [DEXrabbit](https://dexrabbit.bitquery.io/eth/pair/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/0x0ccae1bc46fb018dd396ed4c45565d4cb9d41098#pair_latest_trades). ## Get OHLC data for a particular token pair
Five-minute USD candles for one pair, with variables ```graphql query tradingViewPairs($network: evm_network, $token: String, $base: String) { EVM(network: $network) { DEXTradeByTokens( orderBy: { ascendingByField: "Block_Time" } where: { Trade: { Side: { Amount: { gt: "0" }, Currency: { SmartContract: { is: $base } } }, Currency: { SmartContract: { is: $token } }, PriceAsymmetry: { lt: 0.5 } } } ) { Block { Time(interval: { count: 5, in: minutes }) } Trade { open: PriceInUSD(minimum: Block_Number) close: PriceInUSD(maximum: Block_Number) max: PriceInUSD(maximum: Trade_PriceInUSD) min: PriceInUSD(minimum: Trade_PriceInUSD) } volume: sum(of: Trade_Side_Amount) } } } { "network": "eth", "token": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "base": "0x0ccae1bc46fb018dd396ed4c45565d4cb9d41098" } ```
![DEXrabbit's 5-minute candlestick chart for WETH / MISHA with volume bars](https://github.com/user-attachments/assets/33af35df-4a9b-4ec8-a26b-d4770c2e7c96) You can check the data here on [DEXrabbit](https://dexrabbit.bitquery.io/eth/pair/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/0x0ccae1bc46fb018dd396ed4c45565d4cb9d41098). ## Top Traders of a token pair The same ranking for one pair: accounts that sent swaps between WETH and the base token, with `bought` and `sold` counted the same way.
Top 100 traders of one pair, with variables ```graphql query pairTopTraders($network: evm_network, $token: String, $base: String) { EVM(network: $network) { DEXTradeByTokens( orderBy: { descendingByField: "volumeUsd" } limit: { count: 100 } where: { Trade: { Currency: { SmartContract: { is: $token } }, Side: { Amount: { gt: "0" }, Currency: { SmartContract: { is: $base } } }, PriceAsymmetry: { lt: 0.1 } } } ) { Transaction { From } bought: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: sell } } } }) sold: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: buy } } } }) volume: sum(of: Trade_Amount) volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } { "network": "eth", "token": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "base": "0x0ccae1bc46fb018dd396ed4c45565d4cb9d41098" } ```
You can check the data here on [DEXrabbit](https://dexrabbit.bitquery.io/eth/pair/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/0x0ccae1bc46fb018dd396ed4c45565d4cb9d41098#pair_top_traders). ## Get all DEXs where a specific token pair is listed
DEXs that trade one pair, with variables ```graphql query pairDexList( $network: evm_network, $token: String, $base: String, $time_10min_ago: DateTime, $time_1h_ago: DateTime, $time_3h_ago: DateTime ) { EVM(network: $network) { DEXTradeByTokens( orderBy: { descendingByField: "amount" } where: { Trade: { Currency: { SmartContract: { is: $token } }, Side: { Amount: { gt: "0" }, Currency: { SmartContract: { is: $base } } } }, Block: { Time: { after: $time_3h_ago } } } ) { Trade { Dex { ProtocolFamily ProtocolName } price_last: PriceInUSD(maximum: Block_Number) price_10min_ago: PriceInUSD( maximum: Block_Number if: { Block: { Time: { before: $time_10min_ago } } } ) price_1h_ago: PriceInUSD( maximum: Block_Number if: { Block: { Time: { before: $time_1h_ago } } } ) price_3h_ago: PriceInUSD(minimum: Block_Number) } amount: sum(of: Trade_Side_Amount) pairs: uniq(of: Trade_Side_Currency_SmartContract) trades: count } } } { "network": "eth", "token": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "base": "0x0ccae1bc46fb018dd396ed4c45565d4cb9d41098", "time_10min_ago": "2024-09-22T13:10:42Z", "time_1h_ago": "2024-09-22T12:20:42Z", "time_3h_ago": "2024-09-22T10:20:42Z" } ```
![DEXrabbit's WETH / MISHA DEX Markets tab: Uniswap v2 and v3 rows with trades, last price, 10-minute, 1-hour and 3-hour change and daily volume](https://github.com/user-attachments/assets/a652f6de-1066-49b6-87f7-b05e481565bf) You can check the data here on [DEXrabbit](https://dexrabbit.bitquery.io/eth/pair/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/0x0ccae1bc46fb018dd396ed4c45565d4cb9d41098#pair_dex_list). ## Top Gainers Pairs ranked by USD price change over the last hour, among pairs with at least 100 trades in that hour. A pair can appear twice, once for each of its tokens. `buyers` and `sellers` count the accounts that sent those swaps.
Pairs ranked by 1-hour price gain, with variables ```graphql query ($network: evm_network) { EVM(network: $network) { DEXTradeByTokens( orderBy: { descendingByField: "change_1h" } limit: { count: 100 } where: { Block: { Time: { since_relative: { hours_ago: 1 } } } Trade: { PriceAsymmetry: { lt: 0.1 } } } ) { Trade { Currency { Symbol Name SmartContract } Side { Currency { Symbol Name SmartContract } } price_last: PriceInUSD(maximum: Block_Number) price_1h_ago: PriceInUSD(minimum: Block_Number) } change_1h: calculate(expression: "($Trade_price_last - $Trade_price_1h_ago) / $Trade_price_1h_ago * 100") dexes: uniq(of: Trade_Dex_OwnerAddress) amount: sum(of: Trade_Side_Amount) usd: sum(of: Trade_Side_AmountInUSD) buyers: uniq(of: Transaction_From, if: { Trade: { Side: { Type: { is: sell } } } }) sellers: uniq(of: Transaction_From, if: { Trade: { Side: { Type: { is: buy } } } }) count(selectWhere: { ge: "100" }) } } } { "network": "eth" } ```
![DEXrabbit's Top Gainers table for Ethereum pairs with last price, 1-hour change, daily volume and daily trades](https://github.com/user-attachments/assets/9b501fe8-fb44-4796-a3d4-4084f230e626) You can check the data here on [DEXrabbit](https://dexrabbit.bitquery.io/eth). ## Top Bought tokens Tokens ranked by USD bought. Buys are the rows where `Side.Type`, the counter-side, is `sell`, and the `PriceAsymmetry` filter keeps mispriced trades out of the totals.
Tokens ranked by USD bought, with variables ```graphql query timeDiagram($network: evm_network) { EVM(network: $network) { DEXTradeByTokens( orderBy: { descendingByField: "buy" } limit: { count: 100 } where: { Trade: { PriceAsymmetry: { lt: 0.1 } } } ) { Trade { Currency { Symbol Name SmartContract } } buy: sum( of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: sell } } } } ) sell: sum( of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: buy } } } } ) } } } { "network": "eth" } ```
![DEXrabbit's Top Bought table for Ethereum tokens with USD bought and sold](https://github.com/user-attachments/assets/ef9e8091-0460-4208-841e-4595269d5b84) You can check the data here on [DEXrabbit](https://dexrabbit.bitquery.io/eth). ## Top Sold tokens Tokens ranked by USD sold, where sales are the rows with `Side.Type` set to `buy`.
Tokens ranked by USD sold, with variables ```graphql query timeDiagram($network: evm_network) { EVM(network: $network) { DEXTradeByTokens( orderBy: { descendingByField: "sell" } limit: { count: 100 } where: { Trade: { PriceAsymmetry: { lt: 0.1 } } } ) { Trade { Currency { Symbol Name SmartContract } } buy: sum( of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: sell } } } } ) sell: sum( of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: buy } } } } ) } } } { "network": "eth" } ```
You can check the data here on [DEXrabbit](https://dexrabbit.bitquery.io/eth). ## Latest Token Trades In `DEXTrades` on EVM chains, `Buy` and `Sell` are the pool's side of the trade ([DEXTrades cube](/docs/cubes/dextrades)): `buyside` below holds trades where the pool received the token, that is, traders sold it, and `sellside` trades where traders bought it.
Buy side and sell side of one token's trades (fields omitted) ```graphql { EVM(dataset: archive, network: eth) { buyside: DEXTrades( limit: { count: 10 } orderBy: { descending: Block_Time } where: { Trade: { Buy: { Currency: { SmartContract: { is: "0x5283d291dbcf85356a21ba090e6db59121208b44" } } } } } ) { /* fields */ } sellside: DEXTrades( limit: { count: 10 } orderBy: { descending: Block_Time } where: { Trade: { Sell: { Currency: { SmartContract: { is: "0x5283d291dbcf85356a21ba090e6db59121208b44" } } } } } ) { /* fields */ } } } ```
The IDE has the [full latest-trades query with every field](https://ide.bitquery.io/latest-trades-for-a-token---both-buy-and-sell). ## Token trade from a specific DEX
Uniswap v3 trades in which traders sold WETH (fields omitted) ```graphql { EVM(dataset: archive, network: eth) { buyside: DEXTrades( limit: { count: 5 } orderBy: { descending: Block_Time } where: { Trade: { Buy: { Currency: { SmartContract: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } } Dex: { ProtocolName: { is: "uniswap_v3" } } } } ) { /* fields */ } } } ```
The IDE has the [full DEX-filtered version](https://ide.bitquery.io/token-trades-for-a-specific-DEX_1). ## Subscribe to new token trades (WebSocket)
Subscription: new WETH trades each block (fields omitted) ```graphql subscription { EVM(network: eth, trigger_on: head) { buyside: DEXTrades( orderBy: { descending: Block_Time } where: { Trade: { Buy: { Currency: { SmartContract: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } } } } ) { /* fields */ } sellside: DEXTrades( orderBy: { descending: Block_Time } where: { Trade: { Sell: { Currency: { SmartContract: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } } } } ) { /* fields */ } } } ```
The IDE has the [full subscription](https://ide.bitquery.io/latest-token-trades-subscription). ## OHLC in USD of a Token Hourly open, high, low and close prices in USD for USDT, from its trades against WETH.
Hourly USD candles for USDT ```graphql { EVM(network: eth, dataset: realtime) { DEXTradeByTokens( orderBy: { descendingByField: "Block_testfield" } where: { Trade: { Currency: { SmartContract: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } } PriceAsymmetry: { lt: 0.1 } Side: { Currency: { SmartContract: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } } } } limit: { count: 10 } ) { Block { testfield: Time(interval: { in: hours, count: 1 }) } volume: sum(of: Trade_Amount) Trade { high: PriceInUSD(maximum: Trade_PriceInUSD) low: PriceInUSD(minimum: Trade_PriceInUSD) open: PriceInUSD(minimum: Block_Number) close: PriceInUSD(maximum: Block_Number) } count } } } ```
## Get Token Metadata
Name, symbol and decimals of a token ```graphql query MyQuery { EVM(network: eth, dataset: combined) { DEXTradeByTokens( limit: { count: 1 } orderBy: { descending: Block_Time } where: { Trade: { Currency: { SmartContract: { is: "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE" } } } } ) { Trade { Currency { Name Symbol SmartContract ProtocolName HasURI Fungible Decimals } } } } } ```
## Top Buyers of a Token
Ten largest buyers of a token by USD ```graphql { EVM { DEXTradeByTokens( orderBy: { descendingByField: "bought" } limit: { count: 10 } where: { Trade: { Currency: { SmartContract: { is: "0x53E0bca35eC356BD5ddDFebbD1Fc0fD03FaBad39" } } } } ) { Trade { Buyer Currency { Symbol Name SmartContract } } bought: sum( of: Trade_Side_AmountInUSD if: { Trade: { Side: { Type: { is: sell } } } } ) } } } ```
## Top Sellers of a Token
Ten largest sellers of a token by USD ```graphql { EVM { DEXTradeByTokens( orderBy: { descendingByField: "sold" } limit: { count: 10 } where: { Trade: { Currency: { SmartContract: { is: "0x53E0bca35eC356BD5ddDFebbD1Fc0fD03FaBad39" } } } } ) { Trade { Buyer Currency { Symbol Name SmartContract } } sold: sum( of: Trade_Side_AmountInUSD if: { Trade: { Side: { Type: { is: buy } } } } ) } } } ```
## Get trading volume, buy volume, sell volume of a token This returns the traded, buy and sell volume in USD of BNB's ERC-20 contract on Ethereum (`0xB8c77482e45F1F44dE1745F52C74426C631bDD52`), across every DEX, over the last 24 hours. `PriceAsymmetry: { lt: 0.1 }` drops mispriced trades, which would otherwise skew the USD sums.
24-hour traded, buy and sell volume of one token ```graphql query MyQuery { EVM { DEXTradeByTokens( where: { Trade: { Currency: { SmartContract: { is: "0xB8c77482e45F1F44dE1745F52C74426C631bDD52" } } PriceAsymmetry: { lt: 0.1 } } TransactionStatus: { Success: true } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Trade { Currency { Name Symbol SmartContract } } traded_volume_in_usd: sum(of: Trade_Side_AmountInUSD) sell_volume_in_usd: sum( of: Trade_Side_AmountInUSD if: { Trade: { Side: { Type: { is: buy } } } } ) buy_volume_in_usd: sum( of: Trade_Side_AmountInUSD if: { Trade: { Side: { Type: { is: sell } } } } ) } } } ```
## Stablecoin Peg Health (Latest Price Across All DEXs) Get the **latest price of a stablecoin across all EVM DEXs**. Returns one row per DEX protocol with the most recent trade price. Useful for monitoring peg health and identifying which exchanges have the stablecoin trading closest to its target peg (e.g., $1.00 for USD-pegged stablecoins). Browse multi-chain stablecoin DEX prices on [DEXrabbit's Stablecoins category](https://dexrabbit.bitquery.io/categories/stablecoins). [Run in Bitquery IDE](https://ide.bitquery.io/evm-peg-health_1)
Latest stablecoin price on each DEX ```graphql { EVM(network: eth) { DEXTradeByTokens( orderBy: { descending: Block_Time } limitBy: { count: 1, by: Trade_Dex_SmartContract } where: { Trade: { Currency: { SmartContract: { is: "CZzgUBvxaMLwMhVSLgqJn3npmxoTo6nzMNQPAnwtHF3s" } } } } ) { Block { Time } Transaction { Hash } Trade { Amount AmountInUSD Price PriceInUSD Currency { Name SmartContract Symbol } Dex { ProtocolName ProtocolFamily SmartContract } Side { Type Currency { Name SmartContract Symbol } AmountInUSD Amount } } } } } ```
## Realised PnL, buy volume, sell volume Get realised PnL, buy volume, and sell volume for a token on EVM of a trader for over a time window. [Run in Bitquery IDE](https://ide.bitquery.io/Realised-Pnl-Buy-volume-Sell-Volume-Ethereum)
One trader's realised PnL and buy and sell volume, with variables ```graphql query ($trader: String) { EVM(network: eth, dataset: combined) { DEXTradeByTokens( where: { Trade: { Currency: { SmartContract: { is: "0x80029DBba7FA84bb16724a9fF6eE11c367D2FcfB" } } } any: [ { Trade: { Buyer: { is: $trader } } } { Trade: { Seller: { is: $trader } } } ] TransactionStatus: { Success: true } Block: { Date: { since: "2026-03-11", till: "2026-03-13" } } } ) { Trade { Currency { Name Symbol SmartContract } } buy_volume_usd: sum( of: Trade_Side_AmountInUSD if: { Trade: { Buyer: { is: $trader }, Side: { Type: { is: sell } } } } ) sell_volume_usd: sum( of: Trade_Side_AmountInUSD if: { Trade: { Seller: { is: $trader }, Side: { Type: { is: buy } } } } ) buy_volume: sum( of: Trade_Amount if: { Trade: { Buyer: { is: $trader }, Side: { Type: { is: sell } } } } ) sell_volume: sum( of: Trade_Amount if: { Trade: { Seller: { is: $trader }, Side: { Type: { is: buy } } } } ) PnL: calculate(expression: "$sell_volume_usd - $buy_volume_usd") trades: count } } } ``` ```json { "trader": "0x0a62Bd9Ee12119a5aC4807C0970fed8B71E83163" } ```
## Getting OHLC and Distinct Buys/Sells Daily OHLC, priced in WBNB, with buy and sell counts for Aave Token against WBNB on BNB Chain from 1 July to 1 August 2023. A buy is a row where `Side.Type` is `sell`; `buyers` and `sellers` count the distinct accounts that sent those swaps.
Daily candles with buy and sell counts ```graphql { EVM(dataset: archive, network: bsc) { daily: DEXTradeByTokens( limit: { count: 30 } orderBy: { descendingByField: "Block_time_field" } where: { Trade: { Side: { Currency: { SmartContract: { is: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c" } } Amount: { ge: "0" } } Currency: { SmartContract: { is: "0xfb6115445bff7b52feb98650c87f44907e58f802" } } PriceAsymmetry: { lt: 0.1 } } Block: { Date: { since: "2023-07-01", till: "2023-08-01" } } } ) { Block { time_field: Time(interval: { in: days, count: 1 }) } volume: sum(of: Trade_Amount) buyers: count( distinct: Transaction_From if: { Trade: { Side: { Type: { is: sell } } } } ) sellers: count( distinct: Transaction_From if: { Trade: { Side: { Type: { is: buy } } } } ) distinctTransactions: count(distinct: Transaction_Hash) total_buys: count(if: { Trade: { Side: { Type: { is: sell } } } }) total_sales: count(if: { Trade: { Side: { Type: { is: buy } } } }) total_count: count Trade { Currency { Name } Side { Currency { Name } } high: Price(maximum: Trade_Price) low: Price(minimum: Trade_Price) open: Price(minimum: Block_Number) close: Price(maximum: Block_Number) } } } } ```
## Get Least Traded Token
The 10 least traded tokens in one November 2023 week ```graphql query MyQuery { EVM(dataset: archive, network: eth) { DEXTradeByTokens( limit: { count: 10 } where: { Block: { Time: { after: "2023-11-20T00:00:00Z" before: "2023-11-27T00:00:00Z" } } } orderBy: { ascendingByField: "count" } ) { Trade { Currency { Name SmartContract } } count } } } ```
## First X Buyers of a Token The first 10 accounts to buy BLUR. Buyers of a token sit on the pool's `Sell` side, where the pool paid the token out, so the filter is on `Trade.Sell.Currency`. `Trade.Sell.Buyer` is often a router, so the buyer is `Transaction.From`.
First 10 buyers of BLUR ```graphql { EVM(dataset: archive, network: eth) { buyside: DEXTrades( limit: { count: 10 } limitBy: { by: Transaction_From, count: 1 } orderBy: { ascending: Block_Time } where: { Trade: { Sell: { Currency: { SmartContract: { is: "0x5283d291dbcf85356a21ba090e6db59121208b44" } } } } } ) { Block { Number Time } Transaction { From To Hash } Trade { Sell { Amount Buyer Currency { Name Symbol } Seller Price } } } } } ```
## Volume of Multiple Tokens Across Different Chains Get volume and price change data for multiple tokens trading on different chains (Solana, Ethereum, BSC, Tron) in a single query using the Trading API. Returns volume for 1h, 4h, and 24h periods, plus price change percentages for the same intervals. :::note EVM address format For **EVM chains** (Ethereum, BSC, etc.) in the Trading API, use **all lowercase addresses** in the token ID format (e.g., `bid:eth:0x...` with lowercase hex). Mixed-case addresses may not match. ::: [Run in Bitquery IDE](https://ide.bitquery.io/volume-of-a-token_1)
Volume and price change for tokens on four chains ```graphql query { TokenAsBase: Trading { Pairs( where: { Interval: { Time: { Duration: { eq: 1 } } } Block: { Time: { since_relative: { hours_ago: 24 } } } Price: { IsQuotedInUsd: true } Token: { Id: { in: [ "bid:solana:CZzgUBvxaMLwMhVSLgqJn3npmxoTo6nzMNQPAnwtHF3s" "bid:eth:0xfaf0cee6b20e2aaa4b80748a6af4cd89609a3d78" "bid:bsc:0xfaf0cee6b20e2aaa4b80748a6af4cd89609a3d78" "bid:tron:TXL6rJbvmjD46zeN1JssfgxvSo99qC8MRT" ] } } Market: { Protocol: { notIn: ["jupiter", "dex_solana_v3"] } } } ) { Token { Name Symbol Id } Price { Average { currentPrice: Mean(maximum: Block_Time) H1Ago: Mean( maximum: Block_Time if: { Block: { Time: { till_relative: { hours_ago: 1 } } } } ) H4Ago: Mean( maximum: Block_Time if: { Block: { Time: { till_relative: { hours_ago: 4 } } } } ) H24Ago: Mean( minimum: Block_Time if: { Block: { Time: { after_relative: { hours_ago: 24 } } } } ) } } Price_change_1h: calculate( expression: "( ( $Price_Average_currentPrice - $Price_Average_H1Ago ) / $Price_Average_H1Ago ) * 100" ) Price_change_4h: calculate( expression: "( ( $Price_Average_currentPrice - $Price_Average_H4Ago ) / $Price_Average_H4Ago ) * 100" ) Price_change_24h: calculate( expression: "( ( $Price_Average_currentPrice - $Price_Average_H24Ago ) / $Price_Average_H24Ago ) * 100" ) v1h: sum( of: Volume_Usd if: { Block: { Time: { since_relative: { hours_ago: 1 } } } } ) v4h: sum( of: Volume_Usd if: { Block: { Time: { since_relative: { hours_ago: 4 } } } } ) v24h: sum(of: Volume_Usd) } } } ```
--- ## Trader-Focused Trade APIs (with USD Price, Market Cap & Supply) The queries below use the **[Trades cube](/docs/trading/crypto-trades-api/trades-api/)** (`Trading { Trades }`) which is trader-focused and provides reliable USD prices including for all tokens. See [DEXTrades vs DEXTradeByTokens vs Trades cube](/docs/cubes/dextrades-dextradebytokens-trading-trades) for when to use which. ### Get All DEX Trades on Ethereum With Price, Market Cap, and Supply Stream **all Ethereum DEX trades** in real time with **USD price**, **market cap**, **FDV**, **circulating supply**, and **transaction fee** data. Filter by **`Pair.Market.Network: Ethereum`** to capture every swap across all Ethereum DEXs in a single subscription. You can run this subscription [in the Bitquery IDE](https://ide.bitquery.io/All-trades-on-Ethereum-with-Price-Marketcap-supply).
Subscription: Ethereum trades with USD price, market cap and supply ```graphql subscription { Trading { Trades(where: { Pair: { Market: { Network: { is: "Ethereum" } } } }) { Side Supply { MaxSupply TotalSupply FullyDilutedValuationUsd CirculatingSupply MarketCap } Trader { Address } TransactionHeader { Fee FeePayer Sender To Hash Index } Amounts { Base Quote } AmountsInUsd { Base Quote } Block { Date Time Timestamp } Pair { Currency { Id Name Symbol } Market { Address Program Network } QuoteCurrency { Id Name Symbol } Token { Address Id IsNative Symbol TokenId Network } QuoteToken { Address Id IsNative Symbol TokenId Network } } Price PriceInUsd } } } ```
### Top Traders by PnL for a Specific Pool (Last 30 Minutes) Rank traders by **`PnL`** on one pool: filter **`Pair.Market.Program`** (the pool; for Uniswap v3, `Pair.Market.Address` is the factory and would cover every v3 pool), last **30 minutes**, **`limit: 10`**, and **`orderBy`** **`PnL`** descending. Useful for **leaderboards**, **smart-money screens**, and **pool-specific trader analytics**. You can run this query [in the Bitquery IDE](https://ide.bitquery.io/Top-Traders-by-PnL-of-a-specific-eth-pool_1).
Ten traders with the highest PnL in one pool over 30 minutes ```graphql { Trading { Trades( limit: { count: 10 } orderBy: { descendingByField: "PnL" } where: { Block: { Time: { since_relative: { minutes_ago: 30 } } } Pair: { Market: { Network: { is: "Ethereum" } Program: { is: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640" } } } } ) { Trader { Address } Amount_Bought: sum(of: AmountsInUsd_Base, if: { Side: { is: "Buy" } }) Amount_Sold: sum(of: AmountsInUsd_Base, if: { Side: { is: "Sell" } }) Amount_Bought_native: sum(of: Amounts_Base, if: { Side: { is: "Buy" } }) Amount_Sold_native: sum(of: Amounts_Base, if: { Side: { is: "Sell" } }) PnL: calculate(expression: "$Amount_Sold - $Amount_Bought") buys: count(if: { Side: { is: "Buy" } }) sells: count(if: { Side: { is: "Sell" } }) } } } ```
--- ## Video Tutorial | How to get Token Trade Stats for EVM chains like DexScreener shows --- ## Ethereum Trades Of An Address API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/trades-of-an-address-api/ Ethereum Trades Of An Address API: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. # Address Trades API ## How do I get trades made by a specific wallet on a DEX? This GraphQL query retrieves the latest trades executed by a particular maker on the Ethereum network. You can view the query in the IDE [here](https://ide.bitquery.io/latest-trades-by-market-maker) On **EVM**, use the chain-specific **DEXTrades** cube (GraphQL: `EVM { DEXTrades }`) or **`DEXTradeByTokens`** for a token-centric view. Filter by the wallet as transaction sender or as **`Trade.Sender`** / buyer–seller fields depending on protocol. The [DEXTrades example](#latest-trades-by-address) filters `Transaction.From` on Ethereum; adjust `network`, `dataset`, and DEX filters for BSC, Base, etc. For **Solana**, see [Solana DEX Trades API](/docs/blockchain/Solana/solana-dextrades/). ### Stream wallet swaps on Ethereum [Crypto Trades API](/docs/trading/crypto-trades-api/trades-api): filter **`Pair.Market.Network: Ethereum`** and **`Trader.Address`**. More examples: [Trades API](/docs/trading/crypto-trades-api/trades-api), [trader + token (IDE)](https://ide.bitquery.io/trades-of-a-specific-trader-of-a-specific-token). [Bitquery IDE](https://ide.bitquery.io) ```graphql subscription { Trading { Trades( where: { Pair: { Market: { Network: { is: "Ethereum" } } } Trader: { Address: { is: "0x9d6581468F04e5E55876a2660b5AeAbC12e3EFa0" } } } ) { Side Trader { Address } AmountsInUsd { Base Quote } TransactionHeader { Hash } Block { Time } Pair { Token { Symbol Address } QuoteToken { Symbol Address } } PriceInUsd } } } ``` ### Latest trades by address The query below uses the chain-specific **DEXTrades** cube on EVM (`EVM { DEXTrades }` with `network` and `dataset` for your chain). ```graphql query MyQuery { EVM(dataset: combined, network: eth) { DEXTrades( where: {Transaction: {From: {is: "0x9d6581468F04e5E55876a2660b5AeAbC12e3EFa0"}}} limit: {count: 10} orderBy: {descending: Block_Number} ) { Transaction { Hash From To } Trade { Sender Buy { Buyer Seller Currency { Name SmartContract } Amount Price } Sell { Currency { Name SmartContract } Buyer Amount Seller Price } } Block { Number Time } } } } ``` **Parameters** - `limit`: retrieve only 10 trades - `orderBy`: sort the trades by Block Number in descending order - `where`: retrieve trades where the address was a maker **Returned Data** For each trade, the query retrieves the following data: - `Block`: block number and timestamp of the block in which the trade occurred. - `Transaction`: addresses of the transaction sender and receiver, and the transaction hash. - `Trade`: details of the trade, including the amount of the currency bought and sold, the buyer and seller addresses, the currency name, symbol, and smart contract address, and the price of the trade. ## Buys and Sells of a Specific Token Pair by an Address You can view the query in the IDE [here](https://ide.bitquery.io/latest_buys_and_sell_) ```graphql query MyQuery { EVM(dataset: combined, network: eth) { Sells: DEXTrades( where: {Transaction: {From: {is: "0x9d6581468F04e5E55876a2660b5AeAbC12e3EFa0"}}, Trade: {Buy: {Currency: {SmartContract: {is: "0x7E744BBB1a49A44dfCC795014a4BA618E418FbBE"}}}, Dex: {SmartContract: {is: "0x8C13d5a6635216513EbFB4483397bE14D494aD76"}}}} limit: {count: 10} orderBy: {descending: Block_Number} ) { Transaction { Hash From To } Block{ Time Number } Trade { Sender Buy { Buyer Seller Currency { Name SmartContract } Amount } } } Buys: DEXTrades( where: {Transaction: {From: {is: "0x9d6581468F04e5E55876a2660b5AeAbC12e3EFa0"}}, Trade: {Sell: {Currency: {SmartContract: {is: "0x7E744BBB1a49A44dfCC795014a4BA618E418FbBE"}}}, Dex: {SmartContract: {is: "0x8C13d5a6635216513EbFB4483397bE14D494aD76"}}}} limit: {count: 10} orderBy: {descending: Block_Number} ) { Transaction { Hash From To } Block{ Time Number } Trade { Sell { Buyer Seller Currency { Name SmartContract } Amount } } } } } ``` The "EVM" field contains two sub-queries: "Buys" and "Sells." The "Buys" sub-query retrieves the 10 most recent trades where the specified address was the maker and the token was purchased. The "Sells" sub-query retrieves the 10 most recent trades where the specified address was the maker and the token was sold. **Parameters** - `limit`: retrieve only 10 trades - `orderBy`: sort the trades by Block_Number in descending order - `where`: retrieve trades where the maker address matches "0x9d6581468F04e5E55876a2660b5AeAbC12e3EFa0" and token SmartContract and pair address is "0x7E744BBB1a49A44dfCC795014a4BA618E418FbBE" and "0x8C13d5a6635216513EbFB4483397bE14D494aD76" respectively **Returned Data** For each trade, the query retrieves the following data: - `Block`: block number and timestamp of the block in which the trade occurred. - `Transaction`: The sender, reciever and the transaction hash - `Trade`: details of the trade, including the amount of the currency bought and sold, the buyer and seller addresses, the currency name, symbol, and smart contract address, and the price of the trade. ## Subscribe to latest trades for a given address You can check this query [here](https://ide.bitquery.io/Real-time-trades-of-an-ethereum-address). ```graphql subscription { EVM(network: eth) { DEXTrades( orderBy: { descending: Block_Time } where: { any: [ { Trade: { Buy: { Buyer: { is: "0x152a04d9fde2396c01c5f065a00bd5f6edf5c88d" } } } } { Trade: { Buy: { Seller: { is: "0x152a04d9fde2396c01c5f065a00bd5f6edf5c88d" } } } } { Transaction: { From: { is: "0x152a04d9fde2396c01c5f065a00bd5f6edf5c88d" } } } ] } ) { Block { Number Time } Transaction { From To Hash } Trade { Buy { Amount Buyer Currency { Name Symbol SmartContract } Seller Price } Sell { Amount Currency { Name SmartContract Symbol } Price } } } } } ``` ## Trades Where the Address is Buyer OR Seller The below query gives you trades where the specified address is either as a buyer or a seller. This is achieved by utilizing the `any` filter, which acts as an OR condition to encompass both buyer and seller roles in the results. You can find the query [here](https://ide.bitquery.io/Address-is-Buyer-or-Seller-V2) ```graphql query MyQuery { EVM(dataset: archive, network: eth) { DEXTrades( where: {any: [{Trade: {Buy: {Buyer: {is: "0xacefce78e31332cf2d1b9e770d609c31d26afc09"}}}}, {Trade: {Buy: {Seller: {is: "0xacefce78e31332cf2d1b9e770d609c31d26afc09"}}}}]} limit: {count: 10} orderBy: {descending: Block_Time} ) { Trade { Buy { Buyer Amount Currency { Name } } Dex { ProtocolName } Sell { Buyer Price Currency { Name } } } Transaction { Hash } } } } ``` ## Top Trader for a given token for a pair (Trade's PnL analysis) To get top traders of a given token and analyze their profit and loss, you can use the following query. Run this query [using this link](https://ide.bitquery.io/Top-traders-in-eth_1). ```graphql query TopTraders($token: String) { EVM(network: eth, dataset: combined) { DEXTradeByTokens( orderBy: {descendingByField: "volume"} limit: {count: 20} where: {Trade: {Currency: {SmartContract: {is: $token}}}, TransactionStatus: {Success: true}} ) { Transaction { From } Trade { Dex { ProtocolName ProtocolFamily } Currency { Symbol Name SmartContract } Side { Currency { Name Symbol SmartContract } } } bought: sum( of: Trade_Side_AmountInUSD if: {Trade: {Side: {Type: {is: sell}}}} selectWhere: {gt: "0"} ) sold: sum( of: Trade_Side_AmountInUSD if: {Trade: {Side: {Type: {is: buy}}}} selectWhere: {gt: "0"} ) volume: sum(of: Trade_Amount) volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } variables: { "token": "0xC90242Cd9959b7Be6EC01B5e99702Ee21161f3Ad" } ``` ## Total Volume, Buy Volume, Sell Volume, and PnL for a Trader on a Specific Token This query returns comprehensive trading statistics for a specific trader's activity on a particular token, including total volume, buy/sell volumes in both token amounts and USD, trade counts, and PnL calculations over the last 24 hours. You can run this query [here](https://ide.bitquery.io/total-volume-buy-volume-sell-volume-PnL). ```graphql query MyQuery($trader: String, $token: String) { EVM(dataset: combined, network: eth) { DEXTradeByTokens( where: { Block: { Time: { since_relative: { hours_ago: 24 } } } Trade: { Currency: { SmartContract: { is: $token } } } Transaction: { From: { is: $trader } } } ) { Block { last_active_time: Time(maximum: Block_Time) } total_volume: sum(of: Trade_Amount) buy_volume: sum( of: Trade_Amount if: { Trade: { Side: { Type: { is: sell } } } } ) sell_volume: sum( of: Trade_Amount if: { Trade: { Side: { Type: { is: buy } } } } ) total_volume_usd: sum(of: Trade_Side_AmountInUSD) sell_volume_usd: sum( of: Trade_Side_AmountInUSD if: { Trade: { Side: { Type: { is: buy } } } } ) buy_volume_usd: sum( of: Trade_Side_AmountInUSD if: { Trade: { Side: { Type: { is: sell } } } } ) total_buys: count( distinct: Transaction_Hash if: { Trade: { Side: { Type: { is: sell } } } } ) total_sells: count( distinct: Transaction_Hash if: { Trade: { Side: { Type: { is: buy } } } } ) PnL_usd: calculate(expression: "$sell_volume_usd - $buy_volume_usd") } } } ``` ```json { "token": "0xacba65D610B066443CB211E120835315361e4FCA", "trader": "0x782c362fbf71f939445e6902a064f7e9384f47e2" } ``` --- ## Ethereum Trading Pairs API: Every Pool a Token Trades In URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/get-trading-pairs-of-token/ Every trading pair of an Ethereum token with Bitquery GraphQL: pools across DEXs, pools on one protocol, pair stats, reserves, the tokens behind a pool. # Ethereum Trading Pairs API: Every Pool a Token Trades In A token trades in many places at once: a Uniswap v3 pool against WETH, a v2 pair, a v4 pool, maybe a Curve or Balancer pool. To follow all of its trading you first need that list, and the `DEXTradeByTokens` cube produces it in one query, because every swap is stored once per token with the other token and the pool alongside. From there a pair's stats, a pool's reserves and the two tokens behind a pool address are each one more query. Every example runs in the [IDE](https://ide.bitquery.io). Queries on the `archive` or `combined` dataset need an archive add-on; the free trial is real-time only. The worked token is BLUR, `0x5283d291dbcf85356a21ba090e6db59121208b44`, whose pools are spread across Uniswap v2, v3 and v4. ## Every pair of a token across all DEXs Group by the other token and the pool over a month on the `combined` dataset. Each row is one pool with its protocol, trade count and USD volume in the window. Saved query [here](https://ide.bitquery.io/Pair-tokens-for-BLUR-token-for-all-DEXs_1). ```graphql { EVM(dataset: combined, network: eth) { DEXTradeByTokens( where: { Trade: { Currency: { SmartContract: { is: "0x5283d291dbcf85356a21ba090e6db59121208b44" } } } Block: { Time: { since_relative: { days_ago: 30 } } } } orderBy: { descendingByField: "trades" } limit: { count: 50 } ) { Trade { Side { Currency { Symbol SmartContract } } Dex { ProtocolName SmartContract } } trades: count volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } ``` `Dex.SmartContract` is the pool for v2 and v3 pairs and the PoolManager for Uniswap v4, where pools are told apart by `Trade.PoolId` instead. ## The pairs on one protocol Add the protocol name to the filter. The saved query used the Uniswap v3 factory as an owner filter; the protocol name does the same with less to remember. Saved query [here](https://ide.bitquery.io/pairs-of-blur-token-new-dataset_1). ```graphql { EVM(dataset: combined, network: eth) { DEXTradeByTokens( where: { Trade: { Currency: { SmartContract: { is: "0x5283d291dbcf85356a21ba090e6db59121208b44" } } Dex: { ProtocolName: { is: "uniswap_v3" } } } Block: { Time: { since_relative: { days_ago: 30 } } } } orderBy: { descendingByField: "trades" } limit: { count: 20 } ) { Trade { Side { Currency { Symbol SmartContract } } Dex { SmartContract } } trades: count } } } ``` ## Stats of one pair Fix both tokens and a window: trades, distinct buyers and sellers, USD volume, and how much of the token was bought and sold. `Side.Type` describes the counter-side of each trade, so the token was bought where the side was sold, which is why the two conditions look reversed. ```graphql { EVM(network: eth, dataset: combined) { DEXTradeByTokens( where: { Trade: { Currency: { SmartContract: { is: "0x5283d291dbcf85356a21ba090e6db59121208b44" } } Side: { Currency: { SmartContract: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { trades: count buyers: uniq(of: Trade_Buyer) sellers: uniq(of: Trade_Seller) volumeUsd: sum(of: Trade_Side_AmountInUSD) bought: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: sell } } } }) sold: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: buy } } } }) } } } ``` ## Reserves of a pool A pool's reserves are its token balances. The `Balances` cube returns them for the pool address; the example is the Uniswap v3 USDC/USDT pool, `0x7858E59e0C01EA06Df3aF3D20aC7B0003275D4Bf`. Saved query [here](https://ide.bitquery.io/liquidity-of-token-pair-on-ethereum). ```graphql { EVM(dataset: combined, network: eth) { Balances( where: { Balance: { Address: { is: "0x7858E59e0C01EA06Df3aF3D20aC7B0003275D4Bf" } } Currency: { SmartContract: { in: [ "0xdAC17F958D2ee523a2206206994597C13D831ec7" "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" ] } } } orderBy: { descending: Balance_Amount } ) { Currency { Symbol SmartContract } Balance { Amount } } } } ``` For reserves that update on every swap with USD values and spot prices, use the [DEXPools cube](/docs/cubes/evm-dexpool/). ## The two tokens behind a pool address One trade from the pool names both sides. Saved query [here](https://ide.bitquery.io/tokens-in-a-given-pair-token). ```graphql { EVM(dataset: combined, network: eth) { DEXTrades( limit: { count: 1 } orderBy: { descending: Block_Time } where: { Trade: { Dex: { SmartContract: { is: "0x7858E59e0C01EA06Df3aF3D20aC7B0003275D4Bf" } } } } ) { Trade { Dex { ProtocolName } Buy { Currency { Symbol SmartContract } } Sell { Currency { Symbol SmartContract } } } } } } ``` ## Related pages - [Ethereum DEX trades API](/docs/blockchain/Ethereum/dextrades/dex-api) - [Uniswap v4 on Ethereum](/docs/blockchain/Ethereum/dextrades/uniswap-v4-api) - [DEXPools cube](/docs/cubes/evm-dexpool/) - [Balances and Holders cubes](/docs/cubes/balances-cube) --- ## Ethereum Transaction Balance Tracker URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-transaction-balance-tracker/ Ethereum Transaction Balance Tracker: stream Ethereum balance changes with reason codes using Bitquery GraphQL subscriptions. # Ethereum Transaction Balance Tracker The Ethereum Transaction Balance Tracker API provides real-time balance updates for all addresses involved in transactions on the Ethereum blockchain, including detailed information about the reason for each balance change. ## Subscribe to All Transaction Balances This subscription provides real-time balance updates for all addresses involved in transactions on the Ethereum network. Try the API [here](https://ide.bitquery.io/Subscribe-to-All-Transaction-Balances). ```graphql subscription { EVM(network: eth) { TransactionBalances { Block { Time } TokenBalance { Currency { Symbol HasURI SmartContract } PreBalance PostBalance Address BalanceChangeReasonCode TotalSupplyInUSD TotalSupply TokenOwnership { Owns Id } PostBalanceInUSD } Transaction { Hash } } } } ``` ## Subscribe to Transaction Balances for a Specific Address This subscription filters transaction balances for a specific address. Try the API [here](https://ide.bitquery.io/Subscribe-to-Transaction-Balances-for-a-Specific-Address). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { Address: { is: "0xYourAddressHere" } } } ) { Block { Time } TokenBalance { Currency { Symbol HasURI SmartContract } PreBalance PostBalance Address BalanceChangeReasonCode TotalSupplyInUSD TotalSupply TokenOwnership { Owns Id } PostBalanceInUSD } Transaction { Hash } } } } ``` ## Latest native balance of an address This API gives you latest balance of a specific address (here in example `0xd194daef0cd90675a3b823fcda248f76fccb49f3`) for the native currency. Try it out [here](https://ide.bitquery.io/Latest-native-balance-of-an-address). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 1 } orderBy: { descending: Block_Time } where: { TokenBalance: { Address: { is: "0xd194daef0cd90675a3b823fcda248f76fccb49f3" } Currency: { Native: true } } } ) { Block { Time } TokenBalance { Currency { Symbol HasURI SmartContract } PreBalance PostBalance Address BalanceChangeReasonCode TotalSupplyInUSD TotalSupply TokenOwnership { Owns Id } PostBalanceInUSD } Transaction { Hash } } } } ``` ## Latest balance of an address for a specific token This API gives you latest balance of a specific address (here in example `0xd194daef0cd90675a3b823fcda248f76fccb49f3`) for a specific token (here we have taken example of USDC `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`). Try it out [here](https://ide.bitquery.io/Latest-balance-of-an-address-for-a-specific-token). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 1 } orderBy: { descending: Block_Time } where: { TokenBalance: { Address: { is: "0xd194daef0cd90675a3b823fcda248f76fccb49f3" } Currency: { SmartContract: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } } } } ) { Block { Time } TokenBalance { Currency { Symbol HasURI SmartContract } PreBalance PostBalance Address BalanceChangeReasonCode TotalSupplyInUSD TotalSupply TokenOwnership { Owns Id } PostBalanceInUSD } Transaction { Hash } } } } ``` ## Latest liquidity of EVM Pool This API provides the latest liquidity information for multiple EVM pools in one API call. The example shows results for two pool addresses using a query updated to support multiple addresses. You can try 500 as well,just put them as a list in `where` clause. Try it out [here](https://ide.bitquery.io/latest-liquidity-of-multiple-pools#). ```graphql { EVM(network: base) { TransactionBalances( limitBy: { by: TokenBalance_Address, count: 2 } orderBy: { descendingByField: "TokenBalance_PostBalanceInUSD" } where: { TokenBalance: { Address: { in: [ "0x3f0296BF652e19bca772EC3dF08b32732F93014A" "0x22AEe3699b6A0fEd71490C103Bd4E5f3309891D5" ] } } } ) { TokenBalance { Currency { Symbol HasURI SmartContract } PostBalance(maximum: Block_Time) PostBalanceInUSD(maximum: Block_Time) Address } } } } ``` ## Latest Supply and Marketcap of a specific token on EVM This API gives you latest Supply and Marketcap of a token on EVM (here as example we have taken BITGET Token `0x54D2252757e1672EEaD234D27B1270728fF90581` ). Try it out [here](https://ide.bitquery.io/Total-Supply-and-onchain-Marketcap-of-a-specific-token). ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 1 } orderBy: { descending: Block_Time } where: { TokenBalance: { Currency: { SmartContract: { is: "0x54D2252757e1672EEaD234D27B1270728fF90581" } } } } ) { Block { Time Number } TokenBalance { Currency { Symbol HasURI SmartContract } TotalSupplyInUSD TotalSupply } } } } ``` --- ## Ethereum Transaction Balance Tracker API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/transaction-balance-tracker/ Ethereum Transaction Balance Tracker API: stream Ethereum balance changes with reason codes using Bitquery GraphQL subscriptions. # Ethereum Transaction Balance Tracker API - Complete Guide ## What is Transaction Balance Tracker? The **Ethereum Transaction Balance Tracker API** provides real-time balance updates for all addresses involved in transactions on the Ethereum blockchain. Unlike traditional balance APIs that only show current balances, our Transaction Balance Tracker captures every balance change with detailed information about the reason for each change, making it perfect for building comprehensive transaction monitoring, portfolio tracking, and blockchain analytics applications. Our Transaction Balance Tracker APIs track balance changes across different scenarios including regular transactions, validator rewards, miner rewards, MEV activities, and contract self-destruct events. Each balance change is enriched with reason codes, pre/post balances, USD values, and transaction context. ## Key Features - **Real-time Balance Updates**: Stream balance changes as they happen via GraphQL subscriptions - **Balance Change Reason Codes**: Understand why each balance changed (transfers, rewards, gas, self-destruct, etc.) - **Comprehensive Coverage**: Track native ETH, ERC-20 tokens, ERC-721, and ERC-1155 NFTs - **Historical Data**: Access complete historical balance change data since Ethereum genesis - **USD Values**: Get balance values in USD for portfolio tracking and analytics - **Multiple Use Cases**: Monitor validators, miners, MEV bots, self-destruct events, and more ## Getting Started New to Transaction Balance Tracker? Here's how to get started: 1. **[Create a free account](https://ide.bitquery.io/)** - Get instant access to our GraphQL IDE 2. **[Generate your API key](/docs/authorization/how-to-generate/)** - Required for API access 3. **[Run your first query](/docs/start/first-query/)** - Learn the basics in 5 minutes 4. **[Explore examples](#ethereum-transaction-balance-tracker-apis)** - Copy-paste ready queries below Need help crafting a query or subscription? Message us on [support](https://t.me/Bloxy_info). ## How is it different from regular Balance APIs? - Real-time streaming of all balance changes - Pre/post balance values for every change - Balance change reason codes explain why balance changed - Track all addresses in transactions automatically - Historical data with complete change history - Support for native currency, tokens, and NFTs ## Real-time Data & Streaming Get live Ethereum balance updates through our streaming solutions: - **GraphQL Subscriptions**: Convert any query to a live stream by changing `query` to `subscription` - **Kafka Streaming**: High-throughput streaming for enterprise applications See examples and code snippets [here](/docs/subscriptions/websockets/) for GraphQL subscription implementation, and learn about [Kafka streaming](/docs/streams/kafka-streaming-concepts/) for high-volume use cases. ## Ethereum Transaction Balance Tracker APIs ### [Ethereum Transaction Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-transaction-balance-tracker) The core Transaction Balance Tracker API provides real-time balance updates for all addresses involved in transactions on the Ethereum network, including detailed information about the reason for each balance change. Track native ETH, ERC-20 tokens, and NFTs with pre/post balances, USD values, and balance change reason codes. **Key Features:** - Subscribe to all transaction balances in real-time - Filter by specific addresses or tokens - Get balance change reason codes for native currency - Track ERC-20, ERC-721, and ERC-1155 tokens - Access pre and post balance values ### [Ethereum Transaction Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-transfer-balance-tracker) Transfer Balance Tracker API provides real-time balance updates for all addresses involved in transfer of Native Currency on the Ethereum network. **Key Features:** - Subscribe to all transfer balances in real-time - Filter by specific addresses - Access pre and post balance values ### [Ethereum Validator Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-validator-balance-tracker) Track Ethereum validator balances, staking rewards, and withdrawals from the beacon chain. Monitor validator activity including block rewards, withdrawal events, and transaction fee rewards. **Key Features:** - Track validator staking rewards (Code 2) - Monitor beacon chain withdrawals (Code 3) - Track transaction fee rewards (Code 5) - Filter by specific validator addresses - Real-time validator balance updates ### [Ethereum Gas Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-gas-balance-tracker) Track Ethereum balance changes for gas burn, unused gas returned for unused gas at the end of execution, and transaction tips. **Key Features:** - Track transaction tips (Code 5) - Track gas burnt (Code 6) - Track gas returned for unused gas at the end of execution (Code 7) ### [Ethereum Miner Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-miner-balance-tracker) Monitor Ethereum miner balances, mining rewards, uncle block rewards, and transaction fee rewards. Track historical and real-time mining activity across the Ethereum network. **Key Features:** - Track block mining rewards (Code 2) - Monitor uncle block rewards (Code 1) - Track transaction fee rewards (Code 5) - Filter by specific miner addresses - Historical mining reward data ### [Ethereum MEV Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-mev-balance-tracker) Track MEV (Maximal Extractable Value) related balance changes including transaction fee rewards, block builder rewards, and other MEV extraction activities. Monitor MEV bots and block builders in real-time. **Key Features:** - Track transaction fee rewards (Code 5) - Monitor block builder rewards - Filter by MEV bot or builder addresses - Track large MEV transactions - Aggregate MEV reward statistics ### [Ethereum Self-Destruct Balance Tracker](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-self-destruct-balance-api) Monitor contract self-destruct events, ephemeral contracts (like MEV bots), and security incidents. Track contracts that self-destruct and addresses that receive funds from self-destructed contracts. **Key Features:** - Track contract self-destruct events (Codes 12, 13, 14) - Monitor ephemeral MEV contracts - Track MEV builder payments - Security incident monitoring - Aggregate self-destruct statistics ### [Ethereum Token Balance API](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/token-balance-api) Track ERC-20 fungible token balances, total supply, and market capitalization for any address on Ethereum. Monitor token holdings, portfolio values, and token balance changes in real-time. **Key Features:** - Get latest token balance for an address - Retrieve all token balances for an address - Track token balance history over time - Get token total supply and market cap - Filter tokens by minimum balance threshold - Stream token balance updates in real-time - Monitor token balance changes by transaction ### [Ethereum NFT Balance API](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/nft-balance-api) Track ERC-721 and ERC-1155 non-fungible token balances, ownership, and token IDs for any address on Ethereum. Monitor NFT collections, ownership changes, and specific token ownership in real-time. **Key Features:** - Get latest NFT balance for an address - Retrieve all NFT collections for an address - Get NFT owner for specific token ID - Track NFT ownership history - Get NFT balances for multiple addresses - Stream NFT balance updates in real-time - Monitor NFT balance changes by collection ## Balance Change Reason Codes The Transaction Balance Tracker API uses numeric codes to indicate why a balance changed. These codes are only available for native currency (ETH) transactions, not for fungible tokens or NFTs. | **Code** | **Reason** | **Description** | | -------- | ----------------------------------- | -------------------------------------------------------------------------- | | 0 | BalanceChangeUnspecified | Unspecified balance change reason | | 1 | BalanceIncreaseRewardMineUncle | Reward for mining an uncle block | | 2 | BalanceIncreaseRewardMineBlock | Reward for mining a block | | 3 | BalanceIncreaseWithdrawal | ETH withdrawn from the beacon chain | | 4 | BalanceIncreaseGenesisBalance | ETH allocated at the genesis block | | 5 | BalanceIncreaseRewardTransactionFee | Transaction tip increasing block builder's balance | | 6 | BalanceDecreaseGasBuy | ETH spent to purchase gas for transaction execution | | 7 | BalanceIncreaseGasReturn | ETH returned for unused gas at the end of execution | | 8 | BalanceIncreaseDaoContract | ETH sent to the DAO refund contract | | 9 | BalanceDecreaseDaoAccount | ETH taken from a DAO account to be moved to the refund contract | | 10 | BalanceChangeTransfer | ETH transferred via a call | | 11 | BalanceChangeTouchAccount | Transfer of zero value to touch-create an account | | 12 | BalanceIncreaseSelfdestruct | Balance added to the recipient as indicated by a self-destructing account | | 13 | BalanceDecreaseSelfdestruct | Balance deducted from a contract due to self-destruct | | 14 | BalanceDecreaseSelfdestructBurn | ETH sent to an already self-destructed account within the same transaction | | 15 | BalanceChangeRevert | Balance reverted back to a previous value due to call failure | ## Field Availability by Currency Type The availability of fields in the `TokenBalance` object depends on the type of currency being tracked: ### Native Currency (ETH) - **Available**: `BalanceChangeReasonCode`, `PreBalance`, `PostBalance`, `PostBalanceInUSD` - **Not Provided**: `TotalSupply`, `TokenOwnership` ### Fungible Tokens (ERC-20) - **Available**: `PostBalance`, `PostBalanceInUSD`, `TotalSupply`, `TotalSupplyInUSD` - **Not Provided**: `PreBalance`, `BalanceChangeReasonCode`, `TokenOwnership` ### NFTs (ERC-721 / ERC-1155) - **Available**: `PostBalance`, `TokenOwnership` - **Not Provided**: `PreBalance`, `BalanceChangeReasonCode`, `TotalSupply`, `TotalSupplyInUSD`, `PostBalanceInUSD` --- ## Ethereum Transfer Balance Tracker URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-transfer-balance-tracker/ Ethereum Transfer Balance Tracker: monitor Ethereum native and token transfers in real time with Bitquery GraphQL APIs. See examples in the Bitquery IDE. # Ethereum Transfer Balance Tracker The Ethereum Transfer Balance Tracker API provides real-time balance updates for all addresses involved in Transfers on the Ethereum blockchain, and provides option to filter out based on the direction of transfer you want to target. The Ethereum Transfer Balance is tracked by marking the the `BalanceUpdateReason` equals `10`. :::note The queries covered this section are only valid for the Native Currency Transfer. ::: ## Get Balance Info for an Address after Transfer [This](https://ide.bitquery.io/balance-update-from-transfer-for-an-address#) query returns the Balance Info such as PreBalance, PostBalance, Balances in USD and transfer amount for a particular address after a transfer, irrespective of the direction of transfer.
Click here to expand ```graphql query MyQuery { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}, Address: {is: "0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e"}}} orderBy: {descending: Block_Time} limit: {count: 1} ) { Block { Time } TokenBalance { PostBalance PostBalanceInUSD PreBalance PreBalanceInUSD } amt: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) amt_usd: calculate( expression: "$TokenBalance_PostBalanceInUSD - $TokenBalance_PreBalanceInUSD" ) Transaction { From To } } } } ```
## Stream Balance Info for Transfer in Real Time [This](https://ide.bitquery.io/balance-update-from-transfer-for-an-address--stream#) subscription allows us to stream Balance Updates for an address due to transfer in Real Time.
Click here to expand ```graphql subscription { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}, Address: {is: "0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e"}}} ) { Block { Time } TokenBalance { PostBalance PostBalanceInUSD PreBalance PreBalanceInUSD } amt: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) amt_usd: calculate( expression: "$TokenBalance_PostBalanceInUSD - $TokenBalance_PreBalanceInUSD" ) Transaction { From To } } } } ```
## Get Balance Info for Multiple Addresses after Transfer [This](https://ide.bitquery.io/balance-update-from-transfer-for-multiple-addresses#) query returns the Balance Info such as PreBalance, PostBalance, Balances in USD and transfer amount for a list of addresses after a transfer, irrespective of the direction of transfer.
Click here to expand ```graphql query MyQuery { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}, Address: {in: ["0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e", "0x5b43453fce04b92e190f391a83136bfbecedefd1"]}}} orderBy: {descending: Block_Time} limitBy: {by:TokenBalance_Address count: 1} ) { Block { Time } TokenBalance { PostBalance PostBalanceInUSD PreBalance PreBalanceInUSD } amt: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) amt_usd: calculate( expression: "$TokenBalance_PostBalanceInUSD - $TokenBalance_PreBalanceInUSD" ) Transaction { From To } } } } ```
## Stream Balance Update due to Transfer for Multiple Addresses in Real Time [This](https://ide.bitquery.io/balance-update-from-transfer-for-multiple-addresses--stream#) subscription allows us to stream Balance Updates for a list of addresses due to transfer in Real Time.
Click here to expand ```graphql subscription { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}, Address: {in: ["0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e", "0x5b43453fce04b92e190f391a83136bfbecedefd1"]}}} ) { Block { Time } TokenBalance { PostBalance PostBalanceInUSD PreBalance PreBalanceInUSD } amt: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) amt_usd: calculate( expression: "$TokenBalance_PostBalanceInUSD - $TokenBalance_PreBalanceInUSD" ) Transaction { From To } } } } ```
## Get Balance Info for an Address after Transfer Sent [This](https://ide.bitquery.io/Balance-update-after-transfer-sent_2) query returns the Balance Info such as PreBalance, PostBalance, Balances in USD and transfer amount for a particular address after it sends a transfer.
Click here to expand ```graphql query MyQuery { EVM { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}}, Transaction: {From: {is: "0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e"}}} orderBy: {descending: Block_Time} limit: {count: 1} ) { Block{ Time } TokenBalance { PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD } Transaction{ From To Hash } amount:calculate(expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance") amount_usd:calculate(expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD") } } } ```
## Stream Balance Info for Transfer Sent in Real Time [This](https://ide.bitquery.io/Balance-update-after-transfer-sent--stream_3) subscription allows us to stream Balance Updates for a transfer sent by an address in Real Time.
Click here to expand ```graphql subscription { EVM { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}}, Transaction: {From: {is: "0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e"}}} ) { Block{ Time } TokenBalance { PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD } Transaction{ From To Hash } amount:calculate(expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance") amount_usd:calculate(expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD") } } } ```
## Get Balance Info for Multiple Addresses after Transfer Sent [This](https://ide.bitquery.io/Balance-update-after-transfer-sent-from-multiple-addresses) query returns the Balance Info such as PreBalance, PostBalance, Balances in USD and transfer amount for a list of addresses after they send a transfer.
Click here to expand ```graphql query MyQuery { EVM { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}}, Transaction: {From: {in: ["0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e", "0x5b43453fce04b92e190f391a83136bfbecedefd1"]}}} orderBy: {descending: Block_Time} limitBy: {by:Transaction_From count: 1} ) { Block{ Time } TokenBalance { PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD } Transaction{ From To Hash } amount:calculate(expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance") amount_usd:calculate(expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD") } } } ```
## Stream Balance Info for Multiple Addresses for Transfer Sent in Real Time [This](https://ide.bitquery.io/Balance-update-after-transfer-sent-from-multiple-addresses--stream#) subscription allows us to stream Balance Updates for a list of addresses due to transfer sent in Real Time.
Click here to expand ```graphql subscription { EVM { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}}, Transaction: {From: {in: ["0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e", "0x5b43453fce04b92e190f391a83136bfbecedefd1"]}}} ) { Block{ Time } TokenBalance { PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD } Transaction{ From To Hash } amount:calculate(expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance") amount_usd:calculate(expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD") } } } ```
## Get Balance Info for an Address after Transfer Recieved [This](https://ide.bitquery.io/Balance-update-after-transfer-received_1) query returns the Balance Info such as PreBalance, PostBalance, Balances in USD and transfer amount for a particular address after it recieves a transfer.
Click here to expand ```graphql query MyQuery { EVM { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}}, Transaction: {To: {is: "0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e"}}} orderBy: {descending: Block_Time} limit: {count: 1} ) { Block{ Time } TokenBalance { PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD } Transaction{ From To Hash } amount:calculate(expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance") amount_usd:calculate(expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD") } } } ```
## Stream Balance Info for Transfer Recieved in Real Time [This](https://ide.bitquery.io/Balance-update-after-transfer-received--stream) subscription allows us to stream Balance Updates for a transfer recieved by an address in Real Time.
Click here to expand ```graphql subscription { EVM { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}}, Transaction: {To: {is: "0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e"}}} ) { Block{ Time } TokenBalance { PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD } Transaction{ From To Hash } amount:calculate(expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance") amount_usd:calculate(expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD") } } } ```
## Get Balance Info for Multiple Addresses after Transfer Recieved [This](https://ide.bitquery.io/Balance-update-after-transfer-received-from-multiple-addresses_2) query returns the Balance Info such as PreBalance, PostBalance, Balances in USD and transfer amount for a list of addresses after they recieve a transfer.
Click here to expand ```graphql query MyQuery { EVM { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}}, Transaction: {To: {in: ["0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e", "0x5b43453fce04b92e190f391a83136bfbecedefd1"]}}} orderBy: {descending: Block_Time} limitBy: {by:Transaction_To count: 1} ) { Block{ Time } TokenBalance { PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD } Transaction{ From To Hash } amount:calculate(expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance") amount_usd:calculate(expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD") } } } ```
## Stream Balance Info for Multiple Addresses for Transfer Recieved in Real Time [This](https://ide.bitquery.io/Balance-update-after-transfer-received-from-multiple-addresses--stream) subscription allows us to stream Balance Updates for a list of addresses due to transfer recieved in Real Time.
Click here to expand ```graphql subscription { EVM { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}}, Transaction: {To: {in: ["0xafd8cd311c7bf2635573ebebb97c1a3c7e90f00e", "0x5b43453fce04b92e190f391a83136bfbecedefd1"]}}} ) { Block{ Time } TokenBalance { PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD } Transaction{ From To Hash } amount:calculate(expression: "$TokenBalance_PreBalance - $TokenBalance_PostBalance") amount_usd:calculate(expression: "$TokenBalance_PreBalanceInUSD - $TokenBalance_PostBalanceInUSD") } } } ```
## Get Balance Updates for the Last 24 hours Use [this](https://ide.bitquery.io/Balance-Updates-for-transfer-in-last-24-hours) API endpoint for getting Balance Updates due to Transfers for a particular address irrespective of the direction of Transfer. This could be used in applications that maintains a record for a wallet.
Click here to expand ```graphql query MyQuery { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}, Address: {is: "0xdadb0d80178819f2319190d340ce9a924f783711"}}, Block: {Time: {since_relative: {hours_ago: 24}}}} orderBy: {descending: Block_Time} ) { Block { Time } TokenBalance { PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD } Transaction { From To Hash } transfer_amount: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) transfer_amount_usd: calculate( expression: "$TokenBalance_PostBalanceInUSD - $TokenBalance_PreBalanceInUSD" ) } } } ```
## Get Balance Updates for the Last 24 hours Use [this](https://ide.bitquery.io/Balance-Updates-for-multiple-addresses-transfer-in-last-24-hours) API endpoint for getting Balance Updates due to Transfers for a list of addresses irrespective of the direction of Transfer. This could be used in Dashboard Applications that shows record for multiple wallets.
Click here to expand ```graphql query MyQuery { EVM(network: eth) { TransactionBalances( where: {TokenBalance: {BalanceChangeReasonCode: {eq: 10}, Address: {in: ["0xdadb0d80178819f2319190d340ce9a924f783711", "0x396343362be2a4da1ce0c1c210945346fb82aa49"]}}, Block: {Time: {since_relative: {hours_ago: 24}}}} orderBy: {descending: Block_Time} ) { Block { Time } TokenBalance { PreBalance PostBalance PreBalanceInUSD PostBalanceInUSD } Transaction { From To Hash } transfer_amount: calculate( expression: "$TokenBalance_PostBalance - $TokenBalance_PreBalance" ) transfer_amount_usd: calculate( expression: "$TokenBalance_PostBalanceInUSD - $TokenBalance_PreBalanceInUSD" ) } } } ```
--- ## Ethereum Uniswap API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/uniswap-api/ Query Uniswap v1-v4 on Ethereum with Bitquery GraphQL: real-time trades, TradingView-ready OHLC streams across chains, per-pair trades and top traders. # Uniswap API Uniswap is a decentralized exchange on Ethereum for trading ERC-20 tokens. Bitquery’s APIs support Uniswap trades, pool creations, and active user metrics across v1, v2, v3 and v4 in real-time and across archive data since genesis. :::tip Real-time data or the last 30 days? Use the Trading cube For real-time trades and anything from the last 30 days, use the [Trading cube](/docs/trading/trading-data-overview): [`Trading.Trades`](/docs/trading/crypto-trades-api/trades-api) returns MEV-filtered swaps with a USD price on every row. Use the `EVM` queries on this page for raw per-swap detail or call and event context. An `EVM` query without a `dataset` argument runs on the realtime dataset, which holds only the last few days; add `dataset: combined` or `dataset: archive` for older history. ::: The same schema powers our multi-chain [DEX API](https://bitquery.io/products/dex), so these queries also run on other EVM exchanges, such as PancakeSwap or SushiSwap, once you change the DEX filter. For Uniswap v3 positions, see the [Uniswap position API examples](/docs/blockchain/Ethereum/dextrades/uniswap-position-api/) You can also explore Uniswap APIs on other chains: - [BNB Smart Chain](/docs/blockchain/BSC/bsc-uniswap-api/) - [Base](/docs/blockchain/Base/base-uniswap-api/) - [Polygon](/docs/blockchain/Matic/matic-uniswap-api/) ## Uniswap contract addresses on Ethereum Core contracts on Ethereum mainnet. Every address below was read from indexed mainnet logs rather than copied from a reference, and each one is the contract that actually emits the events in the next table. | Version | Contract | Address | | --- | --- | --- | | v2 | Factory | `0x5c69bee701ef814a2b6a3edd4b1652cb9cc5aa6f` | | v3 | Factory | `0x1f98431c8ad98523631ae4a59f267346ea31f984` | | v3 | NonfungiblePositionManager | `0xc36442b4a4522e871399cd717abdd847ab11fe88` | | v4 | PoolManager (singleton) | `0x000000000004444c5dc75cb358380d2e3de08a90` | | v4 | PositionManager | `0xbd216513d74c8cf14cf4747e6aaa6420ff64ee9e` | ## Uniswap event signatures and topic0 hashes `topic0` is the first log topic, the keccak-256 hash of the event signature. Use it to match raw logs when you are reading them outside Bitquery's decoded schema. | Version | Event | Signature | topic0 | | --- | --- | --- | --- | | v2 | PairCreated | `PairCreated(address,address,address,uint256)` | `0x0d3648bd0f6ba80134a33ba9275ac585d9d315f0ad8355cddefde31afa28d0e9` | | v2 | Swap | `Swap(address,uint256,uint256,uint256,uint256,address)` | `0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822` | | v3 | PoolCreated | `PoolCreated(address,address,uint24,int24,address)` | `0x783cca1c0412dd0d695e784568c96da2e9c22ff989357a2e8b1d9b2b4e6b7118` | | v3 | Swap | `Swap(address,address,int256,int256,uint160,uint128,int24)` | `0xc42079f94a6350d7e6235f29174924f928cc2ac818eb64fed8004e115fbcca67` | | v4 | Initialize | `Initialize(bytes32,address,address,uint24,int24,address,uint160,int24)` | `0xdd466e674ea557f56295e2d0218a125ea4b4f0f6f3307b95f85e6110838d6438` | | v4 | Swap | `Swap(bytes32,address,int128,int128,uint160,uint128,int24,uint24)` | `0x40e9cecb9f5f1f1c5b9c97dec2917b7ee92e57ba5563708daca94dd84ad7112f` | | v4 | ModifyLiquidity | `ModifyLiquidity(bytes32,address,int24,int24,int256,bytes32)` | `0xf208f4912782fd25c7f114ca3723a2d5dd6f3bcc3ac8db5af63baa85f711d5ec` | ### A topic0 does not identify Uniswap The v2 and v3 contracts are the most forked code on Ethereum, and a fork keeps the ABI, so it keeps the hash. Matching logs on topic0 alone gives you every fork as well as Uniswap. SushiSwap's factory at `0xc0aee478e3658e2610c5f7a4a2e1777ce9e4f2ac` emits exactly the `PairCreated` signature and topic0 in the table above. On the v3 side, at least four other Ethereum factories emitted the identical `PoolCreated` in the last 30 days. Any indexer keyed on topic0 alone will report those as Uniswap. To isolate Uniswap's own pools, pair the topic0 with the factory that created them, listed in the first table. ### Filter decoded trades by factory Bitquery's decoded trades have the same catch. `Trade.Dex.ProtocolName` records which code a pool runs, and a fork runs the same code, so `uniswap_v2` also returns SushiSwap and the other v2 forks. In Bitquery's trade data for 18 September 2026, 21% of Ethereum transactions carrying a `uniswap_v2` trade touched another factory's pools, and SushiSwap's factory was in about three in five of those. Count trades rather than transactions and the share rises to 26%, because a routed swap can touch a Uniswap pool and a fork in the same transaction. The `uniswap_v3` label is cleaner, under 2%, and every `uniswap_v4` trade came from the PoolManager. To keep only Uniswap's own pools, filter on the contract that owns them: | Version | Field | Value on Ethereum | | --- | --- | --- | | v2 | `Trade.Dex.OwnerAddress` | `0x5c69bee701ef814a2b6a3edd4b1652cb9cc5aa6f` | | v3 | `Trade.Dex.OwnerAddress` | `0x1f98431c8ad98523631ae4a59f267346ea31f984` | | v4 | `Trade.Dex.SmartContract` | `0x000000000004444c5dc75cb358380d2e3de08a90` | `OwnerAddress` is the factory that deployed the pool. v4 pools have no factory, so their `OwnerAddress` is the zero address and the PoolManager is the `SmartContract`. In the Trading cube, the same contracts are `Market.Address` (the v2 or v3 factory) and `Market.Program` (the v4 PoolManager). The [active traders query](#active-traders-on-uniswap-in-the-last-7-days) below uses the v3 filter. ### Two more differences worth knowing In v2 and v3 the `Swap` event is emitted by the pair or pool contract itself, so the pool is identified by the log's own address, and mainnet has thousands of distinct emitters. In v4 every pool lives inside the one PoolManager, so every v4 `Swap` log carries the same emitter address and the pool is identified by the `bytes32` PoolId in the event's first argument. Filtering v4 swaps by a pool address does not work; filter by PoolId. Liquidity positions are represented differently in each version. v2 gives a depositor fungible ERC-20 LP tokens minted by the pair itself. v3 and v4 both issue an ERC-721: one `tokenId` per position, from the NonfungiblePositionManager in v3 and the PositionManager in v4. Where they differ is which contract reports the liquidity change. The v3 manager emits `IncreaseLiquidity`, `DecreaseLiquidity` and `Collect` itself, so the position lifecycle is readable from that one contract. The v4 PositionManager emits no liquidity events. Its logs on Ethereum are the ERC-721 `Transfer`, `Approval` and `ApprovalForAll`, and the liquidity change is emitted by the PoolManager as `ModifyLiquidity`. Reading a v4 position therefore means joining the NFT to the PoolManager's events by PoolId. ## Realtime Uniswap v1, v2, v3, v4 Trades Track live trades across all Uniswap versions: [Run Stream](https://ide.bitquery.io/uniswap-all-versions-trades-stream_1) The stream filters on `ProtocolName`, so it also returns forks such as SushiSwap. To keep only Uniswap's own pools, use the filters in [Filter decoded trades by factory](#filter-decoded-trades-by-factory).
Click to expand GraphQL subscription ```graphql subscription { EVM(network: eth) { DEXTrades( where: { Trade: { Dex: { ProtocolName: { in: ["uniswap_v4", "uniswap_v3", "uniswap_v2", "uniswap_v1"] } } } } ) { Block { Number Time } Transaction { From To Hash } Trade { Dex { Delegated DelegatedTo OwnerAddress Pair { Decimals Name SmartContract } ProtocolFamily ProtocolName ProtocolVersion SmartContract } Buy { Amount Buyer Currency { Name Symbol SmartContract } Seller Price } Sell { Amount Buyer Currency { Name SmartContract Symbol } Seller Price } } } } } ```
## TradingView OHLC Stream on Uniswap Across Chains The new [Price Index Stream](/docs/trading/crypto-price-api/) helps you get token-level, pair-level, and market-level OHLC data for 1 sec interval( or higher), in real-time across all chains. These also include trading metrics like SMA, EMA, VWAP, and more. The `Market.Protocol` filter matches forks as well. In the Trading cube, PancakeSwap V2 on BNB Chain, QuickSwap on Polygon and SushiSwap on Ethereum all carry the `uniswap_v2` label. To keep Uniswap's own pools, filter `Market.Address` to the v2 or v3 factory, or `Market.Program` to the v4 PoolManager. The addresses differ by chain; Ethereum's are in [Filter decoded trades by factory](#filter-decoded-trades-by-factory). [Run Stream](https://ide.bitquery.io/Stream-all-Uniswap-Seconds-OHLC-Kline_1)
{" "} Click to expand GraphQL query ```graphql subscription { Trading { Pairs( where: {Market: {Protocol: {in: ["uniswap_v4","uniswap_v3", "uniswap_v2", "uniswap_v1"]}}, Interval: {Time: {Duration: {eq: 1}}}} ) { Currency { Name Id } Market { Name NetworkBid Network Address } Price { IsQuotedInUsd Average { Mean } } QuoteCurrency { Id Symbol Name } QuoteToken { Symbol Name Id NetworkBid Network Did Address } Token { Name Id NetworkBid } } } } ```
## Latest Trades of a Pair on Uniswap Retrieve the 50 most recent WETH/USDC trades in pools labelled Uniswap v1–v4, forks included, [Run query](https://ide.bitquery.io/Latest-Trades-of-a-Pair-on-Uniswap). Add the [factory filters](#filter-decoded-trades-by-factory) to keep Uniswap's own pools only:
Click to expand GraphQL query ```graphql query LatestTrades { EVM(network: eth) { DEXTradeByTokens( orderBy: { descending: Block_Time } limit: { count: 50 } where: { Trade: { Side: { Amount: { gt: "0" } Currency: { SmartContract: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } } } Currency: { SmartContract: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } Dex: { ProtocolName: { in: ["uniswap_v4", "uniswap_v3", "uniswap_v2", "uniswap_v1"] } } } } ) { Block { allTime: Time } Trade { Dex { OwnerAddress ProtocolFamily ProtocolName } Currency { Symbol SmartContract Name } Price AmountInUSD Amount Side { Type Currency { Symbol SmartContract Name } AmountInUSD Amount } } } } } ```
## Top Traders of a Token Identify the top 100 USDC traders by USD volume in pools labelled Uniswap v1–v4, forks included ([saved query](https://ide.bitquery.io/Top-Traders-of-a-Token_8)). It ranks `Transaction.From`, the account that sent each swap, since on a sale `Trade.Buyer` is the pool or a router. `Side.Type` describes the counter-side of each trade, so `bought` sums the rows where `Side.Type` is `sell`. `PriceAsymmetry: { lt: 0.1 }` drops trades whose two sides disagree badly on value ([PriceAsymmetry reference](/docs/graphql/metrics/priceAsymmetry/)), which would otherwise inflate the USD totals:
Click to expand GraphQL query ```graphql query topTraders { EVM(network: eth) { DEXTradeByTokens( orderBy: { descendingByField: "volumeUsd" } limit: { count: 100 } where: { Trade: { Currency: { SmartContract: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } } Dex: { ProtocolName: { in: ["uniswap_v4", "uniswap_v3", "uniswap_v2", "uniswap_v1"] } } PriceAsymmetry: { lt: 0.1 } } } ) { Transaction { From } bought: sum( of: Trade_Amount if: { Trade: { Side: { Type: { is: sell } } } } ) sold: sum( of: Trade_Amount if: { Trade: { Side: { Type: { is: buy } } } } ) volume: sum(of: Trade_Amount) volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } ```
## Uniswap v2 Pair Trade Stats Get CHEFDOG/WETH v2 pooled stats (volume, bought, sold). As above, `bought` counts rows where `Side.Type` is `sell`:
Click to expand GraphQL query ```graphql query pairTopTraders { EVM(network: eth, dataset: combined) { DEXTradeByTokens( orderBy: { descendingByField: "volumeUsd" } limit: { count: 100 } where: { Trade: { Dex: { Pair: { SmartContract: { is: "0x4ba1970f8d2dda96ebfbc466943fb0dfaab18c75" } } } } } ) { Trade { Dex { OwnerAddress ProtocolFamily ProtocolName } } bought: sum( of: Trade_Amount if: { Trade: { Side: { Type: { is: sell } } } } ) sold: sum( of: Trade_Amount if: { Trade: { Side: { Type: { is: buy } } } } ) volume: sum(of: Trade_Amount) volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } ```
## Stream Latest Pool Creation on Uniswap V2, V3 [Run Stream ➤](https://ide.bitquery.io/stream-pool-and-pair-creation-on-ethereum_1) It covers v4 as well: the PoolManager is in the contract list, and v4 pools are created by `Initialize`. [Run Query ➤](https://ide.bitquery.io/query-pool-and-pair-creation-on-ethereum_1)
Click to expand GraphQL query ```graphql subscription { EVM(network: eth) { Events( where: { Log: { SmartContract: { in: [ "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f" "0x1f98431c8ad98523631ae4a59f267346ea31f984" "0x000000000004444c5dc75cB358380D2e3dE08A90" ] } Signature: { Name: { in: ["PoolCreated", "PairCreated", "Initialize"] } } } } ) { Log { SmartContract } Transaction { Hash } Arguments { Type Value { ... on EVM_ABI_Boolean_Value_Arg { bool } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Integer_Value_Arg { integer } } Name } Block { Time } } } } ```
## Latest Pools Created on Uniswap V2 Track the last 10 `PairCreated` events from the Uniswap V2 factory:
Click to expand GraphQL query ```graphql { EVM(dataset: combined, network: eth) { Events( orderBy: { descending: Block_Number } limit: { count: 10 } where: { Log: { SmartContract: { is: "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f" } Signature: { Name: { is: "PairCreated" } } } } ) { Log { Signature { Name Parsed Signature } SmartContract } Transaction { Hash } Block { Date Number } Arguments { Type Value { ... on EVM_ABI_Address_Value_Arg { address } } } } } } ```
## Latest Pools Created on Uniswap V4 Track the last 10 `Initialize` events from the Uniswap V4 factory:
Click to expand GraphQL query ```graphql { EVM(dataset: realtime, network: eth) { Events( orderBy: { descending: Block_Number } limit: { count: 10 } where: { Log: { SmartContract: { is: "0x000000000004444c5dc75cB358380D2e3dE08A90" } Signature: { Name: { is: "Initialize" } } } } ) { Log { Signature { Name Parsed Signature } SmartContract } Transaction { Hash } Block { Date Number } Arguments { Type Value { ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_Boolean_Value_Arg { bool } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Integer_Value_Arg { integer } } } } } } ```
## Active Traders on Uniswap in the Last 7 Days Rank the 100 accounts that sent the most Uniswap v3 swaps on Ethereum in the last 7 days. It groups by `Transaction.From`, since `Trade.Seller` is often the pool, and sets `dataset: combined` because the default realtime dataset holds only the last few days:
Click to expand GraphQL query ```graphql query ActiveUniswapTraders { EVM(network: eth, dataset: combined) { DEXTradeByTokens( where: { Trade: { Dex: { OwnerAddress: { is: "0x1f98431c8ad98523631ae4a59f267346ea31f984" } } } Block: { Time: { since_relative: { days_ago: 7 } } } } limit: { count: 100 } orderBy: { descendingByField: "tradeCount" } ) { Transaction { From } tradeCount: count uniqueTokens: count(distinct: Trade_Currency_SmartContract) } } } ```
## Get Latest Trading Price for a Uniswap Token Pair We launched the [Price Index](/docs/trading/crypto-price-api/) in August 2025, allowing you to track price for any onchain token pair. Here's an example of tracking Uniswap token pair trading price. `ProtocolFamily: "Uniswap"` also matches SushiSwap's WETH/USDC pools; filter `Market.Address` or `Market.Program` instead when you need Uniswap's own pools. Uniswap Token Pair Price API [Run Query ➤](https://ide.bitquery.io/latest-trade-price-of-uniswap-pair#)
Click to expand GraphQL query ```graphql query MyQuery { Trading(dataset: realtime) { Pairs( where: { Token: { Address: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } QuoteToken: { Address: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } } Market: { Network: { is: "Ethereum" } ProtocolFamily: { is: "Uniswap" } } Interval: { Time: { Duration: { eq: 60 } } } } orderBy: { descending: Block_Time } limit: { count: 1 } ) { Block { Time } Price { Average { Mean SimpleMoving WeightedSimpleMoving ExponentialMoving } } Market { Address ProtocolFamily Protocol Program } } } } ```
## Get OHLC for a Pair on Uniswap [Run Query](https://ide.bitquery.io/OHLC-price-of-an-uniswap-pair) to get `1 minute` OHLC data for a given pair of currencies. Like the price example above, it filters `ProtocolFamily`, so fork pools are included.
Click to expand GraphQL query ```graphql query MyQuery { Trading(dataset: realtime) { Pairs( where: { Token: { Address: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } QuoteToken: { Address: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } } Market: { Network: { is: "Ethereum" } ProtocolFamily: { is: "Uniswap" } } Interval: { Time: { Duration: { eq: 60 } } } } orderBy: { descending: Interval_Time_End } ) { Interval { Time { Start End } } Price { Ohlc { Open High Low Close } } Market { Address ProtocolFamily Protocol Program } QuoteToken { Address Name Symbol } Token { Address Name Symbol } } } } ```
## Uniswap Kafka Streams You can get Uniswap data with sub-second latency via Kafka Streams. Read about [Kafka streaming concepts](/docs/streams/kafka-streaming-concepts/) Contact us on our telegram channel for a trial credentials. --- ## Ethereum Uniswap v4 API: Swaps, PoolIds, Pool Stats, Traders and Reserves URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/uniswap-v4-api/ Uniswap v4 on Ethereum with Bitquery GraphQL: swaps with trader and market cap, raw PoolManager swaps, pools by PoolId, pool stats, top traders, reserves. # Ethereum Uniswap v4 API: Swaps, PoolIds, Pool Stats, Traders and Reserves Uniswap v4 replaced one contract per pool with one contract for all pools. On Ethereum that contract is the PoolManager at `0x000000000004444c5dc75cB358380D2e3dE08A90`; a pool is a `PoolId`, the hash of its two tokens, fee, tick spacing and hook, and swaps, deposits and withdrawals all surface as events of the PoolManager. Bitquery decodes those into the same cubes as every other DEX, with two things to know. `Trade.PoolId` is how you pick a pool, since `Dex.SmartContract` is always the PoolManager. And on raw `DEXTrades` rows the buyer and seller are both the PoolManager, because it settles both sides; the trader is `Transaction.From`, or the `Trader` field of the Trading cube. Every example runs in the [IDE](https://ide.bitquery.io) on a free account. The worked pool is ETH/USDC, `PoolId 0x00b9edc1583bf6ef09ff3a09f6c23ecb57fd7d0bb75625717ec81eed181e22d7`, and the worked token is USDC, `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`. ## Live swaps with trader, USD and market cap For a live feed with the trader, USD amounts and the token's supply and market cap on every row, use the [Crypto Trades API](/docs/trading/crypto-trades-api/trades-api) of the Trading cube and filter the market to Ethereum and `uniswap_v4`. `Pair.Pool.Id` is the PoolId and `Pair.Pool.Address` the PoolManager. The Trading cube keeps about 30 days; the chain cubes below reach further back. Saved stream [here](https://ide.bitquery.io/Uniswap-v4-trades-with-pool-id-and-mcap). ```graphql subscription { Trading { Trades( where: { Pair: { Market: { Network: { is: "Ethereum" }, Protocol: { is: "uniswap_v4" } } } } ) { Block { Time } Side Trader { Address } Amounts { Base Quote } AmountsInUsd { Base Quote } Supply { CirculatingSupply MarketCap } Pair { Currency { Symbol Id } QuoteCurrency { Symbol } Pool { Id Address } } TransactionHeader { Sender } } } } ``` ## Raw swaps from the PoolManager The chain-specific `DEXTrades` cube gives the pool-side view of each swap: what the pool received and what it paid out, with USD on both sides. Filter on the protocol name and subscribe, or add a `PoolId`. Saved stream [here](https://ide.bitquery.io/Real-time-trades-on-uniswap-v4----subscription). ```graphql subscription { EVM(network: eth) { DEXTrades(where: { Trade: { Dex: { ProtocolName: { is: "uniswap_v4" } } } }) { Block { Time } Trade { PoolId Buy { Currency { Symbol SmartContract } Amount AmountInUSD PriceInUSD } Sell { Currency { Symbol SmartContract } Amount AmountInUSD } } Transaction { From Hash } } } } ``` ## Every v4 pool of a token Group `DEXTradeByTokens` by `PoolId` with the token in `Currency`. Each row is one pool with its counter token, trade count and USD volume in the window; this is the lookup that gives you a `PoolId`. Saved query [here](https://ide.bitquery.io/All-Pool_Ids-for-currency). ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { Dex: { ProtocolName: { is: "uniswap_v4" } } Currency: { SmartContract: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } orderBy: { descendingByField: "count" } limit: { count: 20 } ) { Trade { PoolId Side { Currency { Symbol SmartContract } } } count volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } ``` ## Latest swaps in one pool Saved query [here](https://ide.bitquery.io/Latest-trades-for-a-Pool-Id-on-uniswap-v4). ```graphql { EVM(network: eth) { DEXTrades( where: { Trade: { PoolId: { is: "0x00b9edc1583bf6ef09ff3a09f6c23ecb57fd7d0bb75625717ec81eed181e22d7" } } } limit: { count: 20 } orderBy: { descending: Block_Time } ) { Block { Time } Trade { Buy { Currency { Symbol } Amount AmountInUSD PriceInUSD } Sell { Currency { Symbol } Amount AmountInUSD } } Transaction { From Hash } } } } ``` ## Pool stats for the last 24 hours Trades, distinct buyers and sellers, and USD volume split by direction for the token you name. Saved query [here](https://ide.bitquery.io/uniswap-v4-stats---Volume-bought-and-sold). ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { PoolId: { is: "0x00b9edc1583bf6ef09ff3a09f6c23ecb57fd7d0bb75625717ec81eed181e22d7" } Currency: { SmartContract: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Trade { Currency { Symbol } Side { Currency { Symbol } } } trades: count buyers: uniq(of: Trade_Buyer) sellers: uniq(of: Trade_Seller) volumeUsd: sum(of: Trade_Side_AmountInUSD) buyVolumeUsd: sum(of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: buy } } } }) sellVolumeUsd: sum(of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: sell } } } }) } } } ``` ## Top traders of the pool Rank by `Transaction.From`, the account that sent the swap. `bought` sums the token the trader received and `sold` the token it paid; `Side.Type` describes the counter-side of each trade, which is why the two conditions are the other way round. Saved queries: [top buyers](https://ide.bitquery.io/Top-Buyers-of-a-currency-on-uniswap-v4), [top sellers](https://ide.bitquery.io/Top-Sellers-of-a-currency-on-uniswap-v4). ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { PoolId: { is: "0x00b9edc1583bf6ef09ff3a09f6c23ecb57fd7d0bb75625717ec81eed181e22d7" } Currency: { SmartContract: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } orderBy: { descendingByField: "volumeUsd" } limit: { count: 20 } ) { Transaction { From } trades: count volumeUsd: sum(of: Trade_Side_AmountInUSD) bought: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: sell } } } }) sold: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: buy } } } }) } } } ``` ## Reserves of a v4 pool `DEXPoolEvents` rows carry the reserves the PoolManager holds for the pool after each change, rebuilt from the concentrated positions around the current price and priced in USD. Filter by `PoolId` for one pool, or keep only the protocol name to stream them all. Saved streams: [all v4 pools](https://ide.bitquery.io/Latest-Liquidity-Changes-of-Pools-in-a-Specific-DEX-Protocol---Uniswap-V4_6), [by PoolId](https://ide.bitquery.io/uniswap-v4-pool-liquidity-by-poolid-ethereum). ```graphql { EVM(network: eth) { DEXPoolEvents( where: { PoolEvent: { Pool: { PoolId: { is: "0x00b9edc1583bf6ef09ff3a09f6c23ecb57fd7d0bb75625717ec81eed181e22d7" } } } } limit: { count: 5 } orderBy: { descending: Block_Time } ) { Block { Time } PoolEvent { Pool { PoolId CurrencyA { Symbol } CurrencyB { Symbol } } Liquidity { AmountCurrencyA AmountCurrencyAInUSD AmountCurrencyB AmountCurrencyBInUSD } AtoBPrice } } } } ``` ## Related pages - [Ethereum DEX trades API](/docs/blockchain/Ethereum/dextrades/dex-api) - [Crypto Trades API](/docs/trading/crypto-trades-api/trades-api) - [Uniswap v4 on Base](/docs/blockchain/Base/uniswap-v4-api) - [Uniswap v4 on Arbitrum](/docs/blockchain/Arbitrum/uniswap-v4-api) - [Uniswap v4 on Optimism](/docs/blockchain/Optimism/uniswap-v4-api) --- ## Ethereum Validator Balance Tracker URL: https://docs.bitquery.io/docs/blockchain/Ethereum/balances/transaction-balance-tracker/eth-validator-balance-tracker/ Ethereum Validator Balance Tracker: stream Ethereum balance changes with reason codes using Bitquery GraphQL subscriptions. # Ethereum Validator Balance Tracker The Ethereum Validator Balance Tracker API provides real-time balance updates for Ethereum validators, tracking their staking rewards, withdrawals, and balance changes. For a sample application, see the [Validators Rewards Tax Calculator](https://docs.bitquery.io/crypto-reward-tax-calculator). ## Track Validator Balance Updates Monitor balance changes for Ethereum validators, including staking rewards and withdrawals from the beacon chain. Try the API [here](https://ide.bitquery.io/Track-Validator-Balance-Updates). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 3 } } } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash } } } } ``` **Note:** BalanceChangeReasonCode 3 corresponds to `BalanceIncreaseWithdrawal` - ETH withdrawn from the beacon chain. ## Track Validator Rewards Track validator rewards and balance increases from staking activities. Try the API [here](https://ide.bitquery.io/Track-Validator-Rewards). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { in: [2, 5] } } } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash } } } } ``` **Balance Change Reason Codes for Validators:** - **Code 2**: `BalanceIncreaseRewardMineBlock` - Reward for mining a block - **Code 3**: `BalanceIncreaseWithdrawal` - ETH withdrawn from the beacon chain - **Code 5**: `BalanceIncreaseRewardTransactionFee` - Transaction tip increasing block builder's balance ## Filter by Validator Address Track balance changes for a specific validator address: Try the API [here](https://ide.bitquery.io/Filter-by-Validator-Address). ```graphql subscription { EVM(network: eth) { TransactionBalances( where: { TokenBalance: { Address: { is: "0xValidatorAddressHere" } BalanceChangeReasonCode: { in: [2, 3, 5] } } } ) { Block { Time Number } TokenBalance { Currency { Symbol } PreBalance PostBalance Address BalanceChangeReasonCode PostBalanceInUSD } Transaction { Hash } } } } ``` ## Top Validators by Total Tips earned in last 24 hrs Ranks validators by cumulative priority fees (reason code 5) received in the last 24 hours. Test the query [here](https://ide.bitquery.io/top-validators-by-total-tips-in-last-24-hrs#). ```graphql query MyQuery { EVM(network: eth, dataset: realtime) { TransactionBalances( limit: { count: 10 } orderBy: { descendingByField: "Total_tip_native" } where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { TokenBalance { Address BalanceChangeReasonCode Currency { Name Symbol SmartContract } } Post: sum(of: TokenBalance_PostBalance) Post_USD: sum(of: TokenBalance_PostBalanceInUSD) Pre: sum(of: TokenBalance_PreBalance) Pre_USD: sum(of: TokenBalance_PreBalanceInUSD) Total_tip_native: calculate(expression: "$Post - $Pre") Total_tip_usd: calculate(expression: "$Post_USD - $Pre_USD") number_of_tips: count } } } ``` ## Total Tips earned by a Validator in last 24 hrs Returns the total priority fees (native and USD) earned by a specific validator over the last 24 hours. Test the query [here](https://ide.bitquery.io/total-tips-received-by-a-validator-in-last-24-hrs#). ```graphql query MyQuery { EVM(network: eth, dataset: realtime) { TransactionBalances( where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } Address: { is: "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97" } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { TokenBalance { Address BalanceChangeReasonCode Currency { Name Symbol SmartContract } } Post: sum(of: TokenBalance_PostBalance) Post_USD: sum(of: TokenBalance_PostBalanceInUSD) Pre: sum(of: TokenBalance_PreBalance) Pre_USD: sum(of: TokenBalance_PreBalanceInUSD) Total_tip_native: calculate(expression: "$Post - $Pre") Total_tip_usd: calculate(expression: "$Post_USD - $Pre_USD") number_of_tips: count } } } ``` ## Avg Tip in last 10 Blocks Calculates the average tip for each of the last 10 blocks. Test the query [here](https://ide.bitquery.io/last-10-blocks-avg-tip-in-native-eth_3). ```graphql query MyQuery { EVM(network: eth, dataset: realtime) { TransactionBalances( limit: { count: 10 } orderBy: { descending: Block_Number } where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } } } ) { Block { Number } TokenBalance { BalanceChangeReasonCode Currency { Name Symbol SmartContract } } Post: sum(of: TokenBalance_PostBalance) Post_USD: sum(of: TokenBalance_PostBalanceInUSD) Pre: sum(of: TokenBalance_PreBalance) Pre_USD: sum(of: TokenBalance_PreBalanceInUSD) Total_tip_native: calculate(expression: "$Post - $Pre") Total_tip_usd: calculate(expression: "$Post_USD - $Pre_USD") number_of_tips: count avg_tip_in_this_block: calculate( expression: "$Total_tip_native / $number_of_tips" ) avg_tip_usd_in_this_block: calculate( expression: "$Total_tip_usd / $number_of_tips" ) } } } ``` ## Avg Tip given in terms of Avg Gas Fees in last 10 blocks Compares average user tip to average total gas fee per block across the last 10 blocks. Test the query [here](https://ide.bitquery.io/Average-Tip-in-terms-of-avg-gas-Fee_4). ```graphql query MyQuery { EVM(network: eth, dataset: realtime) { TransactionBalances( limit: { count: 10 } orderBy: { descending: Block_Number } where: { TokenBalance: { BalanceChangeReasonCode: { eq: 5 } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Block { Number } TokenBalance { BalanceChangeReasonCode Currency { Name Symbol SmartContract } } avg_gasfees_in_this_block: average(of: Fee_SenderFee) Post: sum(of: TokenBalance_PostBalance) Post_USD: sum(of: TokenBalance_PostBalanceInUSD) Pre: sum(of: TokenBalance_PreBalance) Pre_USD: sum(of: TokenBalance_PreBalanceInUSD) Total_tip_native: calculate(expression: "$Post - $Pre") Total_tip_usd: calculate(expression: "$Post_USD - $Pre_USD") number_of_tips: count avg_tip_in_this_block: calculate( expression: "$Total_tip_native / $number_of_tips" ) avg_tip_usd_in_this_block: calculate( expression: "$Total_tip_usd / $number_of_tips" ) tip_in_terms_of_gasfees: calculate( expression: "( $avg_gasfees_in_this_block - $avg_tip_in_this_block ) / $avg_gasfees_in_this_block" ) } } } ``` ## Video Tutorial --- ## GMGN-style Token Discovery on Ethereum: New Tokens, Smart Money, DEX Activity URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/evm-gmgn-api/ GMGN-style token discovery on Ethereum via Bitquery GraphQL: new tokens' first trades, token stats and market cap, top bought and sold tokens, top traders. # GMGN-style Token Discovery on Ethereum: New Tokens, Smart Money, DEX Activity GMGN is a discovery screen: tokens that just started trading, the ones being bought and sold most, the wallets behind them, and a wallet's holdings when you click through. On Ethereum each of those is one query on Bitquery's `DEXTradeByTokens`, `Trading` and `Balances` cubes, and the same queries work on BSC, Base, Arbitrum and the other EVM chains with a network change. The worked token is Mog, `0xaaee1a9723aadb7afa2810263653a34ba2c21c7a`. Every example runs in the [IDE](https://ide.bitquery.io) on a free account. Pair feeds and terminal-style data are on the [BullX-style page](/docs/blockchain/Ethereum/dextrades/evm-bullx-api/); pool analytics are on the [GeckoTerminal-style page](/docs/blockchain/Ethereum/dextrades/evm-geckoterminal-api/). ## Recommended: Trading API queries (real-time + last ~30 days) ### Live trades with USD price, market cap and supply Streams MEV-filtered trades across all 10 chains; the network filter scopes it to Ethereum. Run it [in the IDE](https://ide.bitquery.io/Trading-API-Live-Trades-All-Chains). ```graphql subscription { Trading { Trades(where: { Pair: { Market: { Network: { is: "Ethereum" } } } }) { Block { Time } Price PriceInUsd Amounts { Base Quote } AmountsInUsd { Base Quote } Trader { Address } Pair { Token { Symbol Network } QuoteToken { Symbol } Market { Protocol Network } } } } } ``` ### Most accurate token price with 1-minute OHLC (top market) Returns the token's price from its top-volume market via `Ranking: { Position: { eq: 1 } }`; swap the token address and network for your token. Run it [in the IDE](https://ide.bitquery.io/Trading-API-Token-Price-Top-Market-Rank-1). ```graphql { Trading { Pairs( where: { Token: {Address: {is: "0xaaee1a9723aadb7afa2810263653a34ba2c21c7a"}, Network: {is: "Ethereum"}} Ranking: {Position: {eq: 1}} Interval: {Time: {Duration: {eq: 60}}} Price: {IsQuotedInUsd: true} } limit: {count: 1} orderBy: {descending: Block_Time} ) { Token { Symbol Address } QuoteToken { Symbol } Market { Protocol Address Network } Price { IsQuotedInUsd Ohlc { Open High Low Close } Average { Mean } } Volume { Base Usd } Block { Time } } } } ``` ## Tokens that just started trading The first WETH-quoted trade of each token seen in the last six hours: `limitBy` keeps one row per token and the ascending order makes that row its earliest. Established tokens appear too, since the window only sees their first trade inside it; a token whose first trade ever falls in the window is new. ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { Block: { Time: { since_relative: { hours_ago: 6 } } } Trade: { Side: { Currency: { SmartContract: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } } } } limitBy: { by: Trade_Currency_SmartContract, count: 1 } orderBy: { ascending: Block_Time } limit: { count: 50 } ) { Block { Time } Trade { Currency { Symbol SmartContract } Dex { ProtocolName SmartContract } PriceInUSD Side { AmountInUSD } } Transaction { From Hash } } } } ``` ## Token stats with market cap The Trading cube keeps hourly rows per token with the close price, USD volume and market cap; the latest row is the token card. Token ids are `bid:eth:`. ```graphql { Trading { Tokens( where: { Token: { Id: { is: "bid:eth:0xaaee1a9723aadb7afa2810263653a34ba2c21c7a" } } Interval: { Time: { Duration: { eq: 3600 } } } Block: { Time: { since_relative: { hours_ago: 3 } } } } limit: { count: 1 } orderBy: { descending: Block_Time } ) { Block { Time } Token { Symbol Network } Price { Ohlc { Open High Low Close } } Volume { Usd } Supply { MarketCap } } } } ``` ## Most bought and most sold tokens USD bought and sold per token over the last day. `Side.Type` names the counter-side, so the token was bought where the side was sold; sort on `bought` or `sold`. The single-trade USD cap keeps mispriced rows out of the sums. ```graphql { EVM(network: eth) { DEXTradeByTokens( orderBy: { descendingByField: "bought" } limit: { count: 20 } where: { Trade: { Side: { AmountInUSD: { lt: "10000000" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Trade { Currency { Symbol SmartContract } } bought: sum(of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: sell } } } }) sold: sum(of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: buy } } } }) trades: count makers: uniq(of: Transaction_From) } } } ``` ## Top traders of a token Rank by `Transaction.From`, the wallet that sent the swap, with what each bought and sold. Saved query [here](https://ide.bitquery.io/top-traders-of-a-token_7). ```graphql { EVM(network: eth) { DEXTradeByTokens( orderBy: { descendingByField: "volumeUsd" } limit: { count: 50 } where: { Trade: { Currency: { SmartContract: { is: "0xaaee1a9723aadb7afa2810263653a34ba2c21c7a" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Transaction { From } trades: count volumeUsd: sum(of: Trade_Side_AmountInUSD) bought: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: sell } } } }) sold: sum(of: Trade_Amount, if: { Trade: { Side: { Type: { is: buy } } } }) } } } ``` ## DEX activity across Ethereum Trades, USD volume and active pools per protocol over the last day. Saved query [here](https://ide.bitquery.io/dex-markets). ```graphql { EVM(network: eth) { DEXTradeByTokens( orderBy: { descendingByField: "trades" } where: { Trade: { Side: { AmountInUSD: { lt: "10000000" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Trade { Dex { ProtocolName ProtocolFamily } } trades: count volumeUsd: sum(of: Trade_Side_AmountInUSD) pools: uniq(of: Trade_Dex_SmartContract) makers: uniq(of: Transaction_From) } } } ``` ## Trading pairs on one DEX The busiest Uniswap v3 pools of the last day, one row per pool. Saved query [here](https://ide.bitquery.io/trading-pairs-on-a-specific-dex). ```graphql { EVM(network: eth) { DEXTradeByTokens( orderBy: { descendingByField: "trades" } limit: { count: 20 } limitBy: { by: Trade_Dex_SmartContract, count: 1 } where: { Trade: { Dex: { ProtocolName: { is: "uniswap_v3" } } Side: { AmountInUSD: { lt: "10000000" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Trade { Dex { SmartContract } Currency { Symbol SmartContract } Side { Currency { Symbol } } } trades: count volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } ``` ## Latest trades on one DEX Both sides of the newest Uniswap v3 swaps with USD and the sender. Saved query [here](https://ide.bitquery.io/latest-trades_5). ```graphql { EVM(network: eth) { DEXTrades( where: { Trade: { Dex: { ProtocolName: { is: "uniswap_v3" } } } } limit: { count: 20 } orderBy: { descending: Block_Time } ) { Block { Time } Trade { Buy { Currency { Symbol } Amount AmountInUSD } Sell { Currency { Symbol } Amount AmountInUSD } Dex { SmartContract } } Transaction { From Hash } } } } ``` ## A wallet's token balances The `Balances` cube returns the current balance of every token a wallet holds; the example is a wallet from the whale feed. Saved query [here](https://ide.bitquery.io/balance-of-a-wallet_1). ```graphql { EVM(network: eth) { Balances( where: { Balance: { Address: { is: "0xae2fc483527b8ef99eb5d9b44875f005ba1fae13" } } } orderBy: { descending: Balance_Amount } limit: { count: 20 } ) { Currency { Symbol SmartContract } Balance { Amount } } } } ``` ## Related pages - [BullX-style EVM API](/docs/blockchain/Ethereum/dextrades/evm-bullx-api/) - [GeckoTerminal-style EVM API](/docs/blockchain/Ethereum/dextrades/evm-geckoterminal-api/) - [Latest trading pairs API](/docs/blockchain/Ethereum/dextrades/latest-trading-pairs-api) - [Ethereum token balance API](/docs/blockchain/Ethereum/balances/) --- ## GeckoTerminal-style Pool Data on Ethereum: Trending Pools, OHLC, Reserves URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/evm-geckoterminal-api/ GeckoTerminal-style pool pages on Ethereum via Bitquery GraphQL: trending pools, live pool trades, buys, sells and makers, hourly OHLC, reserves, new pools. # GeckoTerminal-style Pool Data on Ethereum: Trending Pools, OHLC, Reserves GeckoTerminal is organised around pools: a ranked list of them, and for each one the trades, the buy and sell counts, the makers, the candles and the reserves. Bitquery's `DEXTradeByTokens` cube keys Ethereum trades by pool contract, and `DEXPoolEvents` records reserves in USD after every change, so each panel is one query. The worked pool is Mog/WETH on Uniswap v2, `0xc2eab7d33d3cb97692ecb231a5d0e4a649cb539d`, with Mog at `0xaaee1a9723aadb7afa2810263653a34ba2c21c7a`. Every example runs in the [IDE](https://ide.bitquery.io) on a free account, and the same queries work on BSC, Base, Arbitrum and the other EVM chains by changing the network. The [Solana version](/docs/blockchain/Solana/solana-geckoterminal-api/) covers Solana pools. ## Recommended: Trading API queries (real-time + last ~30 days) ### Live trades with USD price, market cap and supply Every Ethereum DEX trade with the trader, USD amounts and the market on the row, MEV trades filtered out; drop the network filter for all ten chains. Run it [in the IDE](https://ide.bitquery.io/Trading-API-Live-Trades-All-Chains). ```graphql subscription { Trading { Trades(where: { Pair: { Market: { Network: { is: "Ethereum" } } } }) { Block { Time } Price PriceInUsd Amounts { Base Quote } AmountsInUsd { Base Quote } Trader { Address } Pair { Token { Symbol Network } QuoteToken { Symbol } Market { Protocol Network } } } } } ``` ### Most accurate token price with 1-minute OHLC (top market) `Ranking: { Position: { eq: 1 } }` picks the token's deepest market, so this is the price a pool list should show; change the token address and network for any other token. Run it [in the IDE](https://ide.bitquery.io/Trading-API-Token-Price-Top-Market-Rank-1). ```graphql { Trading { Pairs( where: { Token: {Address: {is: "0xaaee1a9723aadb7afa2810263653a34ba2c21c7a"}, Network: {is: "Ethereum"}} Ranking: {Position: {eq: 1}} Interval: {Time: {Duration: {eq: 60}}} Price: {IsQuotedInUsd: true} } limit: {count: 1} orderBy: {descending: Block_Time} ) { Token { Symbol Address } QuoteToken { Symbol } Market { Protocol Address Network } Price { IsQuotedInUsd Ohlc { Open High Low Close } Average { Mean } } Volume { Base Usd } Block { Time } } } } ``` ## Trending pools The pools with the most trades in the last day, one row per pool contract with the pair, the maker count and USD volume. The single-trade USD cap keeps mispriced thin-pool rows out of the sums. Saved query [here](https://ide.bitquery.io/List-of-trading-pairs-in-descending-order-of-trxns-in-last-24-hours). ```graphql { EVM(network: eth) { DEXTradeByTokens( orderBy: { descendingByField: "trades" } where: { Block: { Time: { since_relative: { hours_ago: 24 } } } TransactionStatus: { Success: true } Trade: { Side: { AmountInUSD: { lt: "10000000" } } } } limit: { count: 20 } limitBy: { by: Trade_Dex_SmartContract, count: 1 } ) { Trade { Dex { SmartContract ProtocolName } Currency { Symbol SmartContract } Side { Currency { Symbol SmartContract } } } trades: count makers: uniq(of: Transaction_From) volumeUsd: sum(of: Trade_Side_AmountInUSD) } } } ``` ## Live trades of a pool Each message is one swap in the pool with the amount, the USD price, the side and the wallet that sent it. Saved stream [here](https://ide.bitquery.io/Get-pair-trades-data-just-like-geckoterminal). ```graphql subscription { EVM(network: eth) { DEXTradeByTokens( where: { Trade: { Dex: { SmartContract: { is: "0xc2eab7d33d3cb97692ecb231a5d0e4a649cb539d" } } Currency: { SmartContract: { is: "0xaaee1a9723aadb7afa2810263653a34ba2c21c7a" } } } } ) { Block { Time } Trade { Amount PriceInUSD Currency { Symbol } Side { Amount AmountInUSD Type Currency { Symbol } } } Transaction { Maker: From Hash } } } } ``` ## Buys, sells, makers and volume of a pool The stat block of a pool page: trades, buys, sells, makers, buyers, sellers and USD volume over the last day, each with a one-hour sub-window, plus the price at both ends of the window. `Side.Type` names the counter-side of a trade, so the token was bought where the side was sold, and wallets are counted by `Transaction.From`. Saved query [here](https://ide.bitquery.io/Buys-Sells-BuyVolume-SellVolume-Makers-TotalTradedVolume-PriceinUSD-for-a-eth-pair). ```graphql { EVM(network: eth) { DEXTradeByTokens( where: { TransactionStatus: { Success: true } Trade: { Dex: { SmartContract: { is: "0xc2eab7d33d3cb97692ecb231a5d0e4a649cb539d" } } Currency: { SmartContract: { is: "0xaaee1a9723aadb7afa2810263653a34ba2c21c7a" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } ) { Trade { Currency { Symbol SmartContract } Side { Currency { Symbol } } Dex { ProtocolName } start: PriceInUSD(minimum: Block_Number) end: PriceInUSD(maximum: Block_Number) } trades: count trades1h: count(if: { Block: { Time: { after_relative: { hours_ago: 1 } } } }) buys: count(if: { Trade: { Side: { Type: { is: sell } } } }) sells: count(if: { Trade: { Side: { Type: { is: buy } } } }) makers: uniq(of: Transaction_From) makers1h: uniq(of: Transaction_From, if: { Block: { Time: { after_relative: { hours_ago: 1 } } } }) buyers: uniq(of: Transaction_From, if: { Trade: { Side: { Type: { is: sell } } } }) sellers: uniq(of: Transaction_From, if: { Trade: { Side: { Type: { is: buy } } } }) volumeUsd: sum(of: Trade_Side_AmountInUSD) volumeUsd1h: sum(of: Trade_Side_AmountInUSD, if: { Block: { Time: { after_relative: { hours_ago: 1 } } } }) buyVolumeUsd: sum(of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: sell } } } }) sellVolumeUsd: sum(of: Trade_Side_AmountInUSD, if: { Trade: { Side: { Type: { is: buy } } } }) } } } ``` ## Hourly OHLC of a pair Candles from the Trading cube for WETH against USDT, quoted in USD, one row per hour. Change the two token ids for any pair. Saved query [here](https://ide.bitquery.io/WETH-USDT-OHLC-on-Ethereum_1). ```graphql { Trading { Pairs( where: { Token: { Id: { is: "bid:eth:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" } } QuoteToken: { Id: { is: "bid:eth:0xdac17f958d2ee523a2206206994597c13d831ec7" } } Interval: { Time: { Duration: { eq: 3600 } } } Price: { IsQuotedInUsd: true } } limit: { count: 24 } orderBy: { descending: Interval_Time_Start } ) { Interval { Time { Start } } Token { Symbol } QuoteToken { Symbol } Price { Ohlc { Open High Low Close } Average { Mean } } Volume { Base Usd } } } } ``` ## Reserves of a pool `DEXPoolEvents` emits both reserves in USD after every swap, mint or burn in the pool. The newest rows are the current liquidity. Saved query [here](https://ide.bitquery.io/Get-liquidity-of-a-pair_1). ```graphql { EVM(network: eth) { DEXPoolEvents( where: { PoolEvent: { Pool: { SmartContract: { is: "0xc2eab7d33d3cb97692ecb231a5d0e4a649cb539d" } } } } limit: { count: 5 } orderBy: { descending: Block_Time } ) { Block { Time } PoolEvent { Pool { CurrencyA { Symbol } CurrencyB { Symbol } } Liquidity { AmountCurrencyA AmountCurrencyAInUSD AmountCurrencyB AmountCurrencyBInUSD } AtoBPrice } } } } ``` ## New pools `PoolCreated` on the Uniswap v3 factory names both tokens, the fee tier and the pool address; the v2 factory at `0x5c69bee701ef814a2b6a3edd4b1652cb9cc5aa6f` emits `PairCreated` for the older design. New pools on Ethereum arrive minutes to hours apart, so query the last day rather than waiting on a stream. Saved query [here](https://ide.bitquery.io/Latest-pools-created-Uniswap-v3_9). ```graphql { EVM(network: eth) { Events( where: { Log: { SmartContract: { is: "0x1f98431c8ad98523631ae4a59f267346ea31f984" } Signature: { Name: { is: "PoolCreated" } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } limit: { count: 50 } orderBy: { descending: Block_Time } ) { Block { Time } Transaction { Hash } Arguments { Name Value { ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } } } } } } ``` ## Related pages - [GeckoTerminal-style Solana API](/docs/blockchain/Solana/solana-geckoterminal-api/) - [BullX-style EVM API](/docs/blockchain/Ethereum/dextrades/evm-bullx-api/) - [Ethereum liquidity API](/docs/blockchain/Ethereum/dextrades/ethereum-liquidity-api) - [Ethereum DEX trades API](/docs/blockchain/Ethereum/dextrades/dex-api) --- ## Get Supply and Marketcap of a Token URL: https://docs.bitquery.io/docs/blockchain/Ethereum/transfers/total-supply/ Get Supply and Marketcap of a Token: monitor Ethereum native and token transfers in real time with Bitquery GraphQL APIs. # Get Supply and Marketcap of a Token We will use the [Transaction Balance Tracker APIs](/docs/blockchain/Ethereum/balances/transaction-balance-tracker/) for this query. ```graphql { EVM(network: eth) { TransactionBalances( limit: { count: 1 } orderBy: { descending: Block_Time } where: { TokenBalance: { Currency: { SmartContract: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } Fungible: true } } } ) { Block { Time Number } TokenBalance { Currency { Symbol Name SmartContract Decimals } TotalSupply Marketcap: TotalSupplyInUSD } } } } ``` ## Alternative Method Using Transfer Cube ### Get Supply of a Token ```graphql query MyQuery { EVM(network: eth, dataset: combined) { Transfers( where: { Transfer: { Currency: { SmartContract: { is: "0x582d872A1B094FC48F5DE31D3B73F2D9bE47def1" } } Success: true } } ) { minted: sum( of: Transfer_Amount if: { Transfer: { Sender: { is: "0x0000000000000000000000000000000000000000" } } } ) burned: sum( of: Transfer_Amount if: { Transfer: { Receiver: { is: "0x0000000000000000000000000000000000000000" } } } ) } } } ``` ### Getting Marketcap ```graphql { EVM(dataset: combined) { Transfers( limit: {count: 1} where: {Call: {Create: true}, Transfer: {Currency: {SmartContract: {is: "0x0f7dc5d02cc1e1f5ee47854d534d332a1081ccc8"}}, Sender: {is: "0x0000000000000000000000000000000000000000"}}} ) { Transfer { Amount Sender Receiver } joinDEXTradeByTokens( limit: {count: 1} join: inner Trade_Currency_SmartContract: Transfer_Currency_SmartContract ) { Trade { Price(maximum: Block_Time) PriceInUSD } } } } } ``` First the query gets supply in the `amount` field then query uses join to get the `PriceInUSD`. Multiplying both of these will give you marketcap of the token. In this example, we are calculating marketcap of Pepes Dog (ZEUS) token which has smart contract address `0x0f7dC5D02CC1E1f5Ee47854d534D332A1081cCC8`. Try the query [here](https://ide.bitquery.io/supply-and-latest-price-of-token-to-get-marketcap). ## Video Tutorial --- ## Get the Latest Block Number with Bitquery Instead of eth_blockNumber URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/eth_blockNumber/ Latest Ethereum block number and time by GraphQL query or WebSocket stream, with the same call for BSC, Base and other EVM chains. # Get the Latest Block Number with Bitquery Instead of eth_blockNumber `eth_blockNumber` is the JSON-RPC call that returns the height of the newest block. On Bitquery the same answer comes from the `Blocks` cube in two shapes: a query that returns the newest block with its timestamp, and a subscription that pushes a row every time a block is produced, so you never poll. Both run on Ethereum and, by changing `network`, on BNB Chain, Base, Arbitrum, Optimism, Polygon, Robinhood Chain and Arc. No node, no RPC key: an access token from [account.bitquery.io](https://account.bitquery.io/) and the same query runs in the [IDE](https://ide.bitquery.io) on a free account. ## Latest block number as a query One row, sorted by block number descending. `Time` is the block timestamp, so the same row tells you how fresh the tip is. ```graphql { EVM(network: eth) { Blocks(limit: { count: 1 }, orderBy: { descending: Block_Number }) { Block { Number Time } } } } ``` ## Latest block number as a stream Every new Ethereum block arrives as one message. Open it in the IDE [here](https://ide.bitquery.io/eth_blockNumber-stream). ```graphql subscription { EVM(network: eth) { Blocks { Block { Number } } } } ``` ## Other EVM chains Change the network name and nothing else. This is the BNB Chain stream, saved [here](https://ide.bitquery.io/eth_blockNumber-stream-bsc); `base`, `arbitrum`, `optimism`, `matic`, `robinhood` and `arc` work the same way. ```graphql subscription { EVM(network: bsc) { Blocks { Block { Number } } } } ``` ## What else the Blocks cube returns Add fields to the same selection: `Block { Hash ParentHash Time Number GasUsed GasLimit BaseFee Difficulty }` and `TxCount`. That covers `eth_getBlockByNumber` for the header, without a second call. For the transactions inside a block, filter the `Transactions` cube on `Block: { Number: { is: "..." } }`; the [EVM blocks schema](/docs/schema/evm/blocks) lists every field. ## Related pages - [EVM blocks schema](/docs/schema/evm/blocks) - [debug_traceCall with Bitquery](/docs/blockchain/Ethereum/ethers-library/debug_traceCall) - [WebSocket subscriptions](/docs/subscriptions/subscription) - [Ethereum API hub](/docs/blockchain/Ethereum/) --- ## Getting Latest Pairs URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/latest-trading-pairs-api/ Getting Latest Pairs: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. Keep queries fast with indexed filters. # Getting Latest Pairs ## Latest Trading Pairs for a DEX Let's see how we can get latest trading pairs created on DEXs. In this example we use Smart Contract Events to track PoolCreated event for [Uniswap v3 factory contract](https://explorer.bitquery.io/ethereum/smart_contract/0x1f98431c8ad98523631ae4a59f267346ea31f984/events). Because whenever a new pool gets created Uniswap v3 factory contract emits a PoolCreated event with the details of the pool. ```graphql { EVM(dataset: realtime, network: eth) { Events( orderBy: {descending: Block_Number} limit: {count: 10} where: {Log: {SmartContract: {is: "0x1f98431c8ad98523631ae4a59f267346ea31f984"}, Signature: {Name: {is: "PoolCreated"}}}} ) { Log { Signature { Name Parsed Signature } SmartContract } Transaction { Hash } Block { Date Number } Arguments { Name Value { __typename ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` Open this query on our GraphQL IDE using this [link](https://ide.bitquery.io/uniswap-v3-pairs). ## Subscribe to the Latest Pairs for Uniswap V3 You can use our GraphQL Subscription (Webhook) to subscribe to these events in case you don't want to call our APIs periodically. ```graphql subscription { EVM { Events( where: {Log: {SmartContract: {is: "0x1f98431c8ad98523631ae4a59f267346ea31f984"}, Signature: {Name: {is: "PoolCreated"}}}} ) { Log { Signature { Name Parsed Signature } SmartContract } Transaction { Hash } Block { Date Number } Arguments { Name Value { __typename ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` Open this query on our GraphQL IDE using this [link](https://ide.bitquery.io/uniswap-v3-pairs-websocket) --- ## NFT Blur MarketPlace API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/nft/nft-blur-marketplace-api/ NFT Blur MarketPlace API: track Ethereum NFT trades, ownership, and metadata with Bitquery GraphQL and streams. Covers archive history and realtime data. # NFT Blur MarketPlace API The NFT Blur Marketplace API provides a wide range of data related to the BLUR NFT Marketplace. With this API, We can access data on the latest traded NFTs, buy-sell activity of specific NFT tokens, top buyers of NFTs, specific buyer statistics for NFTs, NFT loan transactions, loan history, refinancing actions and much more. ## Stream Blur trades in real time Every query on this page has a streaming equivalent: change `query` to `subscription` and drop the ordering, since a stream is already in block order. This one pushes each Blur trade as it settles. ```graphql subscription BlurTradeStream { EVM(network: eth) { DEXTrades( where: { Trade: { Dex: { ProtocolName: { is: "seaport_v1.4" } } } } ) { Block { Time } Transaction { Hash } Trade { Dex { ProtocolName } Buy { Buyer Amount Currency { Name SmartContract Fungible } } Sell { Seller Amount Currency { Symbol } } } } } } ``` Blur settles through Seaport, so this filter catches Blur alongside other Seaport-routed marketplaces. `Buy.Currency.Fungible` is the field that separates the NFT leg from the payment leg. ## Latest Trades on Blur The Blur Marketplace supports the [Seaport protocol](https://opensea.io/blog/articles/introducing-seaport-protocol), which can be utilize to retrieve the most recent Blur trades - [query](https://ide.bitquery.io/Latest-10-Trades-on-Blur). ```graphql query MyQuery { EVM { DEXTrades( limit: { offset: 0, count: 10 } orderBy: { descendingByField: "Block_Time" } where: { Trade: { Dex: { ProtocolName: { is: "seaport_v1.4" } } } Transaction: { To: { is: "0x39da41747a83aeE658334415666f3EF92DD0D541" } } } ) { Trade { Dex { ProtocolName } Buy { Price Seller Buyer Currency { HasURI Name Fungible SmartContract } } Sell { Price Amount Currency { Name } Buyer Seller } } Transaction { Hash } Block { Time } } } } ``` **Parameters** - `limit` : Specifies the number of results to return and the offset from where to start. - `orderBy` : Organizes the results in descending order based on the block time. - `where` : Filters results based on specific conditions. Here, it selects trades where the DEX protocol name is "seaport_v1.4" and the transaction 'To' address is set to the Blur Marketplace contract. **Returned Data** - `Trade` : Provides details about the trade including the DEX protocol name, and the buy and sell details such as price, seller, buyer, and currency information. - `Transaction` : Contains the hash of the transaction associated with the trade. - `Block` : Shows the block time when the trade occurred. ## Most Traded NFTs on Blur Marketplace We can also identify the most traded NFT on the Blur Marketplace using this API. In the following [query](https://ide.bitquery.io/Most-traded-NFT-on-Blur-marketplace), we aggregate the data based on buyers, sellers, NFTs, and trade volume, and then sort the results based on the trade count. This highlights the most active NFTs in the marketplace. ```graphql query MyQuery { EVM(dataset: combined, network: eth) { DEXTrades( where: {Trade: {Dex: {ProtocolName: {in: "seaport_v1.4"}}}, Transaction: {To: {is: "0x39da41747a83aeE658334415666f3EF92DD0D541"}}} orderBy: {descendingByField: "count"} limit: {count: 10} ) { tradeVol: sum(of: Trade_Buy_Amount) count buyers: count(distinct: Trade_Buy_Buyer) seller: count(distinct: Trade_Buy_Seller) nfts: count(distinct: Trade_Buy_Ids) Trade { Buy { Currency { Name ProtocolName Symbol Fungible SmartContract } } } } } } ``` **Parameters** - `where` : This filters out the trades where the DEX protocol name matches "seaport_v1.4", and the transaction is directed to the Blur Marketplace contract. - `orderBy` : This arranges the results in a descending order according to the count of trades. - `limit` : This confines the number of results to the top 10 most traded NFTs. **Returned Data** - `tradeVol` : Represents the total sum of trade buy amounts. - `count` : Represents the number of trades for each NFT. - `buyers` : Displays the count of distinct buyers involved in these trades. - `sellers` : Displays the count of distinct sellers involved in these trades. - `nfts` : Shows the count of distinct NFTs involved in the trades. - `Trade` : Includes information about the trade, specifically the currency details from the buy side of the trade. ## Total Buy-Sell of an NFT Token on Blur Here, the [query](https://ide.bitquery.io/Total-buy-sell-of-an-NFT-token-onBLUR) gather total trades, trade volume, unique buyers, and sellers for a specific NFT token on Blur Marketplace - in this case, the [Nakamigos NFT token](https://explorer.bitquery.io/ethereum/token/0xd774557b647330c91bf44cfeab205095f7e6c367). ```graphql query MyQuery { EVM(dataset: combined, network: eth) { DEXTrades( where: {Trade: {Dex: {ProtocolName: {in: "seaport_v1.4"}}, Buy: {Currency: {Fungible: false, SmartContract: {is: "0xd774557b647330c91bf44cfeab205095f7e6c367"}}}}, Transaction: {To: {is: "0x39da41747a83aeE658334415666f3EF92DD0D541"}}} orderBy: {descendingByField: "count"} limit: {count: 10} ) { tradeVol: sum(of: Trade_Buy_Amount) count buyer: count(distinct: Trade_Buy_Buyer) seller: count(distinct: Trade_Buy_Seller) nfts: count(distinct: Trade_Buy_Ids) Trade { Buy { Currency { Name ProtocolName Symbol Fungible SmartContract } } } } } } ``` **Parameters** - `where` : 'Trade.Buy.Currency.Fungible' filters out the trades where the currency is non-fungible. 'Trade.Buy.Currency.SmartContract' sets the smart contract address to match that of the Nakamigos NFT token. **Returned Data** - `nfts` : Shows the count of distinct Nakamigos NFT tokens involved in the trades. - `Trade.Buy.Currency` : Includes information about the Nakamigos NFT token. ## Identifying Top NFT Buyers on Blur In [this](https://ide.bitquery.io/Top-buyers-of-NFTs-onBLUR) query, we fetch the top buyers on the BLUR marketplace. We aggregate based on NFTs bought, unique transactions, and then sort them based on the number of trades ```graphql query MyQuery { EVM(dataset: combined, network: eth) { DEXTrades( where: { Trade: { Dex: { ProtocolName: { in: "seaport_v1.4" } } Buy: { Currency: { Fungible: false } } } Transaction: { To: { is: "0x39da41747a83aeE658334415666f3EF92DD0D541" } } } orderBy: { descendingByField: "count" } limit: { count: 10 } ) { count uniq_tx: count(distinct: Transaction_Hash) Block { first_date: Time(minimum: Block_Date) last_date: Time(maximum: Block_Date) } nfts: count(distinct: Trade_Buy_Ids) difffernt_nfts: count(distinct: Trade_Buy_Currency_SmartContract) total_money_paid: sum(of: Trade_Sell_Amount) Trade { Buy { Buyer } } } } } ``` **Parameters** - `where` : 'Trade.Buy.Currency.Fungible' filter makes sure to only consider non-fungible tokens in the trades. **Returned Data** - `uniq_tx` : Represents the number of unique transactions made by each buyer. - `Block` : Shows the first and last dates of transactions made by each buyer. - `nfts` : Provides a count of unique NFTs bought by each buyer. - `difffernt_nfts` : Displays a count of different NFTs bought by each buyer. - `total_money_paid` : The total amount of money paid by each buyer for their purchases. ## Specific Buyer stats for an NFT on Blur In [this](https://ide.bitquery.io/Specific-buyer-stats-for-an-NFT-onBLUR) query, we are getting details for a specific address on Blur NFT marketplace. We are also getting the first and last trade dates for the address. ```graphql query MyQuery { EVM(dataset: combined, network: eth) { DEXTrades( where: { Trade: { Dex: { ProtocolName: { in: "seaport_v1.4" } } Buy: { Currency: { SmartContract: { is: "0xd774557b647330c91bf44cfeab205095f7e6c367" } } Buyer: { is: "0x9ba58eea1ea9abdea25ba83603d54f6d9a01e506" } } } Transaction: { To: { is: "0x39da41747a83aeE658334415666f3EF92DD0D541" } } } orderBy: { descendingByField: "count" } limit: { count: 10 } ) { count uniq_tx: count(distinct: Transaction_Hash) Block { first_date: Time(minimum: Block_Date) last_date: Time(maximum: Block_Date) } nfts: count(distinct: Trade_Buy_Ids) Trade { Buy { Buyer Currency { Name ProtocolName Symbol Fungible SmartContract } } } } } } ``` **Parameters** - `where` : 'Trade.Buy.Buyer' filters the trades made by a specific buyer. 'Trade.Buy.Currency.SmartContract' filters to include only the trades involving a specific NFT token. **Returned Data** - `uniq_tx` : Represents the number of unique transactions made by the buyer. - `Block` : Shows the first and last dates of trades made by the buyer. - `nfts` : Provides a count of unique NFTs bought by the buyer. ## Latest Loans taken on Blur Blur uses [Blend protocol](https://www.paradigm.xyz/2023/05/blend) for NFT loans. We're can [fetch](https://ide.bitquery.io/Latest-Loans-taken-onBlur) recent loans on the BLUR market through "LoanOfferTaken" events tied to Blur : [Blend Contract](https://explorer.bitquery.io/ethereum/smart_contract/0x29469395eaf6f95920e59f858042f0e28d98a20b/events). We're using LogHeader instead of Log → SmartContract for queries due to a [delegated proxy contract](https://medium.com/coinmonks/proxy-pattern-and-upgradeable-smart-contracts-45d68d6f15da). ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "LoanOfferTaken" } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Index Type Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** - `where` : 'LogHeader.Address' points to the Blur Blend Contract where the loan events are recorded. 'Log.Signature.Name' sets the event name to "LoanOfferTaken" to filter for loan-taking events. **Returned Data** - `Block.Number` : Block number where the event is recorded. - `Transaction.Hash` : Transaction hash corresponding to the loan event. - `Log.SmartContract` : Provides the address of the smart contract that emitted the event. - `Log.Signature` : Shows the name and signature of the event. - `Arguments` : Details of the arguments associated with the event, gives valuable information like loan amount, borrower address, and more. ## Latest loans for specific NFT token [This](https://ide.bitquery.io/Latest-loans-for-specific-NFTtoken) query retrieves all loans linked to the [MutantApeYachtClub](https://explorer.bitquery.io/ethereum/token/0x60e4d786628fea6478f785a6d7e704777c86a7c6) collection on the BLUR market. We filter event arguments in the smart contract and sort by block time ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "LoanOfferTaken" } } } Arguments: { includes: [ { Name: { is: "collection" } Value: { Address: { is: "0x60e4d786628fea6478f785a6d7e704777c86a7c6" } } } ] } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** - `where` : 'LogHeader.Address' points to the Blur: Blend Contract. 'Log.Signature.Name' sets the event name to "LoanOfferTaken". 'Arguments.includes' filter specifically checks for a collection argument with an Address value corresponding to the MutantApeYachtClub NFT collection. **Returned Data** Same as previous queries, this query will return details about the block, transaction, log, and arguments. By modifying the 'Arguments.includes' filter, you can track loan activities for different NFT collections on the Blur marketplace. ## Latest Loans for a specific lender Using argument filtering, [this](https://ide.bitquery.io/Latest-Loans-for-a-specificlender) query fetches the latest loans for a specific lender address. The same method can be applied to find loans for a specific borrower address - [query](https://ide.bitquery.io/Latest-Loans-for-a-specificborrower-on-Blur-marketplace). ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "LoanOfferTaken" } } } Arguments: { includes: [ { Name: { is: "lender" } Value: { Address: { is: "0xfa0e027fcb7ce300879f3729432cd505826eaabc" } } } ] } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** - `where` : 'LogHeader.Address' directs to the Blur: Blend Contract. 'Log.Signature.Name' sets the event name to "LoanOfferTaken". 'Arguments.includes' filter looks for a lender argument with an Address value matching the specific lender's address. **Returned Data** Similar to previous queries, this query will provide details about the block, transaction, log, and arguments. ## Loans above a specific amount on the Blur NFT marketplace If we want to track loans above a specific amount on the Blur marketplace, we can use the following [query](https://ide.bitquery.io/Loans-above-a-specific-amount-on-the-Blur-NFT-marketplace). ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "LoanOfferTaken" } } } Arguments: { includes: [ { Name: { is: "loanAmount" } Value: { BigInteger: { gt: "3000000000000000000" } } } ] } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` ## Loan history for specific NFT ID [This](https://ide.bitquery.io/Loan-history-for-specific-NFTID) query retrives the loan history for a specific NFT ID on the BLUR market, by matching event arguments to a particular collection address and tokenId. ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "LoanOfferTaken" } } } Arguments: { includes: [ { Name: { is: "collection" } Value: { Address: { is: "0x49cf6f5d44e70224e2e23fdcdd2c053f30ada28b" } } } { Name: { is: "tokenId" }, Value: { BigInteger: { eq: "2662" } } } ] } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** - `where` : 'LogHeader.Address' directs to the Blur: Blend Contract. 'Log.Signature.Name' sets the event name to "LoanOfferTaken". 'Arguments.includes' filter looks for collection argument matching a specific NFT collection address and tokenId argument equating to a specific NFT ID. **Returned Data** The response includes details about the block, transaction, log, and event arguments. By changing the values in 'Arguments.includes' you can query the loan history for different NFT IDs on the Blur marketplace. ## Get loan details for specific LienId The Blur's Blend protocol utilizes LienID as a primary key to track individual loan details. [This](https://ide.bitquery.io/Get-loan-details-for-specificlienId) query fetches details for a specific LienID across different events. ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "LoanOfferTaken" } } } Arguments: { includes: [ { Name: { is: "lienId" }, Value: { BigInteger: { eq: "40501" } } } ] } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** - `where` : 'Arguments.includes' filters for the lienId argument equating to a specific LienID. **Returned Data** The response will include details about the block, transaction, log, and event arguments. By adjusting the LienID in Arguments.includes, you can fetch loan details for various LienIDs on the Blur marketplace. ## Latest Loan Refinances on Blur Refinancing in NFTs refers to securing a new loan using an NFT as collateral to repay an existing loan. The following [query](https://ide.bitquery.io/loan-refinance-on-Blur) retrieves the latest refinance events on BLUR. ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "Refinance" } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Index Type Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** `where` : 'LogHeader.Address' sets the address to the Blur: Blend Contract. 'Log.Signature.Name' filters for the event name "Refinance". ## All Refinance loans for specific NFT To retrieve all refinance loans for a specific NFT collection, we filter Refinance event arguments in [this](https://ide.bitquery.io/All-refinance-loans-for-specificNFT-collection) query ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "Refinance" } } } Arguments: { includes: [ { Name: { is: "collection" } Value: { Address: { is: "0xed5af388653567af2f388e6224dc7c4b3241c544" } } } ] } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Index Type Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` ## Loan Repayments For loan repayment transactions on the BLUR market, use the [following](https://ide.bitquery.io/Loan-repayment-of-blur-marketplace) query. It filters 'Repay' events and sets the smart contract address to the Blur: Blend address ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "Repay" } } } Arguments: { includes: [ { Name: { is: "lienId" }, Value: { BigInteger: { eq: "43662" } } } ] } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Index Type Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** - `where` : 'LogHeader.Address' sets the address to the Blur: Blend Contract. 'Log.Signature.Name' filters for the event name "Repay". 'Arguments.includes' Filters for the "lienId" argument to match a specific LienID. **Returned Data** The response contains details about the block, transaction, log, and arguments, allowing users to track loan repayment transactions associated with the specified LienID on the Blur marketplace. ## Auction Events The 'StartAuction' event is triggered when an NFT auction starts on the Blur : [Blend Contract](https://explorer.bitquery.io/ethereum/smart_contract/0x29469395eaf6f95920e59f858042f0e28d98a20b/events). The following [query](https://ide.bitquery.io/Auction-on-blur-marketplace) monitors these events. If you want to track auctions for a specific NFT, modify the [query](https://ide.bitquery.io/Auctions-for-specific-lienID) to filter for a specific LienID in the 'Arguments' field. ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "StartAuction" } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Index Type Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** `where` : 'LogHeader.Address' sets the address to the Blur: Blend Contract. 'Log.Signature.Name' filters for the event name "StartAuction". ## Latest Locked NFTs Buy Trades Locked NFTs are temporarily non-transferrable and can be traded or transferred after the lock period. These NFTs are often cheaper than non-locked. The following [query](https://ide.bitquery.io/Locked-NFT-bought-on-Blur-marketplace) retrieves the latest trades of locked NFTs by filtering for the 'BuyLocked' event under the Blur : [Blend Contract](https://explorer.bitquery.io/ethereum/smart_contract/0x29469395eaf6f95920e59f858042f0e28d98a20b/events). ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "BuyLocked" } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Index Type Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** `where` : 'LogHeader.Address' sets the address to the Blur: Blend Contract. 'Log.Signature.Name' Filters for the event name "BuyLocked". ## Get Cancelled Offers On the BLUR market, the 'OfferCancelled' event initiates when an offer is withdrawn or cancelled. The following [query](https://ide.bitquery.io/Latest-Cancelled-offers-on-Blur-NFT-marketplace) fetches recent 'OfferCancelled' events under the Blur : [Blend Contract](https://explorer.bitquery.io/ethereum/smart_contract/0x29469395eaf6f95920e59f858042f0e28d98a20b/events). . ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "OfferCancelled" } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Index Type Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** - `where` : 'LogHeader.Address' sets the address to the Blur : Blend Contract. `Log.Signature.Name` filters for the event name "OfferCancelled". ## Get Seize Offers When a seizure event happens, control of the NFT shifts to the lender or an enforcing third party. The [query](https://ide.bitquery.io/Latest-Seized-NFTs-on-Blur-marketplace) filters transactions for the 'seize' event on the Blur : [Blend Contract](https://explorer.bitquery.io/ethereum/smart_contract/0x29469395eaf6f95920e59f858042f0e28d98a20b/events) to track these ```graphql { EVM(dataset: combined, network: eth) { Events( where: { LogHeader: { Address: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } Log: { Signature: { Name: { is: "Seize" } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Number } Transaction { Hash } Log { SmartContract Signature { Name Signature } } Arguments { Name Index Type Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } } } } ``` **Parameters** - `where`: 'LogHeader' filters the results where the Address matches the Blur: Blend contract address. 'Log' Further filters the results where the Name of Signature matches the "Seize" event. **Returned Data** - `Log` : Information about the event log, including the smart contract that emitted the event and the event's name and signature. - `Arguments` : Details of the arguments passed in the event, including their names, indexes, types, and values. --- ## NFT Token Transfers API: ERC-721 and ERC-1155 Transfers on Ethereum URL: https://docs.bitquery.io/docs/blockchain/Ethereum/transfers/nft-token-transfer-api/ NFT transfers on Ethereum with Bitquery GraphQL: a collection's latest transfers from history, every NFT transfer as a stream, one wallet's activity, mints. # NFT Token Transfers API: ERC-721 and ERC-1155 Transfers on Ethereum NFT transfers on Ethereum live in the same `Transfers` cube as token transfers, marked by `Currency.Fungible: false` and carrying the token `Id`, the collection contract, sender, receiver and, for ERC-1155, the amount. That means one cube answers the collection question, the wallet question and the mint question, and the same filter runs as a query over history or as a live subscription. Every example runs in the [IDE](https://ide.bitquery.io). Queries on the `archive` or `combined` dataset need an archive add-on; the free trial is real-time only. The worked collection is CryptoKitties, `0x06012c8cf97bead5deae237070f9587f8e7a266d`, which still changes hands a few times a day, nine years after launch. For collection-level views such as token lists and holders see the [NFT collection API](/docs/blockchain/Ethereum/nft/nft-collection-api). ## Latest transfers of one collection The `combined` dataset reaches history, so this works for a collection whether it moved a minute ago or a year ago. Saved query [here](https://ide.bitquery.io/Cryptokitties-Token-Transfers). ```graphql { EVM(dataset: combined, network: eth) { Transfers( where: { Transfer: { Currency: { SmartContract: { is: "0x06012c8cf97bead5deae237070f9587f8e7a266d" } } } } limit: { count: 20 } orderBy: { descending: Block_Time } ) { Block { Time Number } Transfer { Id Sender Receiver Currency { Name Symbol SmartContract } } Transaction { Hash } } } } ``` ## Every NFT transfer on Ethereum, live Drop the contract and keep `Fungible: false` to stream all ERC-721 and ERC-1155 transfers as blocks are indexed. Saved stream [here](https://ide.bitquery.io/ERC721-token-transfers). ```graphql subscription { EVM(network: eth) { Transfers(where: { Transfer: { Currency: { Fungible: false } } }) { Block { Time } Transfer { Id Amount Sender Receiver Currency { Name Symbol SmartContract } } Transaction { Hash } } } } ``` Add the collection contract back into the filter to stream one collection; a quiet collection can then go hours between messages, so check it with the query above first. ## One wallet's NFT activity An `any` block matches transfers where the wallet is the sender or the receiver. The example is a large BAYC holder. ```graphql { EVM(dataset: combined, network: eth) { Transfers( where: { Transfer: { Currency: { Fungible: false } } any: [ { Transfer: { Sender: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } } { Transfer: { Receiver: { is: "0x29469395eaf6f95920e59f858042f0e28d98a20b" } } } ] } limit: { count: 20 } orderBy: { descending: Block_Time } ) { Block { Time } Transfer { Id Sender Receiver Currency { Name SmartContract } } Transaction { Hash } } } } ``` ## Mints A mint is a transfer from the zero address; the receiver is the minter. For CryptoKitties a mint is a kitty being born. ```graphql { EVM(dataset: combined, network: eth) { Transfers( where: { Transfer: { Currency: { SmartContract: { is: "0x06012c8cf97bead5deae237070f9587f8e7a266d" } } Sender: { is: "0x0000000000000000000000000000000000000000" } } } limit: { count: 20 } orderBy: { descending: Block_Time } ) { Block { Time } Transfer { Id Receiver } Transaction { Hash } } } } ``` ## Fields worth knowing - `Transfer.Id` is the token id; `Transfer.Amount` is 1 for ERC-721 and the quantity for ERC-1155. - `Transfer.URI` is the metadata link when the contract exposes one; fetch it yourself for the image and attributes. - `Currency.Fungible` is the ERC-721/1155 flag; `Currency.HasURI` says whether a URI exists. - `dataset: combined` on the `EVM` root joins archive and realtime; without it a query reads the realtime window only. ## Related pages - [Ethereum NFT collection API](/docs/blockchain/Ethereum/nft/nft-collection-api) - [Ethereum NFT API](/docs/blockchain/Ethereum/nft/nft-api) - [Ethereum token transfers API](/docs/blockchain/Ethereum/transfers/erc20-token-transfer-api) - [Transfers cube](/docs/cubes/transfers-cube) --- ## Pair Creation Time API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/pair-creation-time/ Pair Creation Time API: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. See examples in the Bitquery IDE. # Pair Creation Time API ## Pair Creation Time for a Specific Pair Let's see how we can get pair creation time for a specific pair. We will use Events API for this. Filter for `PairCreated` event and also put one more filter, for which pair address you want the creation time. We have used `0x5c6919B79FAC1C3555675ae59A9ac2484f3972F5` pair address in our example. Open this query on our GraphQL IDE using this [link](https://ide.bitquery.io/when-a-pair-was-created-for-EVM). ```graphql query MyQuery { EVM(network: eth, dataset: combined) { Events( where: { Log: { Signature: { Name: { is: "PairCreated" } } } TransactionStatus: { Success: true } Arguments: { includes: { Value: { Address: { is: "0x5c6919B79FAC1C3555675ae59A9ac2484f3972F5" } } } } } ) { Block { Time } Transaction { Hash } } } } ``` ## Track newly created pairs on uniswap v3 You can track newly created pairs on uniswap v3. Open this query on our GraphQL IDE using this [link](https://ide.bitquery.io/Latest-pools-created-Uniswap-v3_9). ```graphql subscription { EVM(network: eth) { Events( orderBy: { descending: Block_Number } limit: { count: 10 } where: { Log: { SmartContract: { is: "0x1f98431c8ad98523631ae4a59f267346ea31f984" } Signature: { Name: { is: "PoolCreated" } } } } ) { Log { Signature { Name Parsed Signature } SmartContract } Transaction { Hash } Block { Date Number } Arguments { Type Value { ... on EVM_ABI_Boolean_Value_Arg { bool } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_Integer_Value_Arg { integer } } Name } } } } ``` --- ## RWA (Real World Assets) API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/transfers/rwa-api/ RWA (Real World Assets) API: monitor Ethereum native and token transfers in real time with Bitquery GraphQL APIs. Built for traders and analytics teams. # RWA (Real World Assets) API In this section, we will explore some of the APIs that help us obtain information about Real World Assets (RWAs) on Ethereum, Arbitrum, and other EVM chains. These APIs can be executed on any EVM chain simply by changing the `network: eth` parameter to the appropriate chain and using the correct address. We have written about analyzing RWA data in the blog [here](https://bitquery.io/blog/real-world-asset-tracking-arbitrum-bitquery-apis) and how it has influenced tokenized real-estate [here](https://bitquery.io/blog/tokenized-real-estate-transforming-property-investment). ## Top Holders of an RWA You can view and execute the query for the top holders of an RWA using the following examples: - [Top holder stats for Mountain's USDM](https://ide.bitquery.io/top-holder-stats-for-Mountains-USDM) - [Top holder stats for Backed Finance’s blB01](https://ide.bitquery.io/top-holder-stats-for-Backed-Finances-blB01) ```graphql { EVM(dataset: archive, network: eth) { Holders( date: "2025-04-22" limit: { count: 10 } orderBy: { descending: Balance_Amount }, where: { Currency: { SmartContract: { is: "0x59D9356E565Ab3A36dD77763Fc0d87fEaf85508C" } } } ) { Holder { Address } Balance { UpdateCount } Balance { Amount } } } } ``` This query retrieves the top 10 holders of the specified token contract, ranked by their balance amount. ## Real-time Transfers of RWAs on Arbitrum You can monitor real-time transfers of RWAs using the stream link below: [Real-time Transfers of Xend Real World Asset Token](https://ide.bitquery.io/Subscribe-to-Latest-Xend-Real-World-Asset-token-transfers) ```graphql subscription { EVM(network: arbitrum) { Transfers( where: { Transfer: { Currency: { SmartContract: { is: "0x3096e7BFd0878Cc65be71f8899Bc4CFB57187Ba3" } } } } ) { Transaction { Hash } Transfer { Amount Currency { Name Symbol } Receiver Sender Type } } } } ``` This subscription continuously monitors and provides real-time updates on token transfers for the specified token contract. ## Latest Issuance of an RWA This query filters for recent `Issue` events on Ethereum and displays logs emitted by the fund’s smart contract (`0x7712c34205737192402172409a8F7ccef8aA2AEc`) and extracts structured event data. You can use the same as a `subscription` to monitor issuances in real-time. You can run the query [here](https://ide.bitquery.io/BlackRock-USD-Institutional-Digital-Liquidity-Fund-Latest-Issuance) ```graphql { EVM(dataset: realtime, network: eth) { Events( limit: {count: 20} where: {LogHeader:{Address:{is:"0x7712c34205737192402172409a8F7ccef8aA2AEc"}}, Log:{ Signature:{Name:{is:"Issue"}} }} ) { Block { Time Number Hash } Receipt { ContractAddress } Topics { Hash } TransactionStatus { Success } LogHeader { Address Index Data } Transaction { Hash From To Index } Log { EnterIndex ExitIndex Index LogAfterCallIndex Pc SmartContract Signature { Name Signature } } Arguments { Name Value { ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_String_Value_Arg { string } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Bytes_Value_Arg { hex } ... on EVM_ABI_Boolean_Value_Arg { bool } } } Call { Signature { Name } } } } } ``` --- ## Smart Contract Creation URL: https://docs.bitquery.io/docs/blockchain/Ethereum/calls/contract-creation/ Ethereum contract creation: subscribe to new smart contract deployments in real time, list creations since a date, get code, deployer and contract type. # Smart Contract Creation Smart contract creators can use these queries to track the deployment of their own smart contracts and to monitor the deployment of new smart contracts by others. ## Subscription to track new smart contract creation in real-time This subscription will return information on each new smart contract created on Ethereum. You can create a [websocket](/docs/subscriptions/websockets/) to monitor the same in real-time. ```graphql subscription { eth_creates: EVM(network: eth) { creates: Calls( where: { Call: { Create: true }}) { Block { Time } Transaction{ Hash From } Call { Input To Output } } } } ``` This subscription has information on - The block time in which the smart contract was created - The transaction hash that created the smart contract - The address of the sender of the transaction that created the smart contract - The address of the newly created smart contract - The input data for the transaction that created the smart contract - The output data from the transaction that created the smart contract ## Track new smart contract creation since a specific date This query below, will return the number of new smart contracts created on the Ethereum and Binance Smart Chain networks since a particular date. It will also return the date of each day on which new smart contracts were created. You can find the query [here](https://ide.bitquery.io/ETHBSC-SC-creates-count-over-date) ```graphql query { eth_creates: EVM(dataset: archive network: eth) { creates: Calls( where: { Block: {Date: {after: "2023-06-01"}} Call: { Create: true }}) { count Block { Date } } } bsc_creates: EVM(dataset: archive network: bsc) { creates: Calls( where: { Block: {Date: {after: "2023-06-01"}} Call: { Create: true }}) { count Block { Date } } } } ``` ## Get Code of the Token Contract This query will return the most recent transaction that created the token contract. The `Output` field of the Call object in the transaction contains the encoded bytecode of the contract. Replace `0xc923D39fA2d97fb4B660Fc66DAdB1421605975E0` with the token contract address that you want to get the code for. You can find the query [here](https://ide.bitquery.io/ByteCode-of-A-Token) ```graphql { eth_creates: EVM(dataset: archive, network: eth) { creates: Calls( where: {Call: {Create: true, To: {is: "0xc923D39fA2d97fb4B660Fc66DAdB1421605975E0"}}} limit: {count: 1} orderBy: {descending: Block_Time} ) { Block { Time } Transaction { Hash From To } Call { Output } } } } ``` ## Creator/Deployer of a smart contract You can use calls api to get smart contract creator or deployer of a smart contract. In the following example, where we getting deployer of deployer of `0xcd80c916b1194beb48abf007d0b79a7238436d56`. Try this query [here](https://ide.bitquery.io/creator--deployer-of-an-address_1). ```graphql { EVM(dataset: combined) { Calls( where: {Call: {Create: true}, Receipt: {ContractAddress: {is: "0xcd80c916b1194beb48abf007d0b79a7238436d56"}}} ) { Transaction { Hash From To } Block { Time Number } } } } ``` ## Get Contract Type of a Contract To determine the type of a contract and its details, we can use the Transfer API. By fetching the earliest transfer to the contract, we can get relevant details that indicate the contract type. `Abi`: Provides the contract function ABI, describing its inputs and structure. For example, `"Name": "swap",` tells us the given address has a **`swap`** function. This suggests the contract is likely a **DEX (Decentralized Exchange) or token swap contract**. You can run the query [here](https://ide.bitquery.io/Get-Contract-Type-in-v2) ```graphql query MyQuery { EVM(network: eth) { Transfers( limit: {count: 1} orderBy: {ascending: Block_Time} where: {Transfer: {Receiver: {is: "0x881d40237659c251811cec9c364ef91dc08d300c"}}} ) { Call { Create Signature { SignatureType Signature Parsed Name Abi } } } } } ``` --- ## SmartContract Calls API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/calls/smartcontract/ Ethereum smart contract calls: query the most recent contract calls and the calls that created new contracts on mainnet, with ready-to-run GraphQL examples. # SmartContract Calls API ## Smart Contract Calls API Guide > **Before you start**: Not sure when to use Calls vs Transfers vs Events vs DexTrades? Read our [Mental Model guide](/docs/start/mental-model-transfers-events-calls) to understand which primitive to use for your use case. This API helps retrieve information about smart contract transactions, including details about the contract function that was called, the input and output parameters, and more. With this data, you can build applications that interact with smart contracts, perform analytics on contract activity, and more. ## Recent Smart Contract Calls This query retrieves the most recent smart contract calls on the Ethereum network, focusing on contract creation calls. It provides comprehensive information about the call details, transaction data, and block information.
Click to expand GraphQL query ```graphql { EVM(dataset: realtime, network: eth) { Calls( limit: {count: 10} orderBy: {descending: Block_Time} ) { Call { LogCount InternalCalls Create EnterIndex ExitIndex } Transaction { Gas Hash From To Type Index } Block { Date } } } } ```
## Recent Smart Contract Creation Calls This GraphQL query fetches data from the "eth" network about the 10 most recent calls made in Ethereum that were contract creation calls. You can run the query [here](https://ide.bitquery.io/smart-contract-creation-on-EVM-chains) ```graphql query MyQuery { EVM(dataset: realtime, network: eth) { Calls( limit: {count: 10} orderBy: {descending: Block_Time} where: {Call: {Create: true}} ) { Call { LogCount InternalCalls Create EnterIndex ExitIndex } Transaction { Gas Hash From To Type Index } Block { Date } } } } ``` --- ## Token Transaction API URL: https://docs.bitquery.io/docs/blockchain/Ethereum/transactions/transaction-api/ Ethereum transactions: latest transactions, activity from or to an address, details by hash, next nonce, USD transaction value and internal transactions. # Token Transaction API The Transaction API provides access to transaction data on the blockchain. Transactions are the fundamental unit of account on a blockchain and represent the transfer of value from one address to another. The Transaction API allows users to query for transaction data by specifying filters such as transaction hash, sender or receiver address, gas price, and more. The API also provides information about the block that the transaction was included in, including block number and block timestamp. ## Latest Transactions This query is using the Transactions API to retrieve transaction data from the Binance Smart Chain (BSC) blockchain network in real-time. You can find the query [here](https://ide.bitquery.io/Last-transactions-with-cost)
Click to expand GraphQL query ```graphql query { EVM(dataset: realtime, network: bsc) { Transactions( limit: { count: 100 } orderBy: [{ descending: Block_Number }, { descending: Transaction_Index }] ) { Block { Time Number } Transaction { Hash Cost } } } } ```
**Parameters:** - `dataset`: The data source to be used by the query (in this case, "realtime") - `network`: The blockchain network to be queried (in this case, "bsc") - `limit`: Limits the number of returned results to 100. - `orderBy`: Sorts the results by two fields, in descending order: `Block_Number` and `Transaction_Index`. **Results:** - `Block`: The block information of each transaction, including the block number and timestamp. - `Transaction`: The transaction hash and cost (gas used multiplied by the gas price) ## Latest Transactions From or To an Address This query retrieves 100 recent transactions where the specified address is either the sender (`From`) or the receiver (`To`). It is achieved by using the `any` filter which serves as the OR condition. It can help monitor incoming and outgoing transactions of a particular address. You can run the query [here](https://ide.bitquery.io/Latest-Transactions-fromto-address)
Click to expand GraphQL query ```graphql { EVM(dataset: archive, network: eth) { Transactions( limit: {count: 100} where: {any: [{Transaction: {From: {is: "0x21a31ee1afc51d94c2efccaa2092ad1028285549"}}}, {Transaction: {To: {is: "0x21a31ee1afc51d94c2efccaa2092ad1028285549"}}}]} ) { Block { Time Number } Transaction { Hash Cost To From } } } } ```
## Get Transaction Details using Hash The below query retrieves transaction details using the transaction hash. The `where` clause filters transactions based on the `Hash` field, which is set to `0xc3684c0ea63c0e081fb779bb8feaa5e5109ccc70ef30f17f4eea041ec5ea0bc7`. You can find the query [here](https://ide.bitquery.io/Get-a-transaction-by-hash) ```graphql query MyQuery { EVM(dataset: combined, network: eth) { Transactions( where: {Transaction: {Hash: {is: "0xc3684c0ea63c0e081fb779bb8feaa5e5109ccc70ef30f17f4eea041ec5ea0bc7"}}} ) { Block { Time Number } Transaction { From To Hash Value } } } } ``` ## Next available nonce The following query helps you determine the next available nonce for an Ethereum account by getting the latest transaction in the mempool (broadcasted transactions). The returned nonce is the highest nonce used by the account in the mempool. To get the next available nonce for a new transaction, you should increment this value by 1. You can find the query [here](https://ide.bitquery.io/get-next-available-nonce) ```graphql query MyQuery { EVM(mempool: true, network: eth) { Transactions(limit: {count: 1}, orderBy: {descending: Block_Time}) { Transaction { Nonce } } } } ``` ## Transaction Value in USD In the below query we will use the field `Transaction_ValueInUSD` to get the total amount sent to a particular address in USD. You can find the query [here](https://ide.bitquery.io/Transaction-value-in-USD) ```graphql query MyQuery { EVM(network: eth) { in_txs: Transactions( where: {Transaction: {To: {is: "0xdac17f958d2ee523a2206206994597c13d831ec7"}}} ) { sum(of: Transaction_ValueInUSD) } } } ``` ## Internal Transactions A single transaction on a smart contract can result in multiple internal transactions, which interact with different smart contracts. The below query gets all internal transactions for a particular tx filtered using hash. You can run the query [here](https://ide.bitquery.io/internal-transactions-for-a-particular-tx) ```graphql query MyQuery { EVM(network: eth) { Calls( where: {Transaction: {Hash: {is: "0xd1a49976cb217c92eea2bf897d8fe760333047fb555c261f7d2c96ea52901434"}}} ) { Call { Create Index From To ValueInUSD Value Output Signature { Signature Name } } Transaction { Hash } } } } ``` **Response** - **Call** - **Create**: Indicates if the call created a contract. - **Index**: The index of the call within the transaction. - **From**: The address from which the internal transaction was sent. - **To**: The recipient address of the internal transaction. - **Output**: The output data of the call. - **Signature**: Contains signature information. - **Signature**: The signature of the call. - **Name**: The name of the function called. - **Transaction** - **Hash**: The hash of the main transaction. --- ## Uniswap V3 Position API: Mints, Burns, Liquidity Changes and Fee Collections URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/uniswap-position-api/ Uniswap V3 positions on Ethereum via Bitquery GraphQL: mints with token IDs, burns, liquidity increases and decreases, fee collections, and V4 ModifyLiquidity. # Uniswap V3 Position API: Mints, Burns, Liquidity Changes and Fee Collections Every Uniswap V3 liquidity position on Ethereum is an NFT issued by the NonfungiblePositionManager, `0xc36442b4a4522e871399cd717abdd847ab11fe88`. The contract's calls and events are the whole lifecycle: `mint` creates a position and returns its token ID, `increaseLiquidity` and `decreaseLiquidity` resize it, `Collect` pays out fees, `burn` destroys it. Bitquery decodes all of them in the `Calls` and `Events` cubes, arguments and return values included, and the contract sees a steady flow of position changes and fee collections every hour. Every example below runs in the [IDE](https://ide.bitquery.io) on a free account against the realtime dataset, which is where decoded call arguments and returns live; the archive dataset does not serve the `Calls` cube. Uniswap V4 keeps positions inside its PoolManager instead, and the last section covers it. ## New positions with their token IDs `mint` calls from the last day, newest first. The `params` struct arrives as one argument per member in contract order: token0, token1, fee, tickLower, tickUpper, amount0Desired, amount1Desired, amount0Min, amount1Min, recipient, deadline. `Returns` carries the new `tokenId`, the `liquidity` minted and the two amounts pulled in. Saved query [here](https://ide.bitquery.io/recent-uniswap-position-NFTs-mint_1). ```graphql { EVM(network: eth) { Calls( where: { Call: { Signature: { Name: { is: "mint" } } To: { is: "0xc36442b4a4522e871399cd717abdd847ab11fe88" } } Block: { Time: { since_relative: { hours_ago: 24 } } } } limit: { count: 20 } orderBy: { descending: Block_Time } ) { Block { Time } Transaction { From Hash } Arguments { Name Path { Name } Value { ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Integer_Value_Arg { integer } } } Returns { Name Value { ... on EVM_ABI_BigInt_Value_Arg { bigInteger } } } } } } ``` The same filter as a subscription delivers each new position as it is minted; expect one every few minutes rather than a firehose. ```graphql subscription { EVM(network: eth) { Calls( where: { Call: { Signature: { Name: { is: "mint" } } To: { is: "0xc36442b4a4522e871399cd717abdd847ab11fe88" } } } ) { Block { Time } Transaction { From Hash } Returns { Name Value { ... on EVM_ABI_BigInt_Value_Arg { bigInteger } } } } } } ``` ## Closed positions `burn` destroys the NFT once its liquidity is zero and fees are collected. The only argument is the token ID. Saved query [here](https://ide.bitquery.io/Uniswap-v3-weth-usdt-burn-calls-only). ```graphql { EVM(network: eth) { Calls( where: { Call: { Signature: { Name: { is: "burn" } } To: { is: "0xc36442b4a4522e871399cd717abdd847ab11fe88" } } Block: { Time: { since_relative: { hours_ago: 24 } } } } limit: { count: 20 } orderBy: { descending: Block_Time } ) { Block { Time } Transaction { From Hash } Arguments { Name Value { ... on EVM_ABI_BigInt_Value_Arg { bigInteger } } } } } } ``` ## Liquidity added to or removed from a position `increaseLiquidity` and `decreaseLiquidity` keep the token ID and change the size. The `params` members arrive in order: tokenId, then the desired and minimum amounts for `increaseLiquidity` or the liquidity to remove and the minimum amounts for `decreaseLiquidity`, then the deadline. `Returns` gives the liquidity delta and the token amounts moved. Saved query [here](https://ide.bitquery.io/uniswap-v3-liquidity-increase-decrease). ```graphql { EVM(network: eth) { Calls( where: { Call: { Signature: { Name: { in: ["increaseLiquidity", "decreaseLiquidity"] } } To: { is: "0xc36442b4a4522e871399cd717abdd847ab11fe88" } } Block: { Time: { since_relative: { hours_ago: 24 } } } } limit: { count: 20 } orderBy: { descending: Block_Time } ) { Block { Time } Call { Signature { Name } } Transaction { From Hash } Arguments { Name Value { ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Integer_Value_Arg { integer } } } Returns { Name Value { ... on EVM_ABI_BigInt_Value_Arg { bigInteger } } } } } } ``` ## Position details by token ID `positions(tokenId)` is a view function, but contracts call it on-chain all day, and each recorded call returns the full position: `token0`, `token1`, `fee`, `tickLower`, `tickUpper`, `liquidity`, the fee growth counters and the tokens owed. Add the commented `Arguments` filter to pin one token ID. Saved query [here](https://ide.bitquery.io/uniswap-v3-weth-usdt-positions-of-tokenid-with-returns). ```graphql { EVM(network: eth) { Calls( where: { Call: { Signature: { Name: { is: "positions" } } To: { is: "0xc36442b4a4522e871399cd717abdd847ab11fe88" } } # Arguments: { includes: { Value: { BigInteger: { eq: "1360638" } } } } Block: { Time: { since_relative: { hours_ago: 24 } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { Block { Time } Call { From } Arguments { Name Value { ... on EVM_ABI_BigInt_Value_Arg { bigInteger } } } Returns { Name Value { ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_Address_Value_Arg { address } } } } } } ``` ## Fee collections The `Collect` event on the position manager names the `tokenId`, the `recipient` and the raw `amount0` and `amount1` paid out. Filtering on the log's contract catches collections routed through other contracts as well as direct calls. Saved query [here](https://ide.bitquery.io/Fee-collection-on-Uniswap-v3-Positions). ```graphql { EVM(network: eth) { Events( where: { Log: { SmartContract: { is: "0xc36442b4a4522e871399cd717abdd847ab11fe88" } Signature: { Name: { is: "Collect" } } } } limit: { count: 20 } orderBy: { descending: Block_Time } ) { Block { Time } Transaction { Hash From } Arguments { Name Value { ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Address_Value_Arg { address } } } } } } ``` ## Uniswap V4 positions V4 has no position NFT contract of its own: the PoolManager, `0x000000000004444c5dc75cb358380d2e3de08a90`, emits `ModifyLiquidity` with the pool `id`, the `sender`, `tickLower`, `tickUpper`, the signed `liquidityDelta` and the position `salt`. A positive delta adds liquidity and a negative one removes it. Saved query [here](https://ide.bitquery.io/Latest-ModifyLiquidity-Events-on-Uniswap-v4). ```graphql { EVM(network: eth) { Events( where: { Log: { SmartContract: { is: "0x000000000004444c5dc75cb358380d2e3de08a90" } Signature: { Name: { is: "ModifyLiquidity" } } } } limit: { count: 20 } orderBy: { descending: Block_Time } ) { Block { Time } Transaction { From Hash } Arguments { Name Value { ... on EVM_ABI_BigInt_Value_Arg { bigInteger } ... on EVM_ABI_Integer_Value_Arg { integer } ... on EVM_ABI_Address_Value_Arg { address } ... on EVM_ABI_Bytes_Value_Arg { hex } } } } } } ``` ## Turning ticks into a price band A position earns fees only while the pool price sits between its ticks. The price at a tick is `1.0001 ^ tick` in token1 per token0 raw units, so a position with `tickLower` of -100 and `tickUpper` of 100 covers roughly 0.990 to 1.010. Multiply by `10 ^ (decimals0 - decimals1)` to get a human price, and invert it if you want token0 per token1. The tick values come from the `mint` arguments, the `positions` returns or the V4 `ModifyLiquidity` event above. ## Related pages - [Uniswap API on Ethereum](/docs/blockchain/Ethereum/dextrades/uniswap-api/) - [Uniswap v4 API on Ethereum](/docs/blockchain/Ethereum/dextrades/uniswap-v4-api) - [Ethereum liquidity API](/docs/blockchain/Ethereum/dextrades/ethereum-liquidity-api) - [Ethereum slippage API](/docs/blockchain/Ethereum/dextrades/ethereum-slippage-api) --- ## Uniswap v4 Liquidity on Ethereum URL: https://docs.bitquery.io/docs/blockchain/Ethereum/dextrades/uniswap-v4-liquidity-api/ Uniswap v4 Liquidity on Ethereum: get Ethereum DEX swaps, prices, and OHLC with Bitquery GraphQL queries and live streams. # Uniswap v4 Liquidity on Ethereum Uniswap **v4** changes **where** liquidity lives and **how** you identify a “pool.” This page explains that mechanism, contrasts it with earlier versions, and shows how **Bitquery** lets you read **one concrete pool’s** liquidity for a token pair using **`PoolId`**—something that is awkward or misleading if you only filter by **token addresses** or a **single factory contract**. ## How Uniswap v4 liquidity works ### Singleton architecture In **Uniswap v2** and **v3**, each pool is typically backed by its **own pair or pool contract**. You point explorers, indexers, and APIs at that **contract address** to read reserves, positions, and events. In **Uniswap v4**, almost all pool state lives inside one **`PoolManager`** contract (`0x000000000004444c5dc75cB358380D2e3dE08A90` on Ethereum mainnet). The protocol does **not** deploy a new contract per pair. Instead, the manager holds a **key/value style store**: each logical pool is a row of state keyed by a **`PoolId`**. **`PoolId`** is a deterministic identifier (a `bytes32`-style hash) derived from the pool’s **static configuration**, including: - The two **currencies** (token addresses, with ordering rules per the protocol) - **Fee tier** (and fee control / dynamic-fee hooks where applicable) - **Tick spacing** - **Hooks** contract address (v4’s major extension point: custom logic invoked at pool lifecycle points) Any change to those parameters defines a **different** pool, hence a **different `PoolId`**, even when the **two token symbols** look like “the same pair” to a user. ### Liquidity and price state Liquidity is still conceptually **concentrated around ticks** (like v3), but the **implementation is internal to the singleton**: liquidity additions/removals and swaps update the pool’s slot inside `PoolManager` rather than updating storage on a dedicated pool contract. **Hooks** can observe or alter behavior around swaps, liquidity changes, and more, thus two pools with the **same two tokens and fee** can still differ if **hooks** differ, producing **two different `PoolId`s** and **two separate liquidity curves**. --- ## How v4 differs from v2 and v3 (summary) | Topic | Uniswap v2 | Uniswap v3 | Uniswap v4 | | ----- | ---------- | ----------- | ----------- | | **Pool identity** | Pair **contract address** | Pool **contract address** | **`PoolId`** (virtual); shared **`PoolManager`** | | **Deployment** | New **pair contract** per pool | New **pool contract** per pool | **No** per-pool contract; pools are **state keys** | | **“Where is the liquidity?”** | In the pair contract’s balances | In the pool contract + NFT positions manager | In **`PoolManager`** keyed by **`PoolId`** | | **Same two tokens, multiple pools** | Uncommon (same fee, one pool) | Common (multiple fee tiers per pair) | **Very common** (fee, tick spacing, **hooks** → many **`PoolId`s**) | | **Extensions** | Limited | Limited | **Hooks** (custom pool logic) | --- ## Why “pair only” filtering is insufficient on v4 On-chain, **every** v4 pool shares the same **`PoolManager`** address. If your pipeline only filters by: - **`PoolManager`** as the “DEX contract,” or - **Two token addresses** as “the pair,” you **merge** liquidity and events across **all** configurations (fees, tick spacings, hooks) that share those tokens. That is **not** the liquidity of a single market you care about for slippage, depth, or LP behavior. To talk about **one** market you need the same identifier the protocol uses: **`PoolId`**. --- ## How Bitquery helps: `PoolId` on indexed liquidity events Bitquery indexes **DEX pool liquidity** events into **`DEXPoolEvents`** (see [EVM DEXPools](/docs/cubes/evm-dexpool/)). For Uniswap v4, each event carries: - **`PoolEvent.Pool.PoolId`** — unique logical pool (what you need on v4) - **`PoolEvent.Pool.SmartContract`** — the manager (or protocol-facing) address; **repeats** across v4 pools - **`PoolEvent.Dex.ProtocolName`** — e.g. **`uniswap_v4`** for filtering the protocol - **`PoolEvent.Liquidity`** — reserves / amounts and related fields as emitted after the event That means you can: 1. **Subscribe** to liquidity updates **across all Uniswap v4 pools**, and read **`PoolId`** on every row. 2. **Filter to exactly one pool** with **`PoolId: { is: "0x..." }`** together with **`ProtocolName: uniswap_v4`**, and get **that pool’s** reserves and prices—not an aggregate of every WETH/USDC v4 configuration. Without a **`PoolId`** dimension, **per-pool** v4 liquidity for a “pair” is **not** faithfully represented; Bitquery exposes **`PoolId`** so you can align with how Uniswap v4 actually partitions state. --- ## API examples Run these in the [Bitquery IDE](https://ide.bitquery.io). Examples use **`EVM(network: ethereum)`** for Ethereum mainnet, aligned with the [Ethereum Liquidity API](/docs/blockchain/Ethereum/dextrades/ethereum-liquidity-api/) Uniswap v4 patterns. ### Latest liquidity snapshot for a V4 Pool Returns the most recent liquidity event for a **single** Uniswap v4 pool. Replace **`$poolId`** with your target **`PoolId`** (from trades UI, subgraph, or a prior `DEXTradeByTokens` / `DEXPoolEvents` discovery query). [Run in IDE](https://ide.bitquery.io/latest-liquidity-for-an-individual-pool-on-uniswap-v4) (paste and set variables). ```graphql query LatestUniswapV4PoolLiquidity($poolId: String!) { EVM(network: eth) { DEXPoolEvents( limit: { count: 1 } orderBy: { descending: Block_Time } where: { PoolEvent: { Dex: { ProtocolName: { is: "uniswap_v4" } } Pool: { PoolId: { is: $poolId } } } } ) { Block { Time Number } PoolEvent { AtoBPrice BtoAPrice Dex { SmartContract ProtocolName } Liquidity { AmountCurrencyA AmountCurrencyB AmountCurrencyAInUSD AmountCurrencyBInUSD } Pool { PoolId SmartContract CurrencyA { Symbol SmartContract Name } CurrencyB { Symbol SmartContract Name } } } Transaction { Hash } } } } ``` **Variables** ```json { "poolId": "0x2a5bf4f7f9f6044f854ae1170113504a023dbcb347f25a1809bab471f07a7dba" } ``` Use a **`PoolId`** you obtain for your network (the value above is illustrative). ### Real-time Liquidity Streaming Streams **every** liquidity-changing event Bitquery indexes for **`uniswap_v4`**, including **`PoolId`** so you can route updates per pool in your app or Kafka consumer. [Run in IDE](https://ide.bitquery.io/Latest-Liquidity-Changes-of-Pools-in-a-Specific-DEX-Protocol---Uniswap-V4_6#). ```graphql subscription UniswapV4LiquidityStream { EVM(network: eth) { DEXPoolEvents( where: { PoolEvent: { Dex: { ProtocolName: { is: "uniswap_v4" } } } } ) { Block { Time Number } PoolEvent { AtoBPrice BtoAPrice Dex { SmartContract ProtocolName } Liquidity { AmountCurrencyA AmountCurrencyB } Pool { PoolId SmartContract CurrencyA { Symbol SmartContract } CurrencyB { Symbol SmartContract } } } Transaction { Hash } } } } ``` ### Recent liquidity Events for a V4 Pool Useful for dashboards: last **N** updates for **one** pool only (again **`PoolId`**, not just token addresses). [Run in IDE](https://ide.bitquery.io/recent-pool-updates-for-a-given-pool) ```graphql query RecentUniswapV4PoolLiquidity($poolId: String!) { EVM(network: eth) { DEXPoolEvents( limit: { count: 50 } orderBy: { descending: Block_Time } where: { PoolEvent: { Dex: { ProtocolName: { is: "uniswap_v4" } } Pool: { PoolId: { is: $poolId } } } Block: { Time: { since_relative: { days_ago: 7 } } } } ) { Block { Time } PoolEvent { AtoBPrice BtoAPrice Liquidity { AmountCurrencyA AmountCurrencyB } Pool { PoolId CurrencyA { Symbol SmartContract } CurrencyB { Symbol SmartContract } } } Transaction { Hash } } } } ``` ### Latest Liquidity for All Uniswap V4 Pools for a Currency Pair This API endpoint provides latest liquidity event for every Uniswap V4 pool for a given currency pair. This info includes the **Price of currencies in terms of other**, **Price of currencies in USD**, **Currency Details** and `PoolIDs`. [Run in IDE](https://ide.bitquery.io/latest-liquidity-for-a-currency-pair-across-all-v4-pools_1) ```graphql { EVM { DEXPoolEvents( limitBy: {by: PoolEvent_Pool_PoolId count: 1} orderBy: {descending: Block_Time} where: { PoolEvent: { Dex: {ProtocolName: {is: "uniswap_v4"}}, Pool: { CurrencyA: {SmartContract: {is: "0x0bb217e40f8a5cb79adf04e1aab60e5abd0dfc1e"}}, CurrencyB: {SmartContract: {is: "0xdac17f958d2ee523a2206206994597c13d831ec7"}} } } } ) { Block { Time } PoolEvent { AtoBPrice BtoAPrice AtoBPriceInUSD BtoAPriceInUSD Liquidity { AmountCurrencyA AmountCurrencyB AmountCurrencyAInUSD AmountCurrencyBInUSD } Pool { CurrencyA { Decimals Name Symbol SmartContract } CurrencyB { Decimals Name SmartContract Symbol } PoolId } } } } } ``` ### Monitor Liquidity Events for a Currency Pair on Uniswap V4 If looking to monitor a currency pair across all virtual pools within Uniswap V4, then this subscription works the best. [Run in IDE](https://ide.bitquery.io/currency-pair-liquidity-events-stream) ```graphql subscription { EVM { DEXPoolEvents( where: { PoolEvent: { Dex: {ProtocolName: {is: "uniswap_v4"}}, Pool: { CurrencyA: {SmartContract: {is: "0x0bb217e40f8a5cb79adf04e1aab60e5abd0dfc1e"}}, CurrencyB: {SmartContract: {is: "0xdac17f958d2ee523a2206206994597c13d831ec7"}} } } } ) { Block { Time } PoolEvent { AtoBPrice BtoAPrice AtoBPriceInUSD BtoAPriceInUSD Liquidity { AmountCurrencyA AmountCurrencyB AmountCurrencyAInUSD AmountCurrencyBInUSD } Pool { CurrencyA { Decimals Name Symbol SmartContract } CurrencyB { Decimals Name SmartContract Symbol } PoolId } } } } } ``` ### Latest Slippage Bucket and Price for a Transaction on Uniswap V4 Virtual Pool This API endpoint returns the latest slippage basis points, price of currencies (in terms of other and USD) along with **MaxAmountIn** and **MaxAMountOut** for both the currecies of the virtual pool filtered out by `PoolId` for the latest transaction/swap. [Run in IDE](https://ide.bitquery.io/latest-transaction-slippage-for-virtual-uniswap-v4-pool) ```graphql query MyQuery { EVM { DEXPoolEvents( where: {PoolEvent: {Dex: {ProtocolName: {is: "uniswap_v4"}}, Pool: {PoolId: {is: "0x2a5bf4f7f9f6044f854ae1170113504a023dbcb347f25a1809bab471f07a7dba"}}}} orderBy: {descending: Block_Time} ) { Transaction { Hash } joinDEXPoolSlippages(Transaction_Hash: Transaction_Hash) { Price { AtoB { MaxAmountIn MaxAmountInInUSD MinAmountOut MinAmountOutInUSD Price PriceInUSD } SlippageBasisPoints Pool { CurrencyA { Decimals SmartContract Name Symbol } CurrencyB { Name SmartContract Symbol Decimals } } BtoA { MaxAmountIn MaxAmountInInUSD MinAmountOut MinAmountOutInUSD Price PriceInUSD } } } } } } ``` --- ## Related documentation - [Uniswap v4 DEX Trades API](/docs/blockchain/Ethereum/dextrades/uniswap-v4-api/) — trades, `PoolId` filters, pair stats - [Ethereum Liquidity API](/docs/blockchain/Ethereum/dextrades/ethereum-liquidity-api/) — more `DEXPoolEvents` patterns, including Uniswap v4 subscription examples - [DEXPools cube](/docs/cubes/evm-dexpool/) — field semantics and event types --- ## debug_traceCall with Bitquery: Trace Internal Calls Without a Node URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/debug_traceCall/ Read decoded internal calls of executed Ethereum transactions with the Bitquery Calls cube instead of tracing them yourself, with limits stated plainly. # debug_traceCall with Bitquery: Trace Internal Calls Without a Node `debug_traceCall` is the JSON-RPC method that executes a call against a block's state and returns the trace: every internal call with its sender, target, input, output, gas and value. It needs an archive node with the debug API enabled, and it traces one call you construct. The Bitquery `Calls` cube holds the same trace fields for every call that ran on chain, top-level and internal, already decoded, so you filter instead of simulating: all calls into a contract, calls from one sender, calls that carried ETH, one method by name. It does not simulate a hypothetical call; it returns what executed. Every query runs in the [IDE](https://ide.bitquery.io), on Ethereum and, by changing `network`, on the other EVM chains. Queries on the `archive` or `combined` dataset need an archive add-on; the free trial is real-time only. ## Calls into a contract Every call whose target is the USDC contract in the last ten minutes, with the fields a trace returns. `Depth` separates top-level calls (0) from internal ones, `Success` flags reverts, and `Signature.Name` is the decoded method. The time bound keeps the scan small; widen it, or add `dataset: archive` for history. ```graphql { EVM(network: eth) { Calls( where: { Call: { To: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } } Block: { Time: { since_relative: { minutes_ago: 10 } } } } limit: { count: 10 } orderBy: { descending: Block_Time } ) { ChainId Block { Time } Call { From To Input Output Gas GasUsed Value Create Success Depth Signature { Name } } Transaction { Hash } } } } ``` `Gas` is the gas available to the call and `GasUsed` what it consumed, both in gas units; `Value` is in wei. The saved IDE version of this query is [here](https://ide.bitquery.io/debug_traceCall). ## Calls from a known sender Add `From` to the filter. This ranks the addresses that called USDC most in the last hour, which is the quickest way to find an active sender to trace; then put that address in `From: { is: "..." }` with the selection above. Saved variant [here](https://ide.bitquery.io/debug_traceCall_1). ```graphql { EVM(network: eth) { Calls( where: { Call: { To: { is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } } Block: { Time: { since_relative: { hours_ago: 1 } } } } limit: { count: 3 } orderBy: { descendingByField: "n" } ) { Call { From } n: count } } } ``` ## Calls that carried value `Value` takes `eq`, `ne`, `gt`, `ge`, `lt` and `le`, where the RPC method only matches a fixed value. Calls into WETH with value above zero are deposits, most of them internal calls made by routers on a user's behalf. Saved variant [here](https://ide.bitquery.io/debug_traceCall_2). ```graphql { EVM(network: eth) { Calls( where: { Call: { To: { is: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" }, Value: { gt: "0" } } Block: { Time: { since_relative: { hours_ago: 1 } } } } limit: { count: 5 } orderBy: { descending: Block_Time } ) { Block { Time } Call { From To Value Depth Signature { Name } } Transaction { Hash } } } } ``` ## What the RPC method has that this does not, and the reverse `debug_traceCall` simulates a call you have not sent, against any block state. Bitquery only returns calls that executed. In return you get filters across every transaction at once, decoded method names and arguments, `dataset: archive` for history, and a subscription form that streams new calls into a contract as they happen. For a full transaction's trace, filter `Transaction: { Hash: { is: "..." } }` and read the calls in `Call.Index` order. ## Related pages - [EVM calls schema](/docs/schema/evm/calls) - [Robinhood Calls and traces API](/docs/blockchain/robinhood/robinhood-calls-api) - [eth_blockNumber with Bitquery](/docs/blockchain/Ethereum/ethers-library/eth_blockNumber) - [Ethereum API hub](/docs/blockchain/Ethereum/) --- ## debug_traceTransaction URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/debug_traceTransaction/ debug_traceTransaction on Ethereum: reproduce a transaction trace with a Bitquery GraphQL query and see the response it returns, as an RPC method alternative. # debug_traceTransaction debug_traceTransaction is a JSON RPC method that returns tracing results for the specified transaction. In this section, we are looking for a way to build an alternative for the same using Bitquery API. ## Debug Trace Transaction To trace a transaction using the debug_traceTransaction we need the `transaction hash`. We are using [this](https://ide.bitquery.io/debug_traceTransaction) API given below for tracing the transaction, with transaction hash as `0x4fe59dcf4f834f17acdcd0f244538c119523009ce47817ccd56423404ba34ffa`. ``` graphql query MyQuery { EVM { Calls( where: { Transaction: { Hash: { is: "0x4fe59dcf4f834f17acdcd0f244538c119523009ce47817ccd56423404ba34ffa" } } } ) { Call { From Gas GasUsed Input Output To Value InternalCalls Error Create } } } } ``` ## Response Recieved The response from running the above API is given below, and returns. - `Create` - (boolean) If the transaction is a smart contract creation or not. - `From` - The address from which the transaction originated. - `To` - The address to which the transaction is sent. - `Gas` - Gas provided for the transaction in `WEI`. - `GasUsed` - Gas used in the transaction in `WEI`. - `Input` - Call Data. - `Output` - Data Returned. - `Value` - Amount of value transfer. - `Error` - Error string (if any), otherwise an empty string. - `InternalCalls` - Number of sub-calls. ``` json { "EVM": { "Calls": [ { "Call": { "Create": false, "Error": "", "From": "0xd2241065700f763d0390725d00bfd3fbef0b525e", "Gas": "120748", "GasUsed": "87170", "Input": "0x42842e0e000000000000000000000000d2241065700f763d0390725d00bfd3fbef0b525e000000000000000000000000ad6df549cc5c3427fe2c54207620e3555c4350aa000000000000000000000000000000000000000000000000000000000000057e", "InternalCalls": 0, "Output": "0x", "To": "0xbb3f21dd9b16741e9822392f753d07da4c6b6cd6", "Value": "0.000000000000000000" } } ] } } ``` --- ## eth_getBlockReceipts URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/eth_getBlockReceipts/ eth_getBlockReceipts equivalent on Ethereum: fetch all transaction receipts, logs and gas used for a block through a GraphQL query instead of RPC. # eth_getBlockReceipts In this section we will build an API that serves as an alternative to the eth_getBlockReceipts JSON RPC method that takes `Block Number` as an input and returns all transaction receipts for the given block. ## Get Block Receipts [This](https://ide.bitquery.io/eth_getBlockReceipt) query serves as an alternative to the eth_getBlockReceipts method with `Block Number` as `20525804`. ``` graphql query MyQuery { EVM { Transactions(where: {Block: {Number: {eq: "20525804"}}}) { Block { Hash Number } Transaction { From To Hash Index } Receipt { ContractAddress CumulativeGasUsed GasUsed Status Type } } } } ``` The above API returns the following output. ``` json { "EVM": { "Transactions": [ { "Block": { "Hash": "0x399bf82bde7d84d36f9deb7e7ddb5f2b11b6d454960f3a6243ec51d50ccd4300", "Number": "20525804" }, "Receipt": { "ContractAddress": "0x0000000000000000000000000000000000000000", "CumulativeGasUsed": "4227373", "GasUsed": "27329", "Status": "1", "Type": 2 }, "Transaction": { "From": "0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5", "Gas": "27329", "Hash": "0xcc9ce436a02e8a4b44546affebe036fdd54b70c27ea3c2df18c0a1ed78ec9fbe", "Index": "23", "To": "0x1876207dbfd106372d289d06e89cb75a4ff40231" } }, { "Block": { "Hash": "0x399bf82bde7d84d36f9deb7e7ddb5f2b11b6d454960f3a6243ec51d50ccd4300", "Number": "20525804" }, "Receipt": { "ContractAddress": "0x0000000000000000000000000000000000000000", "CumulativeGasUsed": "4273342", "GasUsed": "45969", "Status": "0", "Type": 2 }, "Transaction": { "From": "0xffdfafbe24182f0cb5da28905aeb4109ef97d536", "Gas": "2000000", "Hash": "0xe255e765b5acec3f3c07d0294454e75f25f0c939d8a983f0832169aefaaf481f", "Index": "24", "To": "0xc7e9f886639beeba04c135abeb96365c01969552" } }, ] } } ``` --- ## eth_getTransactionByHash URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/eth_getTransactionByHash/ Ethereum transaction lookup by hash, the eth_getTransactionByHash equivalent: get transaction hashes and full transaction details with GraphQL query examples. # eth_getTransactionByHash In this section we will discuss how we can build eth_getTransactionByHash alternatives using Bitquery APIs. ## Get Transaction Hash We will use [this](https://ide.bitquery.io/Get-Transaction-Hash) stream to get the latest transactions hash. We will use this transaction hash as an input for the eth_getTransactionByHash alternative API. ``` graphql subscription { EVM { Transactions { Transaction { Hash } } } } ``` ## Get Transaction Details by Hash [This](https://ide.bitquery.io/eth_getTransactionByHash_1) API serves as an alternative to the eth_getTransactionByHash JSON RPC method with `Hash` as `0xcc9ce436a02e8a4b44546affebe036fdd54b70c27ea3c2df18c0a1ed78ec9fbe`. ``` graphql query getTransactionByHash { EVM { Transactions( where: {Transaction: {Hash: {is: "0xcc9ce436a02e8a4b44546affebe036fdd54b70c27ea3c2df18c0a1ed78ec9fbe"}}} ) { Block { Time Number } ChainId Signature { R S V } Transaction { From Gas GasPrice Hash Index Nonce Cost Data To Value AccessList { Address StorageKeys } GasFeeCap Type } TransactionStatus { Success } } } } ``` After running the above query this is the expected result. ``` json { "EVM": { "Transactions": [ { "Block": { "Number": "20525804", "Time": "2024-08-14T08:54:11Z" }, "ChainId": "1", "Signature": { "R": "15733655909487727252053616094955044058698623526211212024614602844347766842611", "S": "31797148001645269693712272496207792779118835901043019296634774876795585651855", "V": "0" }, "Transaction": { "AccessList": [], "Cost": "0.000603129239285980", "Data": "0x", "From": "0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5", "Gas": "27329", "GasFeeCap": "3474089451", "GasPrice": "0.000000003474089451", "Hash": "0xcc9ce436a02e8a4b44546affebe036fdd54b70c27ea3c2df18c0a1ed78ec9fbe", "Index": "23", "Nonce": "1278621", "To": "0x1876207dbfd106372d289d06e89cb75a4ff40231", "Type": 2, "Value": "0.000508185848679601" }, "TransactionStatus": { "Success": true } } ] } } ``` --- ## eth_getTransactionReceipt URL: https://docs.bitquery.io/docs/blockchain/Ethereum/ethers-library/eth_getTransactionReceipt/ eth_getTransactionReceipt equivalent on Ethereum: get a transaction's receipt, status, gas used and logs via a GraphQL query, with a sample response. # eth_getTransactionReceipt In this section, we will build an alternative to the eth_getTransactionReceipt JSON RPC method using the Bitquery APIs. The method is used to provide the receipt of a transaction given `transaction hash`. Note that the receipt is not available for pending transactions. ## Get Transaction Receipt We can get the receipt of a transaction using the transaction hash, `0x4fe59dcf4f834f17acdcd0f244538c119523009ce47817ccd56423404ba34ffa` for this example, using [this](https://ide.bitquery.io/eth_getTransactionReceipt_1) API given below. ``` graphql { EVM { Transactions( where: { Transaction: { Hash: { is: "0x4fe59dcf4f834f17acdcd0f244538c119523009ce47817ccd56423404ba34ffa" } } } ) { Block { Hash Number } Transaction { From GasPrice Hash Index To } Receipt { ContractAddress CumulativeGasUsed GasUsed Status Type Bloom } } } } ``` ## Response Received The response of the above API is given below. ``` json { "EVM": { "Transactions": [ { "Block": { "Hash": "0x8b0d94963d1cb307ff0b83a60bb43bb53bf471a6644161eb882169c782ec5e5c", "Number": "20540273" }, "Receipt": { "Bloom": "0x0000000000000000000000000000000000000000000000000000000000000000000002000000040000000000000000000000000000000000000000000000000000020000000000000000000a000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000010000000000000000000000040000000000000000000008001000000000000000000000000000000000000000000000000000000000000000000002000000000000000002000000002000000000004000000000000000000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000", "ContractAddress": "0x0000000000000000000000000000000000000000", "CumulativeGasUsed": "4656412", "GasUsed": "99510", "Status": "1", "Type": 0 }, "Transaction": { "From": "0xd2241065700f763d0390725d00bfd3fbef0b525e", "GasPrice": "0.000000005000000000", "Hash": "0x4fe59dcf4f834f17acdcd0f244538c119523009ce47817ccd56423404ba34ffa", "Index": "24", "To": "0xbb3f21dd9b16741e9822392f753d07da4c6b6cd6" } } ] } } ``` Now, you may note that unlike the JSON RPC method, this API does'nt return any `log` object. However, if that is something you might need then checkout the following page for [eth_getLogs](/docs/blockchain/Ethereum/ethers-library/eth_getLogs/).