# TikTok Shop Velocity Sniper (`signalfoundry/tiktok-shop-velocity-sniper`) Actor

Detects TikTok Shop products going viral in real-time by tracking order velocity. Get Telegram alerts the moment a product surges before everyone else knows.

- **URL**: https://apify.com/signalfoundry/tiktok-shop-velocity-sniper.md
- **Developed by:** [Frank Kamu](https://apify.com/signalfoundry) (community)
- **Categories:** E-commerce
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $250.00 / 1,000 velocity spike detecteds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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](https://t.me/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:

         ````json
         {
           "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
         ````

# Actor input Schema

## `keywords` (type: `array`):

Keywords to search on TikTok Shop (e.g. 'lip gloss', 'phone case', 'wireless earbuds').

## `region` (type: `string`):

TikTok Shop region (US, GB, ID, MY, TH, PH, SG).

## `maxProductsPerKeyword` (type: `integer`):

How many products to track per keyword.

## `sociaVaultApiKey` (type: `string`):

Your SociaVault API key for TikTok Shop data.

## `telegramBotToken` (type: `string`):

Your Telegram bot token from @BotFather.

## `telegramChatId` (type: `string`):

Your Telegram chat ID where alerts will be sent.

## `velocityThresholdOrders` (type: `integer`):

Alert if order count increases by this many since last run.

## `velocityThresholdPercent` (type: `number`):

Alert if order count grows by this percentage since last run.

## `pollIntervalMinutes` (type: `integer`):

How often the actor runs via Apify Scheduler.

## `rainforestApiKey` (type: `string`):

Rainforest API key for Amazon competition checks

## Actor input object example

```json
{
  "keywords": [
    "trending",
    "lip gloss",
    "phone case"
  ],
  "region": "US",
  "maxProductsPerKeyword": 20,
  "velocityThresholdOrders": 200,
  "velocityThresholdPercent": 300,
  "pollIntervalMinutes": 15
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("signalfoundry/tiktok-shop-velocity-sniper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("signalfoundry/tiktok-shop-velocity-sniper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call signalfoundry/tiktok-shop-velocity-sniper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,signalfoundry/tiktok-shop-velocity-sniper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/CcYGUxjnyPzA2TDZJ/builds/za5zyXbhdVhtZoshN/openapi.json