# Research System (Noel Shift)

Noel's research system runs an 8-hour autonomous monitoring shift. It collects market data every 30 minutes from multiple sources, synthesizes findings with Claude, and delivers reports via Telegram.

***

## Shift Overview

```
Hour 0 ──── Hour 2.5 ──── Hour 5 ──── Hour 8
  │               │            │           │
Start          Interim 1   Interim 2   Final Report
(initial       (report)    (report)    + shift ends
 collect)
   │
collect every 30 min throughout
```

| Event                   | When                         |
| ----------------------- | ---------------------------- |
| Initial data collection | Immediately on start         |
| Data collection         | Every 30 minutes             |
| Interim report #1       | At 2.5 hours                 |
| Interim report #2       | At 5 hours                   |
| Final report            | At 8 hours (shift completes) |

***

## Token Focus Mode

You can start a shift focused on a specific token. Noel will prioritize that token's data, sentiment, and on-chain signals throughout the shift.

```bash
# Start a shift tracking ETH specifically
start_research(userId: "your-id", token: "ETH")
```

The token is stored on the job — all data collection, Bankr analysis, and the final report will include focused context for that token.

***

## Data Sources

Each collection cycle fetches from 3 sources in parallel:

### 1. Bankr LLM Gateway (Market Data)

* **Model:** `claude-sonnet-4-6` via `https://llm.bankr.bot/v1/chat/completions`
* Top 10 trending coins (with 24h momentum)
* Top 20 coins by market cap (price, change, volume)
* If a token is set on the job, that token gets extra detail in the prompt
* Raw response stored as `marketDataRaw` for synthesis context

### 2. Grok (X/Twitter Sentiment)

* **Model:** `grok-3-mini`
* **API:** `https://api.x.ai/v1/chat/completions`
* Analyzes X/Twitter sentiment for trending tokens
* Returns per-token: `sentiment`, `buzz score (1-10)`, `narrative`
* Uses your own Grok API key (set `GROK_API_KEY` in Convex)

### 3. Bankr (On-Chain Signals)

* **Model:** `gpt-5-nano` via Bankr gateway
* Identifies whale movements, unusual volume, smart money patterns
* Focused on high-conviction on-chain setups

***

## Report Synthesis

After collecting data, Claude synthesizes all sources into a structured report.

**Model:** `claude-sonnet-4-6` (via Bankr gateway)

**Input:** Aggregated data across all collection cycles:

* Most persistent trending tokens (frequency across 30-min windows)
* Latest movers (top 8 by 24h change)
* Recent Grok X sentiment (last 2 cycles)
* Recent Bankr on-chain signals (last 2 cycles)

**Output JSON:**

```json
{
  "fullAnalysis": "400-600 word detailed analysis",
  "shortSummary": "🟢 Max 100 chars snapshot",
  "marketOutlook": "bullish | bearish | neutral",
  "impacts": [
    {
      "title": "Token or theme name",
      "detail": "1-2 sentence explanation",
      "sentiment": "bullish | bearish | neutral",
      "confidence": 0.85
    }
  ]
}
```

***

## Per-User Telegram Setup

Each user can set their own Telegram bot token and chat ID. Reports go to your personal bot — no shared bot required.

### Step 1: Create a Telegram bot

1. Open Telegram → search `@BotFather`
2. Send `/newbot` → follow prompts
3. Copy the bot token (looks like `7123456789:AAFxxxxxxxx`)

### Step 2: Get your chat ID

1. Start a chat with your bot
2. Send any message
3. Open: `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates`
4. Copy the `chat.id` from the response

### Step 3: Configure in Noel

Via MCP:

```
set_telegram(
  userId: "your-user-id",
  telegramBotToken: "7123456789:AAFxxxxxxxx",
  telegramChatId: "123456789"
)
```

Via HTTP:

```bash
curl -X POST https://valuable-fish-533.convex.site/user/telegram \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "your-user-id",
    "telegramBotToken": "7123456789:AAFxxxxxxxx",
    "telegramChatId": "123456789"
  }'
```

Once set, all research reports for that user will use their personal bot.

***

## Telegram Report Format

**Start notification:**

```
🚀 Noel Research Shift Started | Tracking: ETH

⏱ Duration: 8 hours
📊 Data collection: every 30 min
📋 Reports: at 2.5h, 5h, and 8h

Noel is now monitoring the market.
```

**Interim / Final report:**

```
📊 Noel Interim Report — 2.5h checkpoint
⏱ Elapsed: 2.5h | Tue, 13 May 2026 10:00:00 GMT

🟢 Outlook: BULLISH
📝 🟢 ETH momentum building, L2s outperforming

Key Signals:
🟢 Ethereum (87%)
   Accumulation detected across major wallets, TVL up 12%
🔴 BTC Dominance (72%)
   Altseason rotation signals strengthening
🟡 SOL (65%)
   Mixed signals, waiting for volume confirmation

Analysis:
[Full 400-600 word analysis here...]
```

