Reading the Ethereum Mempool: The txpool Namespace and Pending Transactions

What the Ethereum Mempool Actually Is

When you send a transaction via eth_sendRawTransaction, the receiving node validates it and, if valid, places it into its local transaction pool (often called the mempool). This pool is not part of Ethereum consensus; it is a per-node cache of transactions that have been accepted but not yet mined. Each node maintains its own pool, so the contents differ from node to node. The pool is typically organized into two queues: pending (transactions with sequential nonces that are ready to be included in a block) and queued (transactions with nonce gaps or other conditions that prevent immediate inclusion).

The authoritative documentation for the txpool namespace is maintained by execution clients. For example, geth's txpool documentation and reth's txpool documentation describe the methods and their semantics. These are primary sources for the behavior described here. The key point is that the pool is local: two nodes can have different pending sets, and a transaction that is in one node's pool may be absent from another's.

This locality has profound implications for developers. If you rely on a hosted RPC provider, you are typically sharing infrastructure with many other users. Providers often disable the txpool namespace entirely because exposing it would leak information about their users' pending transactions and could be abused. As a result, you cannot assume that txpool_* methods are available on a hosted endpoint. Always check your provider's documentation or test the method directly.

• The mempool is node-local, not a global network component.
• Transactions enter the pool after validation and leave when mined or dropped.
• The pool is not part of consensus; it is an implementation detail.
• Hosted providers often disable txpool_* for privacy and resource reasons.

The txpool Namespace: Methods and Semantics

The txpool namespace provides three standard methods, defined in the Ethereum JSON-RPC specification and implemented by most clients: txpool_content, txpool_inspect, and txpool_status. Some clients add extensions, such as txpool_contentFrom (geth) or Besu-specific history methods, but these are not standardized and availability varies.

txpool_content returns the full transaction objects in the pool, grouped by address and nonce. The response has two top-level keys: pending and queued. Each maps an address to another map of nonce to transaction object. This is the most detailed view, but it can be large and is rarely exposed by providers.

txpool_inspect returns a lighter summary: for each address and nonce, it gives a string like value: gasPrice: gasLimit (e.g., 0x...: 1000000000000 wei + 50000 gas × 20000000000 wei). This is useful for quickly assessing the gas competition without fetching full transaction bodies.

txpool_status returns a simple object with pending and queued integer counts. This is the cheapest way to check if the pool is active and roughly how many transactions are waiting.

Some clients also provide txpool_contentFrom (geth) to filter by sender address, but again, this is not universal. Besu has its own txpool_besu* methods for transaction history, but they are Besu-specific. Always consult your client's documentation.

• txpool_content: full transaction objects, grouped by address and nonce.
• txpool_inspect: summary with gas price and value estimates.
• txpool_status: pending and queued counts.
• Extensions like txpool_contentFrom and txpool_besu* are client-specific.

Why Hosted Providers Usually Hide the Mempool

If you are using a hosted RPC service like OnFinality's API service, you may find that txpool_* methods return an error such as the method txpool_content does not exist/is not available. This is not a bug; it is a deliberate design choice. Providers operate shared infrastructure where many users send transactions through the same nodes. Exposing the local pool would reveal pending transactions from all users, creating privacy risks and enabling front-running. Additionally, serving full pool contents to every request would be resource-intensive.

The Ethereum node architecture itself does not require a global mempool. Each node independently validates and stores pending transactions. When you send a transaction to a provider, it is broadcast to the network, but the provider's node only keeps a local copy. Other nodes may have it in their pools, but you cannot query them directly unless you run your own node.

Therefore, if your integration depends on inspecting the mempool, you have two realistic paths: run your own full node (or a light node that supports the namespace) and query it directly, or use alternative methods that do not rely on the local pool. For most use cases, such as checking whether a transaction was accepted, eth_getTransactionByHash and receipt polling are more reliable because they query the canonical chain state, not a local cache.

• Hosted providers often disable txpool_* for privacy and resource reasons.
• The pool is local, so even if a provider exposed it, it would only show that provider's view.
• For transaction status, use eth_getTransactionByHash and receipt polling instead.
• Running your own node is the only way to get full txpool_* access.

Practical Use Cases and How to Approach Them

The search queries that lead to this article often come from developers trying to answer one of three questions: 'Is my transaction in the pool yet?', 'How congested is the network?', and 'Am I exposed to front-running?'. Let's address each.

Is my transaction in the pool? If you sent a transaction through a provider, the provider's node may have it in its local pool, but you usually cannot query that pool. Instead, use eth_getTransactionByHash with your transaction hash. If the transaction is still pending, this method returns the transaction object; if it has been mined, it returns the transaction with a block hash; if it is not found, it may have been dropped or never accepted. Polling for a receipt is the definitive way to know if it was mined.

Analyzing gas competition. If you run your own node, txpool_content or txpool_inspect can show you the pending transactions and their gas prices. This helps you estimate the minimum gas price needed to get included in the next block. However, remember that this is only your node's view; other nodes may have different transactions.

Front-running exposure. The public mempool is a known vector for front-running and sandwich attacks. If you are building an order-sensitive application (e.g., a DEX trade), you should assume that your transaction is visible to anyone who monitors the pool. Using a private transaction relay (such as Flashbots) is a separate channel that bypasses the public pool, but it is not an endorsement by OnFinality; it is a tool you can evaluate for your use case.

• For transaction status, use eth_getTransactionByHash and receipt polling.
• For gas analysis, txpool_inspect gives a quick summary.
• Public mempool transactions are visible to all; consider private relays for sensitive flows.
• Never assume a hosted provider exposes the pool.

Running txpool Methods Against Your Own Node

