1. Prerequisites
This tool requires a Twitter/X Developer account with a Bearer Token. To get one:
- Go to developer.twitter.com and sign in with your Twitter/X account
- Create a project, then create an app inside the project
- Copy the Bearer Token from the app's Keys and Tokens tab
- Enter it in the Config tab Bearer Token field of this tool
The Bearer Token is read-only — it cannot post tweets, access DMs, or make any writes to your account. It is safe to use here.
Which Tier Do You Need?
The free Twitter developer tier is sufficient to start. It allows 1 search request per 15 minutes. For more frequent polling, the Basic tier ($100/mo) allows 15 requests per 15 minutes.
2. Dashboard Tab
Monitor Status
| Status | Badge Colour | Meaning |
|---|---|---|
| running | Green | Polling Twitter on your configured interval |
| stopped | Gray | Manually stopped, or not yet started |
| no_token | Red | Bearer Token not entered or not saved |
| rate_limited | Amber | Twitter API limit hit — auto-recovers when window resets |
| error | Red | API call failed — check log for details |
Stats Panel
| Stat | What it shows |
|---|---|
| Tweets Checked | Total tweets scanned since the server started |
| Matches Found | Tweets that matched at least one keyword |
| Signals Executed | Signals successfully sent to Webhook Portal or Gunbot |
| Signals Gated | Signals blocked by Webhook Portal gate rules |
| Signals Failed | Delivery failures (Gunbot or Portal unreachable) |
| API Errors | Twitter API call failures |
The Start/Stop button manually starts or stops polling. The monitor auto-starts on server restart if a token is set AND at least one account and keyword are enabled.
3. Accounts Tab
To add an account, enter the Twitter handle without the @ symbol, give it a label, and optionally assign a colour for visual grouping in the log.
The Validate button checks that all accounts can be resolved to Twitter user IDs. Resolved IDs are cached for 24 hours. Accounts can be enabled or disabled individually without deleting them.
Public Accounts Only
Only public Twitter accounts can be watched. Private accounts will fail to resolve and will be flagged as an error in the validation step.
4. Keywords Tab
Keyword Configuration
| Field | What it does | Values |
|---|---|---|
| Term | The word or phrase to match in a tweet | Any text |
| Case Sensitive | Match uppercase/lowercase exactly | On / Off |
| Whole Word | Match whole word only — won't match substring | On / Off |
| Enabled | Whether this keyword is active | On / Off |
| Action | What trade to fire when matched | buy / sell / addpair |
| Exchange | Gunbot exchange name | e.g. binance |
| Symbol | Gunbot pair format | e.g. USDT-BTC |
| Amount | Trade size | Number |
| Signal Mode | Where to route the signal | webhook / gunbot |
Action Types
| Action | What Gunbot does |
|---|---|
buy | Market buy the configured symbol |
sell | Market sell the configured symbol |
addpair | Tell Gunbot to start trading this pair |
Signal Routing
| Mode | Route | Gate rules apply? | When to use |
|---|---|---|---|
webhook |
Sends to Webhook Portal /webhook endpoint |
Yes — all your gate rules run | Recommended — protects against false positives |
gunbot |
Sends directly to Gunbot API | No — executes immediately | Only for highly trusted, confirmed signals |
Use Webhook Mode
Use webhook mode for all keywords. Routing through the Webhook Portal means your indicator filters and gate rules protect you from acting on noise.
5. Log Tab
Every signal event shows: timestamp, account handle, tweet text preview (first 280 characters), matched keyword, action fired, and a status badge.
False Positives — How Matching Works
The tool fetches up to 100 tweets per poll from Twitter. Keyword matching is done locally after fetch — the Twitter search query is broad by design. Some irrelevant tweets may be fetched; only tweets where your keyword actually matches trigger a signal.
6. Config Tab
| Setting | Default | Notes |
|---|---|---|
| Bearer Token | (empty) | From Twitter Developer Portal — shown as •••• after saving |
| Match Mode | any | any = signal fires on ANY keyword match. all = ALL enabled keywords must match the same tweet |
| Signal Mode | webhook | Global default routing. Per-keyword Signal Mode overrides this |
| Webhook URL | http://localhost:8081/webhook | Where to send signals in webhook mode |
| Webhook Secret | (empty) | Must match the Webhook Portal's secret (or leave both empty) |
| Gunbot URL | http://localhost:3001 | For direct gunbot mode |
| Gunbot Token | (empty) | For direct gunbot mode |
| Poll Interval (ms) | 60000 | Minimum is 15000ms (15 seconds). Free tier: keep at 60000+ |
| Filter Retweets | On | Ignore retweets |
| Filter Replies | Off | Ignore replies (turn On to ignore them) |
| Language | en | Only process tweets in this language code |
| Max Results/Poll | 10 | Tweets fetched per API call (10–100) |
7. Rate Limits
| Twitter Tier | Monthly Cost | Search Requests / 15 min | Safe Poll Interval |
|---|---|---|---|
| Free | $0 | 1 | 15 minutes (900,000ms) |
| Basic | $100/mo | 15 | 60 seconds (60,000ms) |
| Pro | $5,000/mo | 450 | 2 seconds |
Free Tier Warning
On the Free tier, set your poll interval to at least 60,000ms (1 minute). The app enforces a minimum of 15,000ms, but polling every 15 seconds on the Free tier will hit the rate limit within the first minute and trigger a temporary ban.
Automatic Rate Limit Recovery
When Twitter returns a 429 (rate limited), the app reads the reset time from the response header, sets status to rate_limited, and waits automatically. It resumes polling as soon as the rate limit window resets. No action is required from you.
8. Testing Sequence
- Enter your Bearer Token in Config tab, click Save
- Add one account — use a high-volume crypto account that tweets frequently
- Add one keyword that is very likely to appear (e.g. "the") — but set Amount to $1 and Signal Mode to "webhook" so gate rules protect you
- Set Poll Interval to 60,000ms
- Click Start — status should change from stopped to running
- Wait up to 60 seconds for the first poll — Tweets Checked stat should increase
- Check the Log tab — any matches will appear here
- Click Force Poll (Config tab) to trigger an immediate poll without waiting for the interval
- Use the Test Signal button to inject a synthetic match — this makes no Twitter API call and sends no real signal unless you confirm
- Verify the synthetic signal appears in the Webhook Portal log (if routing mode is webhook)
- Test rate limit handling: temporarily set poll interval to 15,000ms, run for 2 minutes, verify the status switches to rate_limited and then recovers without crashing
9. Known Limitations
| Limitation | Detail |
|---|---|
| Free tier rate limit | 1 search request per 15 minutes — polling more often triggers rate limiting |
| Read-only Bearer Token | Cannot verify token is valid until first poll attempt |
| Keyword matching is post-fetch | Twitter search is broad; keyword matching runs locally on fetched tweets. Some irrelevant tweets may be fetched but won't trigger signals |
| Whole word matching | Uses word-boundary logic — may not match hyphenated or emoji-adjacent words |
| 500 log entries | Older entries are dropped automatically when the limit is reached |
| No deduplication across restarts | If the server restarts, the same recent tweets may match again on the first poll |
| Language filter | Not 100% reliable — Twitter language detection can misclassify tweets |
10. Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Status stays no_token | Bearer Token not entered or not saved | Enter token in Config tab and click Save |
| Status shows rate_limited | Too many polls per minute for your tier | Increase Poll Interval; the app will auto-recover |
| Status shows error | Twitter API error | Check the Log tab — the error detail is logged there. Common cause: invalid or expired Bearer Token |
| Signals not appearing in Webhook Portal | Wrong Webhook URL in config | Verify Webhook URL in Config matches the Portal address (http://localhost:8081/webhook) |
| Account fails to resolve | Handle doesn't exist or is private | Remove the account; only public accounts can be watched |
| All keywords matching but no signals | Signal Mode set to all but not all keywords matched one tweet |
Switch to any mode, or ensure all keywords would realistically appear in one tweet |
11. Bug Report
Include all of the following when reporting a bug. The more detail you provide, the faster it can be diagnosed.
- Tool: Twitter Monitor (:8083)
- Step-by-step description of what you did
- Expected vs actual behaviour
- Your Twitter account handles and keywords (which specific ones were involved)
- Signal Mode and Webhook URL at the time
- The exact tweet text that triggered (or failed to trigger) the signal
- Health check JSON from http://localhost:8083/health
- Stats panel values at the time (paste all 6 stats)
- Screenshot of Dashboard and Log tab
- Browser and OS version
- Approximate time it happened