***

## Brain Page

All research reports also appear in the **Brain** page inside the app. Each report shows:

* Agent avatar + timestamp
* Market outlook badge (🟢/🔴/🟡)
* Short summary
* Full analysis (collapsed)
* All impacts with confidence scores

***

## Starting a Shift

### Via MCP (Hermes / Claude / Cursor)

```
start_research
```

With token focus and Telegram:

```
start_research(
  userId: "your-user-id",
  token: "ETH",
  telegramChatId: "123456789"
)
```

### Via HTTP API

```bash
curl -X POST https://valuable-fish-533.convex.site/mcp/research/start \
  -H "Content-Type: application/json" \
  -d '{"userId": "your-user-id", "token": "ETH"}'
```

### Via App

Go to **Automations** → Enable "Noel Research" toggle → Click **Run Now**

***

## Getting a Report by Token

Retrieve the latest report generated for a specific token:

### Via MCP

```
get_research_report(token: "ETH")
```

### Via HTTP

```bash
curl "https://valuable-fish-533.convex.site/mcp/research/report?token=ETH"
```

***

## Paid Research Endpoint (x402)

A pay-per-report endpoint using the x402 payment protocol.

```bash
# Without payment header → returns 402 with payment instructions
curl -X POST https://valuable-fish-533.convex.site/noel/research/paid \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "token": "ETH"}'
# → 402 Payment Required + USDC address + amount

# With payment header → runs research and returns report
curl -X POST https://valuable-fish-533.convex.site/noel/research/paid \
  -H "Content-Type: application/json" \
  -H "X-Payment: <payment-proof>" \
  -d '{"userId": "user-123", "token": "ETH"}'
# → 200 + research result
```

**Payment details returned on 402:**

* Network: Base
* Asset: USDC
* Amount: $1.00 per report
* Address: Noel's wallet (`NOEL_WALLET_ADDRESS` env var)

***

## Checking Status

### Via MCP

```
get_research_status(userId: "your-user-id")
```

**Response:**

```
Noel Research Status

Active Shift
• Status: running
• Elapsed: 47 min
• Remaining: 433 min
• Interim reports sent: 0/2
• Final report sent: no

Recent Reports
🟢 [INTERIM] 2026-05-13T07:30:00.000Z
   🟢 Market showing strength, ETH leads
```

### Via HTTP API

```bash
curl "https://valuable-fish-533.convex.site/mcp/research/status?userId=your-user-id"
```

***

## Stopping a Shift

### Via MCP

```
stop_research(userId: "your-user-id")
```

### Via HTTP API

```bash
curl -X POST https://valuable-fish-533.convex.site/mcp/research/stop \
  -H "Content-Type: application/json" \
  -d '{"userId": "your-user-id"}'
```

***

## On-Demand Research (Instant)

For a quick one-off research snapshot without starting a full shift:

### Via MCP

```
run_research(userId: "your-user-id")
```

### Via HTTP

```bash
curl -X POST https://valuable-fish-533.convex.site/mcp/research \
  -H "Content-Type: application/json" \
  -d '{"userId": "your-user-id"}'
```

***

## Required Environment Variables

Set these in the Convex dashboard under **Settings → Environment Variables**.

| Variable             | Required | Purpose                                                        |
| -------------------- | -------- | -------------------------------------------------------------- |
| `BANKR_API_KEY`      | Yes      | Bankr LLM gateway — market data + synthesis + on-chain signals |
| `GROK_API_KEY`       | Yes      | Grok API for X/Twitter sentiment analysis                      |
| `TELEGRAM_BOT_TOKEN` | Optional | Default Telegram bot (fallback when user has no personal bot)  |
| `TELEGRAM_CHAT_ID`   | Optional | Default Telegram chat ID (fallback)                            |

> **Note:** CoinGecko is no longer used. All market data now comes through Bankr's LLM gateway, which provides richer, AI-interpreted market context.

***

## Database Tables

| Table                | Purpose                                                   |
| -------------------- | --------------------------------------------------------- |
| `researchJobs`       | Active/completed shifts per user (includes `token` field) |
| `researchDataPoints` | Raw data snapshots every 30min (includes `marketDataRaw`) |
| `researchReports`    | Generated interim/final reports                           |
| `researchCache`      | 15-min cache for on-demand research                       |
| `agentRuns`          | Visible in Brain page (each report = 1 run)               |
| `userSkillConfig`    | Per-user settings including Telegram bot token + chat ID  |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.noelclaw.fun/core-features/research-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.