three kinds of events: confluence (several top traders bought the same coin recently), big_trade (one tracked trader bought or sold a large amount) and thesis (a tracked trader posted a thesis). the thresholds are yours.
by polling (no key)
curl -s 'https://copy.top/v1/alerts?min_top_traders=3'
keep the cursor the answer returns and pass it back as since on the next call. once a minute is enough. without since, you get the last 15 minutes.
by webhook (free key)
create_alert_webhook registers an https address; copy.top checks for new events once a minute and POSTs them to it. up to 3 webhooks per key. the signing secret is returned once.
POST https://your-server.example/copytop
content-type: application/json
x-copytop-signature: sha256=<hex hmac-sha256(secret, raw body)>
x-copytop-webhook-id: 42
{ "type": "copytop.alerts", "webhook_id": 42, "sent_at": "2026-11-22T20:00:00.000Z", "events": [ ... ] }
check the signature on the raw body before you trust it, and answer 2xx within 5 seconds. a webhook that keeps failing is turned off; list_alert_webhooks shows its last error.
copy.top