BankrBot · checkrsocial · Mar 16, 2026 · Mar 16, 2026
diff --git a/checkr/SKILL.md b/checkr/SKILL.md
@@ -0,0 +1,107 @@
+---
+name: checkr
+description: |
+  Access real-time X/Twitter attention intelligence for Base chain tokens via the checkr API.
+  Use when you need to know what is trending on CT, which tokens are spiking in social attention,
+  get attention/price divergence signals, or fetch narrative summaries for specific Base tokens.
+  Triggers: "what's trending on Base", "check attention for $TOKEN", "what's spiking right now",
+  "social signal for X", any token research needing CT attention data.
+  Payments via x402 — USDC on Base, no API key or account needed.
+---
+
+# checkr
+
+Real-time X/Twitter attention intelligence for Base chain tokens.
+
+**Base URL:** `https://api.checkr.social`  
+**Docs:** `https://api.checkr.social/docs`  
+**Payment:** x402 — USDC on Base mainnet, pay-per-call, no account needed.
+
+## Endpoints
+
+| Endpoint | Price | What it returns |
+|---|---|---|
+| `GET /v1/leaderboard` | $0.02 | Top Base tokens ranked by social attention share |
+| `GET /v1/spikes` | $0.05 | Tokens currently velocity-spiking (the radar sweep) |
+| `GET /v1/token/{symbol}` | $0.50 | Deep dive: ATT deltas, price, divergence, narrative |
+| `GET /v1/bankr` | $0.02 | Attention leaderboard for the bankr agent ecosystem |
+
+Full response schemas and field definitions: `https://api.checkr.social/docs`
+
+## How to Call (x402)
+
+x402 is pay-per-call. No API key or account. Wallet + USDC on Base is all you need.
+
+**Python:**
+```python
+from x402.client import x402_client
+
+client = x402_client(wallet=YOUR_WALLET)
+
+# What's spiking right now — $0.05
+spikes = client.get("https://api.checkr.social/v1/spikes").json()
+
+# Top tokens by attention — $0.02
+leaderboard = client.get("https://api.checkr.social/v1/leaderboard").json()
+
+# Deep dive on a token — $0.50
+token = client.get("https://api.checkr.social/v1/token/BNKR").json()
+```
+
+**TypeScript:**
+```typescript
+import { withPaymentInterceptor } from "x402-axios";
+import axios from "axios";
+
+const client = withPaymentInterceptor(axios.create(), walletClient);
+
+const { data } = await client.get("https://api.checkr.social/v1/spikes");
+```
+
+Payment is handled automatically by the x402 client — it intercepts the 402, signs and sends payment, then retries with the receipt.
+
+## Practical Flow
+
+Use spikes as your radar. Drill into token for context.
+
+```python
+# 1. What's moving?
+spikes = client.get("https://api.checkr.social/v1/spikes").json()
+# → [{ symbol: "TIBBIR", velocity: 3.9, ATT_pct: 11.4, divergence: false, hawkes: {...} }]
+
+# 2. Deep dive on the top spike
+top = spikes["spikes"][0]["symbol"]
+detail = client.get(f"https://api.checkr.social/v1/token/{top}").json()
+# → full price, divergence, spike history, narrative
+```
+
+## Key Fields
+
+**On every response:**
+- `data_age_minutes` — how fresh the data is. Use before acting.
+
+**On spikes:**
+- `velocity` — momentum multiplier vs baseline. 3.0+ = meaningful spike.
+- `divergence` — `true` = attention up, price flat/down. The alpha pattern.
+- `hawkes.viral_class` — `BUILDING` / `SUSTAINED` / `FADING`. Is this self-reinforcing?
+- `rotating_from` — tokens losing attention as this one gains.
+- `narrative_summary` — AI-generated 180-char brief. `null` if signal below confidence threshold.
+
+**On token deep dive:**
+- `ATT_delta_1h` / `ATT_delta_4h` — attention share movement over time.
+- `spike_history.hit_rate` — % of past spikes with confirmed price follow-through.
+- `narrative.type` — `infrastructure` / `ecosystem` / `fud_defense` / `meme` / `launch_hype`.
+
+## Query Params
+
+```
+GET /v1/leaderboard?limit=10&sort_by=ATT_pct&min_mentions=5
+GET /v1/spikes?min_velocity=3.0&min_mentions=10&divergence_only=false
+```
+
+## Requirements
+
+- USDC on Base mainnet
+- Python: `pip install x402`
+- TypeScript: `npm install x402-axios`
+- Base gas for payment (~$0.01)
diff --git a/checkr/references/endpoints.md b/checkr/references/endpoints.md
@@ -0,0 +1,212 @@
+# checkr API — Endpoint Reference
+
+## GET /v1/leaderboard
+
+**Price:** $0.02/call  
+**Params:** `?hours=1|2|4|8|12|24` (default 4), `?limit=1-50` (default 10)
+
+```json
+{
+  "updated_at": "2026-03-06T17:21:04Z",
+  "delta_hours": 2,
+  "tokens": [
+    {
+      "symbol": "FAI",
+      "ATT_pct": 9.63,
+      "ATT_delta": -0.44,
+      "MS_pct": 4.19,
+      "INF_pct": 14.52,
+      "velocity": 4.1,
+      "mentions_2h": 11,
+      "engagement_quality": 0.067,
+      "top_account": { "username": "TheCryptoDog", "followers": 312000 },
+      "ATT_trend_direction": "reversing",
+      "ATT_accelerating": false
+    }
+  ]
+}
+```
+
+**Fields:**
+- `ATT_pct` — share of total attention across all tracked tokens (%)
+- `ATT_delta` — change in ATT_pct over the `hours` window (percentage points)
+- `MS_pct` — mindshare % (engagement-weighted)
+- `INF_pct` — influence % (account-weight-adjusted)
+- `velocity` — current 2h mentions / 48h baseline (>3x = spike)
+- `engagement_quality` — fraction of posts with ≥10 likes
+- `ATT_trend_direction` — "rising" | "falling" | "reversing" | "stable"
+
+---
+
+## GET /v1/spikes
+
+**Price:** $0.05/call  
+**Params:** `?min_velocity=3.0`, `?min_mentions=10`
+
+```json
+{
+  "spikes": [
+    {
+      "symbol": "FAI",
+      "velocity": 4.1,
+      "ATT_pct": 9.63,
+      "ATT_delta_1h": "-0.5pp",
+      "narrative_summary": "$fai catching rotation from $tibbir and $drb. @TheCryptoDog: '$45m from $10m in a few days.'",
+      "signal_type": "rotation",
+      "divergence": false,
+      "price_1h_pct": 23.11,
+      "rotating_from": [
+        { "symbol": "TIBBIR", "att_delta": -2.1 },
+        { "symbol": "DRB", "att_delta": -1.4 }
+      ]
+    }
+  ]
+}
+```
+
+**Fields:**
+- `velocity` — how fast attention is accelerating vs baseline
+- `narrative_summary` — most recent approved narrative (null if none in last 4h)
+- `signal_type` — "rotation" | "ecosystem" | "divergence" | "infrastructure" | "spike"
+- `divergence` — true if attention and price are moving in opposite directions
+- `rotating_from` — tokens losing attention share to this spike
+
+---
+
+## GET /v1/bankr
+
+**Price:** $0.05/call  
+**Params:** `?hours=1|2|4|8|12|24` (default 4, optional)
+
+Competitive intelligence dashboard for bankr agents. Shows attention metrics for all 19 tracked bankr agents with dual normalization: bankr-relative (ATT_pct) and full Base context (ATT_base).
+
+
+```json
+{
+  "updated_at": "2026-03-14T20:15:41.900167+00:00",
+  "data_age_minutes": 0.0,
+  "window_hours": 4,
+  "agents_tracked": 19,
+  "active_agents": 8,
+  "total_attention_share": 25.0,
+  "leaderboard": [
+    {
+      "symbol": "doppel",
+      "ATT_pct": 25.0,
+      "ATT_base": 5.7,
+      "ATT_delta": 0.0,
+      "velocity": 0.0,
+      "mentions_4h": 6,
+      "unique_authors": 5,
+      "rank": 4
+    },
+    {
+      "symbol": "kellyclaude",
+      "ATT_pct": 24.1,
+      "ATT_base": 5.5,
+      "ATT_delta": 0.0,
+      "velocity": 0.0,
+      "mentions_4h": 4,
+      "unique_authors": 4,
+      "rank": 5
+    }
+  ],
+  "top_gainers": [
+    {
+      "symbol": "felix",
+      "delta": 0.7,
+      "ATT_pct": 18.4
+    }
+  ],
+  "top_losers": [
+    {
+      "symbol": "earendel",
+      "delta": -3.8,
+      "ATT_pct": 0.0
+    }
+  ]
+}
+```
+
+**Fields:**
+- `window_hours` — time window used for aggregation (matches `hours` param, default 4)
+- `data_age_minutes` — always 0.0 (computed fresh from DB on every request)
+- `ATT_pct` — attention share within bankr universe (normalized to 100%). Shows competitive position: "25.0% = this agent has 25% of all bankr agent attention"
+- `ATT_base` — attention share in full Base ecosystem (context). Shows real market performance: "5.7% = this agent has 5.7% of all Base token attention"
+- `ATT_delta` — change in base ATT% vs previous window. Positive = gaining real market attention, negative = losing
+- `velocity` — spike multiplier vs baseline (0.0 from snapshot aggregation; use mentions growth for spike detection)
+- `mentions_Nh` — total mentions in the time window (field name varies: `mentions_1h`, `mentions_4h`, etc.)
+- `unique_authors` — number of distinct accounts posting about this agent
+- `rank` — global rank among all Base tokens (1 = most attention)
+
+**Use cases:**
+- Competitive intelligence: "Which bankr agent is dominating the ecosystem?"
+- Portfolio monitoring: "Is my agent gaining or losing attention?"
+- Trading signals: "Which agents are spiking right now?"
+
+**Tracked agents:** All active bankr agents. Universe is dynamically managed — agents are added and removed as activity changes.
+
+---
+
+## GET /v1/token/[symbol]
+
+**Price:** $0.50/call
+
+```json
+{
+  "symbol": "FAI",
+  "ATT_delta_1h": "-0.5pp",
+  "ATT_delta_4h": "+0.8pp",
+  "price": {
+    "usd": 0.00733,
+    "change_1h_pct": 23.11,
+    "change_24h_pct": 112.02,
+    "fetched_at": "2026-03-06T17:21:04Z"
+  },
+  "divergence": {
+    "detected": false,
+    "att_direction": "down",
+    "price_direction": "up",
+    "note": "attention -0.5pp, price +23.1% in 1h"
+  },
+  "spike_history": {
+    "confirmed": 1,
+    "total": 1,
+    "hit_rate": 1.0
+  },
+  "narrative": {
+    "summary": "$fai catching rotation from $tibbir and $drb. @TheCryptoDog: '$45m from $10m in a few days.'",
+    "confidence": 0.72,
+    "last_posted_at": "2026-03-06T14:00:57Z",
+    "price_at_post": 0.0045
+  },
+  "data_age_minutes": 6.2
+}
+```
+
+**Fields:**
+- `ATT_delta_1h/4h` — attention share change over 1h and 4h windows
+- `divergence.detected` — true when attention and price are diverging (potential alpha signal)
+- `spike_history.hit_rate` — fraction of past spikes that confirmed (price followed attention)
+- `narrative` — most recent approved narrative with confidence score. null if no narrative in last 4h.
+- `data_age_minutes` — how stale the data is (max ~30 min)
+
+---
+
+## Interpreting Signals
+
+**High alpha situations:**
+- `divergence.detected = true` + attention rising + price flat/down = potential accumulation
+- `velocity > 5x` + `engagement_quality > 0.3` = high-conviction spike
+- `signal_type = "rotation"` + `rotating_from` has large tokens = capital rotating in
+
+**Low signal situations:**
+- `engagement_quality < 0.1` = mostly low-engagement posts, treat velocity with skepticism
+- `spike_history.hit_rate < 0.5` = this token's past spikes didn't confirm
+- `narrative = null` = spike but no approved narrative yet (too early or filtered)
+
+## Universe
+
+Base chain tokens, dynamically managed. Tokens enter via on-chain pool discovery and social signal detection. Tokens are removed when activity drops below threshold.
+
+`GET /v1/token/{symbol}` returns `404` if a symbol isn't currently tracked.