TikTok Shop Velocity Sniper

An Apify Actor that monitors TikTok Shop product listings for sudden sales velocity spikes and fires real-time Telegram alerts. Uses pay-per-event billing — you only pay when a spike is detected.

How It Works

1. On each run, the actor fetches the current sold_count for every tracked product via the SociaVault API.
2. It compares the current count against the previously recorded snapshot (stored in Apify Key-Value Store between runs).
3. If the order delta or percentage growth exceeds your configured thresholds, it:
   • Charges a Velocity-Spike-Detected event (pay-per-event billing)

     • Pushes a record to the actor's dataset

       • Sends a Telegram alert with full spike details
       4. Updates the snapshot for the next run.

       Setup Guide

       1. Get a SociaVault API Key

       • Sign up at https://sociavault.com
       • Navigate to your account settings and copy your API key
       • Enter it in the sociaVaultApiKey input field (marked as secret)

       2. Create a Telegram Bot

       1. Open Telegram and message @BotFather
       2. Send /newbot and follow the prompts to create your bot
       3. Copy the bot token (looks like 123456789:ABCdef...)
       4. Enter it in the telegramBotToken input field (marked as secret)

       3. Get Your Telegram Chat ID

       For a personal chat:

       • Message your bot, then visit: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

         • Look for "chat":{"id":...} in the response

         For a channel:

         • Add your bot as an administrator to the channel
         • Use the channel username as the Chat ID (e.g. @myalertchannel)
         • Or forward a message from the channel to @userinfobot

         4. Configure the Actor Input

         Field	Description	Default
         productUrls	Array of TikTok Shop product URLs or IDs	Required
         sociaVaultApiKey	SociaVault API key (secret)	Required
         telegramBotToken	Telegram bot token (secret)	Required
         telegramChatId	Target Telegram chat/channel ID	Required
         velocityThresholdOrders	Absolute order delta to trigger alert	200
         velocityThresholdPercent	Percentage growth to trigger alert	300
         pollIntervalMinutes	Expected run interval (for context)	15

         5. Set Up the Scheduler

         The actor uses Apify's native Scheduler for recurring runs — there is no long-running loop inside the actor itself.

         1. Go to Schedules in the Apify Console
         2. Click Create new schedule
         3. Set the cron expression for every 15 minutes: */15 * * * *
         4. Link the schedule to this actor with your saved input
         5. Enable the schedule

         Set pollIntervalMinutes in the actor input to match your scheduler cadence.

         Billing

         This actor uses pay-per-event pricing:

         Event	Description	Price
         apify-actor-start	Charged once per run	$0.001
         Velocity-Spike-Detected	Charged per detected spike	$0.01

         You are only charged for spikes that are actually detected — no spike, no charge (beyond the base run cost).

         Thresholds Explained

         The alert trigger uses OR logic:

         • Alert fires if orderDelta >= velocityThresholdOrders OR percentGrowth >= velocityThresholdPercent

         Examples:

         • Product goes from 1,000 to 1,250 sales (+250 orders, +25%) with defaults (200 orders / 300%): fires on absolute threshold
         • Product goes from 10 to 50 sales (+40 orders, +400%) with defaults: fires on percent threshold
         • Brand-new product with no prior baseline: records initial snapshot only, no alert (avoids false positives)

         Output Dataset Fields

         Each spike record contains:

         {
           "productId": "1234567890",
             "title": "Product Name",
               "shopName": "Shop Name",
                 "price": "$19.99",
                   "soldCountBefore": 1000,
                     "soldCountAfter": 1350,
                       "orderDelta": 350,
                         "percentGrowth": 35.0,
                           "triggerReason": "Absolute order threshold exceeded",
                             "detectedAt": "2026-06-19T14:30:00.000Z",
                               "pollIntervalMinutes": 15
                               }
                               ```
         
                               ## Local Development
         
                               ```bash
                               # Clone and install
                               npm install
         
                               # Create .env or set environment variables
                               # APIFY_TOKEN=your_apify_token
         
                               # Run locally
                               npm start
                               ```
         
                               ## Architecture Notes
         
                               - **Concurrency**: Max 5 concurrent SociaVault API calls (semaphore-controlled)
                               - **Retry logic**: 3 attempts with exponential backoff on API failures
                               - **Error isolation**: A single product failure doesn't abort the full run
                               - **State persistence**: Snapshots stored in Apify Key-Value Store (no external DB needed)
                               - **Scheduler-driven**: Uses Apify's native Scheduler — no `setInterval` loops