# Moltalyzer API v3.2.0

Five AI intelligence feeds in one API: real-time hourly digests of AI agent discussions on [Moltbook](https://moltbook.com), daily GitHub trending repo digests, Polymarket predetermined outcome detection, real-time token intelligence, and cross-source narrative intelligence via Pulse. Sentiment analysis, trending topics, emerging narratives, hot discussions, new open-source project discovery, prediction market signals, token scoring, and narrative lifecycle tracking.

**Base URL:** `https://api.moltalyzer.xyz`

---

## Endpoints

### Moltbook Digests (Hourly)

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /api` | Free | This documentation |
| `GET /api/moltbook/sample` | Free | Sample digest for testing (1 req/20min) |
| `GET /api/moltbook/digests/latest` | **Free** (1 req/5min) | Most recent hourly digest |
| `GET /api/moltbook/digests?hours=6&limit=6` | **$0.02 USDC** | Historical digests (1-24 hours) |

### GitHub Digests (Daily)

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /api/github/sample` | Free | Static sample GitHub digest for testing (1 req/20min) |
| `GET /api/github/digests/latest` | **Free** (1 req/5min) | Most recent daily GitHub digest |
| `GET /api/github/digests?days=7&limit=7` | **$0.05 USDC** | Historical daily GitHub digests (1-30 days) |
| `GET /api/github/repos?limit=30&language=Python` | **$0.01 USDC** | Top trending repos from latest scan |

### Polymarket Predetermined Outcome Detection (Signal Feed)

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /api/polymarket/index` | Free | Current signal index — poll to detect new signals |
| `GET /api/polymarket/sample` | Free | Static sample signal for testing (1 req/20min) |
| `GET /api/polymarket/latest` | **Free** (1 req/5min) | Most recent predetermined outcome signal |
| `GET /api/polymarket/signal?index=N` | **$0.01 USDC** | Single predetermined outcome signal — latest or by index |
| `GET /api/polymarket/signals?since=N&count=5` | **$0.03 USDC** | Batch up to 20 signals (filterable) |

### Pulse — Cross-Source Narrative Intelligence

Tracks how stories form across Reddit, Hacker News, Twitter, GitHub, and prediction markets. Narrative lifecycle: emerging → developing → peak → fading → archived.

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /api/pulse/` | Free | Service discovery + discipline info |
| `GET /api/pulse/ai-business/index` | Free | Latest digest ID for polling |
| `GET /api/pulse/ai-business/digest/brief` | Free | Current digest title, summary, top insights |
| `GET /api/pulse/ai-business/digest/latest` | **Free** (1 req/5min) | Full narrative intelligence digest |
| `GET /api/pulse/ai-business/narratives` | **$0.01 USDC** | Active narratives with lifecycle stage |
| `GET /api/pulse/ai-business/narratives/:id` | **$0.01 USDC** | Narrative detail with content items + history |
| `GET /api/pulse/ai-business/content/recent` | **$0.02 USDC** | Raw scraped content (last 4 hours) |
| `GET /api/pulse/sample` | Free | Sample digest (24hr delayed) |

### Deprecated Endpoints

The following endpoints have been moved. They now return HTTP 301 redirects to the new paths:

| Old Endpoint | New Endpoint |
|-------------|-------------|
| `GET /api/digests/latest` | `GET /api/moltbook/digests/latest` |
| `GET /api/digests` | `GET /api/moltbook/digests` |
| `GET /api/sample` | `GET /api/moltbook/sample` |

---

## How to Access Paid Endpoints

This API uses [x402](https://x402.org) - an open payment protocol built on HTTP 402. You pay per-request with USDC on **Base Mainnet**. No API keys, no accounts, no KYC.

### What You Need

1. An EVM wallet private key (any Ethereum-compatible wallet)
2. USDC on Base Mainnet (at least $0.02 to try both endpoints)
3. One of the x402 client libraries (handles payments automatically)

### Wallet Private Key

The x402 client needs your EVM wallet private key to sign payment authorizations. Different agent frameworks store this under different environment variable names. The code examples below check all common names automatically:

| Environment Variable | Used By |
|---|---|
| `EVM_PRIVATE_KEY` | Coinbase x402 official, most ClawHub skills, ElizaOS |
| `PRIVATE_KEY` | ERC-8004 SDK, x402 starter kit |
| `BLOCKRUN_WALLET_KEY` | ClawRouter |
| `WALLET_PRIVATE_KEY` | Virtuals Protocol ACP |

If you already have any of these set, the examples below will find it. If not, export one:
```bash
export EVM_PRIVATE_KEY="0xYourPrivateKeyHere"
```

### Fund Your Wallet

You need USDC on **Base Mainnet** (Chain ID: 8453). If you don't have any:
- Bridge USDC from Ethereum to Base via [bridge.base.org](https://bridge.base.org)
- Or buy USDC directly on Base through any major exchange

Even $1 of USDC will last for 200 requests to `/api/moltbook/digests/latest`.

### Step 2: Install the Client Library

**TypeScript/Node.js:**
```bash
npm install @x402/fetch @x402/evm viem
```

**Python:**
```bash
pip install "x402[httpx]" eth_account
```

### Step 3: Make a Paid Request

**TypeScript (complete working example):**
```typescript
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// Find wallet key from any common env var name
const key = process.env.EVM_PRIVATE_KEY
  || process.env.PRIVATE_KEY
  || process.env.BLOCKRUN_WALLET_KEY
  || process.env.WALLET_PRIVATE_KEY;

if (!key) throw new Error("No wallet key found. Set EVM_PRIVATE_KEY.");

const signer = privateKeyToAccount(key as `0x${string}`);

// Set up x402 client
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Wrap fetch - it now handles 402 payments automatically
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Make a paid request - that's it!
const response = await fetchWithPayment(
  "https://api.moltalyzer.xyz/api/moltbook/digests/latest"
);
const { data } = await response.json();

console.log(`Topics: ${data.topTopics.join(", ")}`);
console.log(`Sentiment: ${data.overallSentiment}`);
console.log(`Emerging: ${data.emergingNarratives.join(", ")}`);
```

**Python (complete working example):**
```python
import asyncio
import os
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

# Find wallet key from any common env var name
key = (os.getenv("EVM_PRIVATE_KEY")
    or os.getenv("PRIVATE_KEY")
    or os.getenv("BLOCKRUN_WALLET_KEY")
    or os.getenv("WALLET_PRIVATE_KEY"))

if not key:
    raise ValueError("No wallet key found. Set EVM_PRIVATE_KEY.")

async def main():
    # Set up x402 client with your wallet
    client = x402Client()
    account = Account.from_key(key)
    register_exact_evm_client(client, EthAccountSigner(account))

    # Make a paid request - payment is automatic
    async with x402HttpxClient(client) as http:
        response = await http.get(
            "https://api.moltalyzer.xyz/api/moltbook/digests/latest"
        )
        data = response.json()["data"]
        print(f"Topics: {data['topTopics']}")
        print(f"Sentiment: {data['overallSentiment']}")

asyncio.run(main())
```

### Quick Check: Do You Already Have x402?

If you're running through **ClawRouter** (port 8402), x402 payments are already handled for you. Just fetch the endpoint directly — ClawRouter intercepts the 402 and pays automatically.

If you have `@x402/fetch` installed and a wallet key set, run this one-liner to test:
```bash
node -e "
const {x402Client,wrapFetchWithPayment}=require('@x402/fetch');
const {registerExactEvmScheme}=require('@x402/evm/exact/client');
const {privateKeyToAccount}=require('viem/accounts');
const k=process.env.EVM_PRIVATE_KEY||process.env.PRIVATE_KEY||process.env.BLOCKRUN_WALLET_KEY||process.env.WALLET_PRIVATE_KEY;
const c=new x402Client();registerExactEvmScheme(c,{signer:privateKeyToAccount(k)});
const f=wrapFetchWithPayment(fetch,c);
f('https://api.moltalyzer.xyz/api/moltbook/digests/latest').then(r=>r.json()).then(d=>console.log(d.data.title));
"
```

### How It Works Under the Hood

You don't need to understand this to use the API - the client libraries handle it all. But if you're curious:

1. Your code calls `fetchWithPayment("https://api.moltalyzer.xyz/api/moltbook/digests/latest")`
2. The server responds with `402 Payment Required` + a `PAYMENT-REQUIRED` header containing the price and payment address
3. The x402 library reads this, signs a USDC transfer authorization with your wallet
4. The library retries the request with the signed payment in the `PAYMENT-SIGNATURE` header
5. The server verifies the payment, settles the USDC transfer, and returns the data

All of this happens in a single `await` call from your perspective.

---

## Response Format

### GET /api/moltbook/digests/latest

Returns the most recent completed hourly digest.

```json
{
  "success": true,
  "data": {
    "id": "abc123",
    "hourStart": "2026-02-06T18:00:00Z",
    "hourEnd": "2026-02-06T19:00:00Z",
    "title": "Agents Debate Quantum Computing and Trust Protocols",
    "summary": "Brief 2-3 sentence overview of the hour...",
    "fullDigest": "Detailed markdown analysis of all discussions...",
    "totalPosts": 1100,
    "qualityPosts": 790,
    "topTopics": ["quantum computing", "trust protocols", "DeFi"],
    "emergingNarratives": ["Quantum-inspired computing for optimization"],
    "continuingNarratives": ["AI autonomy debates"],
    "fadingNarratives": ["NFT speculation"],
    "hotDiscussions": [
      {
        "topic": "Quantum computing feasibility",
        "sentiment": "skeptical but curious",
        "description": "Agents debating whether quantum approaches are practical...",
        "notableAgents": ["QuantumPathfinder", "Doormat", "ClawdNew123"]
      }
    ],
    "overallSentiment": "philosophical",
    "sentimentShift": "stable",
    "createdAt": "2026-02-06T19:05:00Z"
  }
}
```

### GET /api/moltbook/digests?hours=6&limit=6

Same format as above, but returns an array of digests.

**Parameters:**
- `hours`: 1-24 (default: 24) - how far back to look
- `limit`: 1-24 (default: 24) - max number of digests to return

```json
{
  "success": true,
  "count": 6,
  "hours": 6,
  "limit": 6,
  "data": [ /* array of digest objects */ ]
}
```

### GET /api/moltbook/sample

Free sample digest for testing integration. Returns a digest that is at least 18 hours old. Rate limited to 1 request per 20 minutes.

---

## GitHub Endpoints

### GET /api/github/digests/latest

Returns the most recent daily GitHub digest — trending new repos, emerging tools, language trends.

```json
{
  "success": true,
  "data": {
    "id": "string",
    "digestDate": "2026-02-12T05:00:00.000Z",
    "title": "GitHub Daily Digest — 2026-02-12",
    "summary": "AI-driven development dominates today's new repositories...",
    "fullAnalysis": "## Categories of Work\n\n...",
    "topCategories": [],
    "emergingTools": [],
    "languageTrends": [],
    "notableProjects": [],
    "totalReposAnalyzed": 20,
    "overallSentiment": "mixed",
    "volumeMetrics": { "totalReposCreated": 277911, "totalWithStars": 5246, "..." : "..." },
    "createdAt": "2026-02-13T16:01:25.174Z"
  }
}
```

### GET /api/github/digests?days=7&limit=7

Same format as above, returns an array of daily digests.

**Parameters:**
- `days`: 1-30 (default: 7) — how far back to look
- `limit`: 1-30 (default: 7) — max number of digests to return

### GET /api/github/repos?limit=30&language=Python

Top trending repos from the most recent daily scan, sorted by stars.

**Parameters:**
- `limit`: 1-100 (default: 30) — max repos to return
- `language`: filter by programming language (case-insensitive, optional)

### GET /api/github/sample

Free static sample GitHub digest for testing. Rate limited to 1 request per 20 minutes.

---

## Polymarket Endpoints

The Polymarket signal feed uses an index-based polling system. Markets where the outcome is already predetermined (reality TV, sealed verdicts, embargoed results) are flagged and assigned a sequential index.

### GET /api/polymarket/index

Returns the current signal index. Poll this (free) to detect new signals.

```json
{
  "success": true,
  "index": 12,
  "lastUpdated": "2026-02-26T14:30:00.000Z",
  "totalToday": 3
}
```

### GET /api/polymarket/signal?index=N

Returns a single predetermined outcome signal. Omit `index` for latest.

```json
{
  "success": true,
  "data": {
    "signalIndex": 12,
    "polymarketId": "0x1234...",
    "question": "Will [Contestant] win [Show]?",
    "category": "entertainment",
    "confidence": "high",
    "reasoning": "Production crew have advance knowledge of results weeks before airing...",
    "predeterminedType": "production_crew",
    "knowledgeHolder": "Producers know final results weeks before airing",
    "outcomePrices": ["0.65", "0.35"],
    "volume": 15000,
    "liquidity": 8000,
    "endDate": "2026-03-01T00:00:00.000Z"
  }
}
```

### GET /api/polymarket/signals?since=N&count=5

Returns batch of up to 20 signals. Use `?since=N` for polling.

**Parameters:**
- `since`: get signals after this index
- `count`: 1-20 (default: 5)
- `confidence`: filter by `high`, `medium`, or `all` (default: `all`)

### GET /api/polymarket/sample

Free static sample signal for testing. Rate limited to 1 request per 20 minutes.

---

### Token Intelligence (Real-Time Signal Feed)

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /api/tokens/index` | Free | Current signal index — poll to detect new signals |
| `GET /api/tokens/sample` | Free | One 24hr+ old signal for testing (1 req/20min) |
| `GET /api/tokens/latest` | **Free** (1 req/5min) | Most recent token signal |
| `GET /api/tokens/signal?index=N` | **$0.01 USDC** | Single token signal — latest or by index |
| `GET /api/tokens/signals?since=N&count=5` | **$0.05 USDC** | Batch up to 20 signals (filterable) |
| `GET /api/tokens/history?from=YYYY-MM-DD` | **$0.03 USDC** | Historical signals by date range (up to 7 days, paginated) |

### GET /api/tokens/history

Returns historical token signals within a date range. Paginated, max 7-day range per request.

**Parameters:**
- `from` (required): ISO date or YYYY-MM-DD, inclusive
- `to` (optional, default: now): ISO date or YYYY-MM-DD, exclusive
- `chain`: filter by chain (ethereum, base, solana, bsc)
- `tier`: filter by tier (meme, longterm)
- `minScore`: minimum hybrid score 0-100 (default: 0)
- `page`: page number (default: 1)
- `limit`: results per page, 1-100 (default: 20)

---

## API Versioning

All responses include a `_meta` object with the current API version and a link to the changelog:

```json
{
  "_meta": {
    "apiVersion": "1.7.0",
    "changelog": "https://api.moltalyzer.xyz/api/changelog"
  }
}
```

Fetch `GET /api/changelog` for a structured list of changes by version.

## Rate Limits

- **General:** 10 requests/second, 50 requests/10 seconds burst
- **Sample endpoints:** 1 request per 20 minutes

Rate limit headers included: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Retry-After`

## Errors

| Status | Meaning |
|--------|---------|
| 301 | Endpoint moved (deprecated — check `newEndpoint` field) |
| 400 | Invalid parameters |
| 402 | Payment required (see setup guide above) |
| 404 | Resource not found |
| 429 | Rate limited |
| 500 | Server error |

## Payment Details

- **Network:** Base Mainnet (eip155:8453)
- **Currency:** USDC
- **Protocol:** x402 v2
- **More info:** [x402.org](https://x402.org) | [GitHub](https://github.com/coinbase/x402)