A Twitter monitoring tool for developers: keyword and account alerts by webhook.

What can you monitor?

Keyword queries use X search syntax and can be up to 512 characters, so from:, OR, hashtags and cashtags all work. You can buy 1 to 168 hours per purchase and keep up to 720 hours (30 days) prepaid ahead.

Which events does it send?

By default a monitor sends every event that applies to it. You can pass eventTypes to narrow it, for example to only tweet.new. The lifecycle event means silence is never ambiguous: either nothing happened, or you were told the monitor ended.

How much does Twitter monitoring cost?

Polling and webhook delivery are free. Hours are prepaid and aren't refunded if you delete early. You can pay with USDC via x402 on Base or MPP on Tempo, or from a card-funded balance. For comparison, polling a search yourself on any paid API means paying for every read, and an always-on stream means keeping a connection alive.

How do I set up keyword alerts?

# 1) create a keyword monitor for 24 prepaid hours
#    first request returns 402 with the price ($0.606); the wallet pays and retries
npx agentcash fetch https://twitr.sh/api/tools/x_monitor -m POST \
  -H 'Idempotency-Key: acme-alerts-001' \
  -b '{"action":"create","query":"acme OR @acmehq","eventTypes":["tweet.new","tweet.quote"],"hours":24}'
# -> { monitor: { monitor_id: "mn_...", expires_at, ... }, events_url }

# 2a) pull: poll the feed for free (wallet-signed)
npx agentcash fetch "https://twitr.sh/api/monitors/mn_.../events?after=<last id>"

# 2b) push: register a webhook once (free); the secret is returned once
npx agentcash fetch https://twitr.sh/api/webhooks -m POST \
  -b '{"url":"https://your-app.example/hooks","eventTypes":["tweet.new","tweet.quote"]}'

# 3) keep it running: extend before it expires
npx agentcash fetch https://twitr.sh/api/tools/x_monitor -m POST \
  -H 'Idempotency-Key: acme-alerts-002' \
  -b '{"action":"extend","monitorId":"mn_...","hours":48}'

The Idempotency-Key is required. If a retry reuses the same key, it returns the original monitor instead of charging twice. Prefer a card balance? Send Authorization: Bearer tw_live_… with plain curl instead. Every field is in the docs and on the x_monitor page.

How do I verify webhook deliveries?

Each delivery is a POST with X-Twitr-Signature, X-Twitr-Timestamp, X-Twitr-Delivery and X-Twitr-Event headers. The body has type, id, delivery_id, monitor_id, timestamps, source and data. Verify it before you trust it:

import crypto from "node:crypto";

// rawBody: the exact bytes you received, before JSON parsing
export function verifyTwitr(rawBody, headers, secret) {
  const ts = headers["x-twitr-timestamp"];          // unix time in ms
  const sig = headers["x-twitr-signature"] ?? "";    // "sha256=<hex>"
  if (Math.abs(Date.now() - Number(ts)) > 5 * 60_000) return false;
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  return sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Respond with a 2xx within 10 seconds and do slow work afterwards. Dedupe on delivery_id and id. Failed deliveries retry with backoff over about 36 minutes, up to 6 attempts. After 50 consecutive failures the webhook pauses, and a successful /test call turns it back on.

How does it compare with other ways to monitor Twitter?

What do people use Twitter monitors for?

Each row is one monitor, and you can run several side by side. Narrowing eventTypesdoesn't change the hourly price, but it keeps your webhook quiet and your agent focused on what matters. For a support inbox, send tweet.mention events to an agent that drafts replies, and approve them before anything is posted.

Can an AI agent run the monitor for me?

Yes. Install the skills with npx skills add lnvestor/twitr-skillsand say “Watch @competitor and tell me when they announce something.” The x-twitter-monitor skill creates the monitor, checks the feed and extends it when you ask. Point a webhook at Claude, OpenClaw, Hermes or your own endpoint to act the moment a post lands. With a connected account, the x-presence skill can draft replies for you to approve. See connect Claude to Twitter, /skills and /tools.

Comparing costs with the official API? See Twitter API vs twitr.sh, X API pricing and X API alternatives. If an account you're watching suddenly goes quiet, the free shadowban checker and X algorithm checker can tell you whether its reach dropped.

FAQ