When a rare CryptoPunk lists below its fair value, the window is minutes, sometimes seconds. PunkPredictor monitors the Ethereum mempool and the CryptoPunks marketplace simultaneously, computes a prediction-vs-ask comparison in real time, and delivers that signal to wherever you are: your Telegram bot, a Discord server, or a custom HTTP endpoint you control.

This post explains how each channel works, what the payload looks like, how filters and membership tiers affect delivery timing, and how to integrate webhooks into your own tooling.

How the alert engine works

Every listing alert begins from the same source: a Punk is listed for sale on the CryptoPunks marketplace. PunkPredictor detects this either from mempool activity before the transaction confirms, or via on-chain event indexing.

From there, the engine does four things before any delivery happens:

1. Deduplication. Each transaction hash is reserved atomically so the same listing never fires twice, even if both the mempool and on-chain paths race.
2. Prediction lookup. The current fair-value estimate for that Punk is fetched from the model — a trait-adjusted ML prediction updated every 30 minutes.
3. Per-recipient gating. Each subscriber's filter preferences are evaluated: mute, percentage threshold, undervalued-only, or trait whitelist. Recipients that do not match are skipped.
4. Tier-aware scheduling. Trader members receive immediate delivery. Collector members receive the same alert with a 90-minute delay, enforced by the listing timestamp in the database — not a countdown that restarts on app restart.

Telegram and webhooks share the same per-recipient filter and tier-delay logic. Discord is a broadcast feed, but all channels still use the same listing detection and prediction engine.

Telegram: mobile-first alerts with full filter control

The Telegram integration uses @PunkPredictorBot. Open the bot, send /start, paste your API key, and alerts begin flowing immediately. No server required.

Each alert message includes:

• Punk ID and thumbnail image
• Listing price in ETH
• Fair-value prediction (or a locked icon if your plan does not include prediction access)
• Percentage gap between listing and prediction (+undervalued / −overvalued)
• Direct link to the CryptoPunks marketplace listing
• Inline buttons: Explain prediction · Open Punk page

Filter options for Telegram

Manage filters from the membership modal or by messaging the bot directly:

• All listings — receive every alert, no threshold
• Within 10% / 20% / custom % — only when the gap between prediction and ask is within your chosen threshold
• Undervalued only — only when the prediction exceeds the ask (the model thinks it is mispriced below fair value)
• Mute — pause all alerts without disconnecting
• Trait filter — select one or more visual traits; only Punks with at least one matching trait will trigger an alert

Discord: community signal feed

The Discord integration broadcasts listings to a private server channel. Join via the link in your membership dashboard. Every listing that passes the global signal threshold is posted with Punk image, price, prediction, and percentage gap.

Discord is a shared feed rather than a per-user filtered stream — it is better suited for ambient awareness than for programmatic alerting. For precise per-user filtering, use Telegram or webhooks.

Webhooks: for builders and automated strategies

Webhooks deliver a signed JSON payload to an HTTPS endpoint you own. They are designed for bots, trading systems, portfolio dashboards, and any other tooling that needs structured data rather than a human-readable message.

Setting up a webhook

In your membership dashboard, open Webhook Alerts → Manage, paste your https:// endpoint URL, and click Add. The dashboard shows your signing secret once at creation time — save it, as it is not shown again. You can rotate it later from the same panel with a 7-day grace period so old and new secrets both validate during the transition.

Payload structure

Each delivery is a JSON POST with the following fields:

{
  "event": "punk.listed",
  "occurred_at": "2026-03-04T14:22:01Z",
  "listed_at": "2026-03-04T14:21:58Z",
  "delivery_id": "wd_48291",
  "punk_id": 3100,
  "listing_eth": 4500.0,
  "prediction_eth": 5820.4,
  "raw_prediction_eth": 5820.4,
  "prediction_masked": false,
  "diff_pct": 29.34,
  "abs_diff_pct": 29.34,
  "is_undervalued": true,
  "membership_type": "Trader",
  "filter": "undervalued",
  "trait_filter": [],
  "tx_hash": "0xabc123...",
  "source": "mempool",
  "links": {
    "punk": "https://cryptopunks.eth.limo/details/3100",
    "app": "https://punkpredictor.xyz/punk/3100"
  }
}

• delivery_id — unique per delivery, safe to use as an idempotency key
• prediction_eth — the value shown in the alert (null if masked by plan tier)
• raw_prediction_eth — same as above; null when masked, never bypasses tier policy
• diff_pct — positive means prediction is above listing (undervalued), negative means below
• source — mempool (pre-confirmation) or webhook (on-chain)

Verifying the signature

Each request includes an X-PP-Signature: sha256=<hex> header. Verify it by computing HMAC-SHA256 of the raw request body using your signing secret:

# Python example
import hmac, hashlib

def verify_signature(body_bytes: bytes, secret: str, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Always use a constant-time comparison (hmac.compare_digest) to prevent timing attacks. Reject requests where verification fails.

Retry behavior

If your endpoint returns a non-2xx status or times out (10-second limit), PunkPredictor retries with exponential backoff: 15 s → 30 s → 60 s → up to 8 attempts. In practice this is roughly a 32-minute retry window (excluding request/timeout overhead). After 8 failed attempts the delivery is marked terminal. Use delivery_id to deduplicate on retries — your endpoint may receive the same event more than once during transient failures.

Channel comparison

Trader vs. Collector timing

Both tiers receive the same alert content from the same prediction engine. The difference is when the alert is delivered relative to listed_at:

The 90-minute delay is enforced by the database timestamp of the listing, not a wall-clock countdown. If the server restarts mid-delay, Collector alerts still fire at the correct wall-clock time.

Frequently asked questions

Do I need one API key per channel?

No. Your single API key covers all three channels simultaneously. You can be connected to Telegram, Discord, and multiple webhook endpoints at the same time, all governed by your membership tier.

Can I have multiple webhook endpoints?

Yes. You can register multiple webhook URLs under the same API key. Each subscription has its own signing secret and can have independent filter preferences in a future update. Current delivery filters default to all listings.

What if I rotate my webhook secret?

Rotating a secret via the dashboard creates a new secret_current and moves the old one to secret_previous with a 7-day validity window. During those 7 days, both the old and new secrets validate successfully, so you can update your endpoint without a hard cutover.

Can I test a webhook without waiting for a real listing?

Yes. The webhook management panel has a Test button for each registered endpoint. Clicking it sends a synthetic punk.listed event with a real-looking payload so you can verify your signature verification and handler logic end-to-end.

Are alerts available for V1 CryptoPunks?

V1 tracking is available through the V1 experience at v1.punkpredictor.xyz. The Telegram and Discord channels currently cover V2 (the canonical CryptoPunks contract).