PumpFetch Mechanics Documentation

Overview

This documentation provides a detailed explanation of how our system distinguishes between various types of transactions – such as Bundles, Sniper trades, Developer Buys/Sells, Sniper Clusters, and Sniper Bot activities – based solely on transaction characteristics and filtering logic.

Bundle Filtering

A Bundle is defined as a group of trades that occur in rapid succession and share the same slot (a blockchain-specific grouping). The filtering process follows these steps:

  1. Data Retrieval: Trades are fetched from an external API (e.g., via the get_all_trades(mint) function) for a given token (mint address).
  2. Threshold Filtering: Each trade’s SOL amount (converted from lamports) is evaluated. The filter_small_transactions(trades, threshold=Decimal("0.05")) function retains only those trades with a converted amount of at least 0.05 SOL, filtering out smaller, less significant trades.
  3. Grouping by Slot: The filtered trades are then grouped by their slot value using the group_by_slot(trades) function. Only groups containing at least two transactions are considered valid bundles.
  4. Aggregation: For each bundle, the system sums up the total SOL amounts for buy and sell transactions separately. The net result is calculated as:
    net_result = total_sell - total_buy
  5. Result Type: Based on the net result, the bundle is tagged as either a profit (if positive), a loss (if negative), or break-even. 
// Pseudocode Example for Bundle Detection:
filteredTrades = filter_small_transactions(allTrades, threshold=0.05);
bundles = group_by_slot(filteredTrades);

for each bundle in bundles {
    totalBuy = sum(buy trades);
    totalSell = sum(sell trades);
    netResult = totalSell - totalBuy;
    tag bundle as profit/loss/break-even based on netResult;
}

Developer Transactions

Developer transactions are identified by comparing the transaction’s traderPublicKey with the creator’s key stored in the tokens table. There are two primary types:

The functions process_dev_bought and process_dev_sold are responsible for scanning new updates (from the tokens_update table) and verifying whether the trader’s public key matches the token creator’s key. 

// Pseudocode Example for Developer Transaction Detection:
if (update.txType == 'buy') {
  if (token.traderPublicKey == update.traderPublicKey) {
    // Mark as Developer Buy
  }
} else if (update.txType == 'sell') {
  if (token.traderPublicKey == update.traderPublicKey) {
    // Mark as Developer Sell
  }
}

Sniper Transactions

Sniper transactions are characterized by their extremely short time window, typically occurring immediately after a token is created. The filtering logic includes:

  1. Recent Token Identification: The system scans the tokens table for tokens created within the last 10 minutes.
  2. Time Window Definition: For each new token, a 1-second window is established starting from the token’s created_at timestamp.
  3. Transaction Extraction: All trade updates (both buys and sells) that occur within this 1-second window are extracted from the tokens_update table.
  4. Sniper Flagging: If any transactions are found in this narrow window, they are inserted into the sniper table for further analysis. 
// Pseudocode Example for Sniper Detection:
for each token created in last 10 minutes {
    windowStart = token.created_at;
    windowEnd = windowStart + 1 seconds;
    sniperTrades = get trades from tokens_update between windowStart and windowEnd;
    if (sniperTrades exist) {
        insert sniperTrades into sniper table;
    }
}

Sniper Cluster Analysis

Sniper Clusters are groups of similar sniper transactions that indicate coordinated trading behavior. The process involves:

  1. Grouping by Slot and Time: Transactions in the sniper table are grouped by their slot and the processed_at time, which is rounded to the nearest minute.
  2. Cluster Signature Creation: For each group with at least two transactions, a unique cluster signature is generated. This signature is a sorted, comma-separated list of unique traderPublicKey values.
  3. Occurrence Validation: If the same cluster signature appears in at least two separate groups (different tokens or time slots), the group is confirmed as a sniper cluster.
  4. Database Insertion: Confirmed clusters are then recorded in the sniper_cluster table. 
// Pseudocode Example for Sniper Cluster Detection:
groups = group sniper trades by (slot, round(processed_at to minute));
for each group with >= 2 trades {
    signature = sorted unique traderPublicKeys (joined by commas);
    if (signature occurs in multiple groups) {
        insert cluster (signature, token, group time) into sniper_cluster;
    }
}

Sniper Bot Filtering

The Sniper Bot module is designed to detect automated or repetitive sniping behavior. It operates by:

  1. Collecting Wallet Data: New entries from the sniper_wallets table are collected. These entries originate from sniper transactions already flagged as potentially suspicious.
  2. Grouping by Wallet and Amount: The system groups these transactions by the traderPublicKey and the trade amount (solAmount). This grouping is based on the assumption that a genuine trader would not repeatedly execute transactions with the same amount in rapid succession.
  3. Threshold Evaluation: A configurable threshold (e.g., a minimum of 2 transactions per wallet for a given amount) is used to flag repetitive behavior.
  4. Data Enrichment: For every group that meets the threshold, additional token details (such as name and symbol) are fetched from the tokens table. The enriched data is then stored in the sniper_bot table. 
// Pseudocode Example for Sniper Bot Filtering:
groupedWallets = group new sniper_wallets entries by (traderPublicKey, solAmount);
for each group {
    if (group count >= threshold) {
        tokenDetails = fetch token info by mint;
        insert record into sniper_bot with wallet, solAmount, tokenDetails, and transaction type;
    }
}

Conclusion

The filtering logic of our system is based on a combination of transaction characteristics such as timing, value, and participant identity. By applying these specific criteria:

This multi-layered approach enables real‑time monitoring and differentiation of complex trading patterns, which is essential for market analysis and risk management.