To use the txpool namespace, you need access to a node that exposes it. This is typically a self-managed full node with the namespace enabled. The following curl examples assume you have such an endpoint at http://localhost:8545. Replace the URL with your node's address.

First, check the pool status:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"txpool_status","params":[],"id":1}'

# Expected response (values vary)
{"jsonrpc":"2.0","id":1,"result":{"pending":"12","queued":"3"}}

Example: Inspecting Pending Transactions

To see a summary of pending transactions, use txpool_inspect. The output is a map of addresses to nonces, each with a string describing the transaction's value and gas. Here is an example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"txpool_inspect","params":[],"id":1}'

# Expected response (truncated)
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "pending": {
      "0x...address1": {
        "0": "0x...to: 1000000000000 wei + 50000 gas × 20000000000 wei"
      }
    },
    "queued": {}
  }
}

Example: Full Transaction Content

For the full transaction objects, use txpool_content. This returns the complete transaction data, including from, to, gas, gasPrice, value, and input. The response can be large, so be cautious when using it on a busy node.

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"txpool_content","params":[],"id":1}'

# Expected response (truncated)
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "pending": {
      "0x...address1": {
        "0": {
          "hash": "0x...",
          "nonce": "0x0",
          "from": "0x...",
          "to": "0x...",
          "value": "0xde0b6b3a7640000",
          "gas": "0x5208",
          "gasPrice": "0x4a817c800",
          "input": "0x"
        }
      }
    },
    "queued": {}
  }
}

Interpreting the Results: A Fill-in Table

When you run these methods, record your observations in a table like the one below. This helps you understand the state of your node's pool at a given time. The values are not benchmarks; they are snapshots that vary by network conditions and node configuration.

• Pending count: number of transactions ready for inclusion.
• Queued count: transactions with nonce gaps or other issues.
• Highest gas price in pending: indicates the current competitive threshold.
• Lowest gas price in pending: shows the minimum to get included soon.
• Number of unique senders: helps assess if the pool is dominated by a few addresses.

Troubleshooting: Why Is My Transaction Not in the Pool?

If you send a transaction and it does not appear in the pool (or you cannot see it), work through this checklist. The issue is often not the pool itself but the transaction's validity or your provider's behavior.

1. Check if the transaction was accepted. Use eth_getTransactionByHash. If it returns null, the transaction is not in the node's pool and may have been rejected. If it returns a transaction object, it is either pending or mined.

2. Check for nonce errors. A common reason for rejection is a nonce that is too low (already used) or too high (gap). Use eth_getTransactionCount with the pending block parameter to see the next expected nonce for your address. See our guide on EVM nonce management and eth_getTransactionCount for details.

3. Check gas price. If your gas price is too low, the transaction may be stuck in the pool or dropped by nodes that prune low-fee transactions. Geth, for example, has a default price limit and will drop transactions below it. The exact behavior is documented in the client's source.

4. Check pool limits. Geth caps the number of queued transactions per account (default is 64) and the total number of queued transactions (default 1024). If you exceed these, your transaction may be rejected. These are documented defaults; check your client's documentation for the current values.

5. Consider provider behavior. If you are using a hosted provider, they may not broadcast your transaction to the network immediately, or they may have their own validation rules. Always check the provider's documentation for any restrictions.

• Use eth_getTransactionByHash to confirm acceptance.
• Verify your nonce with eth_getTransactionCount.
• Ensure your gas price is above the node's minimum.
• Be aware of per-account and total pool limits.
• Hosted providers may have additional restrictions.

Limitations, Privacy, and Security Considerations

The public mempool is a double-edged sword. On one hand, it provides transparency and allows anyone to see pending transactions. On the other hand, it exposes your intentions before they are finalized. If you are trading large amounts or executing arbitrage, your transaction can be front-run by bots that monitor the pool. This is a well-known issue in DeFi.

To mitigate this, some developers use private transaction relays that send transactions directly to miners or validators, bypassing the public pool. Flashbots is one such service, but there are others. OnFinality does not endorse any specific service; you should evaluate the trade-offs yourself.

Another limitation is that the mempool is not a reliable source of truth. Because it is node-local, you cannot know the global state of pending transactions. A transaction might be in one node's pool but not another's, and it might be mined before you even see it. Therefore, do not build critical logic on the assumption that the pool reflects the entire network.

Finally, be aware that some nodes may not implement the txpool namespace at all, or may restrict it to local connections for security. Always test the method on your target endpoint before relying on it.

• Public mempool transactions are visible to all; sensitive flows should consider private relays.
• The pool is node-local, so it is not a global view.
• Some nodes disable the namespace for security.
• Always test method availability before building on it.

Next Steps and Further Reading

Understanding the mempool is just one piece of Ethereum RPC mastery. To build robust applications, you should also understand how to choose the right node for your needs. Our Choosing an Ethereum RPC node (RPC Assistant) guide explains the differences between full, archive, and light nodes, and how they affect your access to methods like txpool_*.

If you are dealing with transaction lifecycle issues, review our guides on Ethereum RPC timeouts and retries and Ethereum WebSocket disconnect handling. These are common pain points when sending transactions and monitoring their status.

For a broader perspective on Ethereum network interactions, see the OnFinality Learn hub and the Ethereum network page. If you are evaluating RPC providers, our RPC pricing page can help you understand cost structures, and the API service documentation describes what OnFinality offers.

Finally, if you are monitoring your own node, our guide on Monitoring RPC endpoints and node health provides practical tips for keeping your infrastructure reliable.

• Learn about node types and their capabilities.
• Understand timeout and WebSocket handling for robust apps.
• Explore the OnFinality Learn hub for more guides.
• Review pricing and API service details if you are considering a provider.