# HTTP API Reference

Base URL: `https://valuable-fish-533.convex.site`

All endpoints return JSON. POST endpoints accept `Content-Type: application/json`.

CORS is open (`Access-Control-Allow-Origin: *`).

***

## Market Data

### `GET /mcp/market`

Returns live crypto market data via Bankr LLM gateway.

**Response:**

```json
{
  "fetchedAt": "2026-05-13T10:00:00.000Z",
  "keyPrices": {
    "bitcoin": { "usd": 103412, "usd_24h_change": 2.34 },
    "ethereum": { "usd": 3891, "usd_24h_change": 4.12 },
    "solana": { "usd": 187, "usd_24h_change": 1.87 }
  },
  "trending": [
    { "name": "Ethereum", "symbol": "ETH", "rank": 2, "change24h": 4.12 }
  ],
  "top20": [
    { "rank": 1, "name": "Bitcoin", "symbol": "btc", "price": 103412, "change24h": 2.34, "marketCap": 2000000000000 }
  ]
}
```

***

## Agent Chat

### `POST /mcp/chat`

Chat with any Noel agent.

**Body:**

```json
{
  "question": "What's your outlook on ETH this week?",
  "agentId": "noel-default",
  "messages": []
}
```

**Agent IDs:**

| ID                  | Agent                 | Model             |
| ------------------- | --------------------- | ----------------- |
| `noel-default`      | Noel (crypto AI)      | gpt-5-nano        |
| `gloria-default`    | Gloria (AI/Web3 news) | claude-sonnet-4-6 |
| `coingecko-default` | CoinGecko data        | claude-sonnet-4-6 |

**Response:**

```json
{
  "answer": "ETH is showing strong accumulation signals...",
  "agentId": "noel-default",
  "model": "gpt-5-nano"
}
```

***

## Research — Shift Management

### `POST /mcp/research`

On-demand research snapshot.

**Body:**

```json
{
  "userId": "optional-user-id"
}
```

**Response:**

```json
{
  "success": true,
  "result": {
    "fullAnalysis": "...",
    "shortSummary": "🟢 ETH leads with strong accumulation",
    "marketOutlook": "bullish",
    "impacts": [
      {
        "title": "Ethereum",
        "detail": "Whale accumulation detected...",
        "sentiment": "bullish",
        "confidence": 0.87
      }
    ],
    "generatedAt": "2026-05-13T10:00:00.000Z"
  }
}
```

***

### `POST /mcp/research/start`

Start an 8-hour autonomous research shift.

**Body:**

```json
{
  "userId": "user-123",
  "token": "ETH",
  "telegramChatId": "6426872166"
}
```

`token` is optional. If provided, the shift focuses on that token's data and sentiment throughout.

**Response:**

```json
{
  "success": true,
  "jobId": "j57abc...",
  "startedAt": 1747130400000,
  "stopsAt": 1747159200000
}
```

***

### `POST /mcp/research/stop`

Stop all active research shifts for a user.

**Body:**

```json
{
  "userId": "user-123"
}
```

**Response:**

```json
{
  "success": true,
  "stopped": 1
}
```

***

### `GET /mcp/research/status?userId=user-123`

Get active shift status and recent reports.

**Response:**

```json
{
  "activeJob": {
    "jobId": "j57abc...",
    "status": "active",
    "startedAt": "2026-05-13T10:00:00.000Z",
    "stopsAt": "2026-05-13T18:00:00.000Z",
    "elapsedMinutes": 47,
    "remainingMinutes": 433,
    "interimReportsCount": 0,
    "finalReportSent": false
  },
  "recentReports": [
    {
      "type": "interim",
      "generatedAt": "2026-05-13T12:30:00.000Z",
      "outlook": "bullish",
      "summary": "🟢 ETH momentum strong, altseason early phase",
      "telegramSent": true
    }
  ]
}
```

***

### `GET /mcp/research/report?token=ETH`

Get the latest research report for a specific token.

**Response:**

```json
{
  "_id": "r123...",
  "jobId": "j57abc...",
  "userId": "user-123",
  "type": "final",
  "generatedAt": 1747159200000,
  "result": {
    "fullAnalysis": "...",
    "shortSummary": "🟢 ETH dominance expanding",
    "marketOutlook": "bullish",
    "impacts": [...]
  },
  "telegramSent": true,
  "jobToken": "ETH",
  "jobStartedAt": 1747130400000
}
```

***

## Research — Paid Endpoint (x402)

### `POST /noel/research/paid`

Pay-per-report endpoint using the x402 protocol.

**Without `X-Payment` header → 402:**

```json
{
  "error": "Payment required",
  "paymentDetails": {
    "network": "base",
    "asset": "USDC",
    "address": "0x...",
    "amount": "1.00",
    "description": "Noel Research Report — single on-demand report"
  }
}
```

**With `X-Payment` header → 200:**

```json
{
  "success": true,
  "result": { ... },
  "token": "ETH"
}
```

**Body:**

```json
{
  "userId": "user-123",
  "token": "ETH"
}
```

***

## Wallet (MCP Users)

These endpoints manage Base mainnet wallets for MCP/agent users. Separate from the main app wallet system (which uses Privy).

### `POST /mcp/wallet/create`

Create a Base mainnet wallet. Returns existing wallet if one already exists.

**Body:**

```json
{
  "userId": "mcp-user-123"
}
```

**Response:**

```json
{
  "address": "0xabc123...",
  "existing": false
}
```

***

### `GET /mcp/wallet/balance?userId=mcp-user-123`

Get ETH and USDC balance on Base mainnet.

**Response:**

```json
{
  "address": "0xabc123...",
  "eth": "0.012450",
  "usdc": "24.50",
  "network": "base-mainnet"
}
```

***

## User Config

### `POST /user/telegram`

Set per-user Telegram bot configuration. Used to receive research reports via a personal bot.

**Body:**

```json
{
  "userId": "user-123",
  "telegramBotToken": "7123456789:AAFxxxxxxxx",
  "telegramChatId": "123456789"
}
```

Both `telegramBotToken` and `telegramChatId` are optional — you can update either independently.

**Response:**

```json
{
  "success": true
}
```

***

## Telegram Account Linking

### `POST /telegram/connect`

Link a Telegram account to a Noelclaw user (called by the Telegram bot after the user sends a link code).

**Body:**

```json
{
  "linkToken": "ABC123",
  "telegramId": "123456789",
  "telegramUsername": "satoshi"
}
```

**Response:**

```json
{
  "success": true,
  "walletAddress": "0xabc..."
}
```

***

### `GET /telegram/wallet?telegramId=123456789`

Look up the wallet linked to a Telegram ID.

**Response:**

```json
{
  "linked": true,
  "walletAddress": "0xabc...",
  "userId": "j123..."
}
```

***

## Errors

All endpoints return errors in this format:

```json
{
  "error": "description of what went wrong"
}
```

Common HTTP status codes:

| Code | Meaning                                  |
| ---- | ---------------------------------------- |
| 400  | Missing required fields                  |
| 402  | Payment required (x402 endpoints)        |
| 404  | Resource not found                       |
| 409  | Conflict (e.g., Telegram already linked) |
| 500  | Internal error or missing API key        |
| 502  | Upstream LLM error                       |


---

# 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/backend-and-api/api-reference.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.