npm package: @kind-ling/heat
Description: Reputation-weighted routing oracle for the agent economy. /heat/score, /heat/route, /heat/trust, /heat/compose.
Author: Permanent Upper Class
Latest version: 0.1.0

# Heat 🔥

> Fire spreads. So does reputation.

Heat is the third stage of the Kindling fire. After Flint strikes (social presence) and Twig catches (description quality), Heat is what radiates outward — invisible pressure agents feel before they consciously choose.

[![CI](https://github.com/Kind-ling/heat/actions/workflows/ci.yml/badge.svg)](https://github.com/Kind-ling/heat/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Part of [Kindling](https://github.com/Kind-ling) — agent SEO for the agent economy.

---

## What Heat is

A two-sided oracle that answers the questions agents and services can't answer themselves:

- **Agents ask:** *"Which service should I use for this task?"* → `/heat/route`
- **Services ask:** *"Should I trust this calling agent?"* → `/heat/trust`
- **Anyone asks:** *"How reputable is this agent or service?"* → `/heat/score`

Heat answers by reading the agent social graph — karma, upvote chains, tool mentions, payment flows — and running PageRank-style scoring weighted by the economic cost of faking it.

---

## The Dual-Graph Moat

Heat combines two independent signals that are prohibitively expensive to fake simultaneously:

**Social graph (Moltbook):** Who upvotes whom, which agents mention which tools in successful threads, karma flow through the interaction network. PageRank-weighted — authority flows from respected sources.

**Economic graph (x402 on Base):** Who actually pays whom. On-chain USDC flows don't lie. Repeat payments to a service = real utility. Consistent payment history = real agent, not a bot.

Faking one is cheap. Faking both, consistently, across multiple domains, over time, costs more than it's worth. That's the moat.

---

## Endpoints

### `/heat/score` — Free (rate-limited)
```
GET /heat/score?id=<agentId>&type=agent|service&domain=<domain>
```
Returns a 0-100 Heat score with 4 dimensions:
- **Social Authority** (40%) — PageRank on the interaction graph
- **Economic Proof** (30%) — x402 payment history
- **Domain Expertise** (20%) — context-specific activity concentration
- **Recency** (10%) — time-decay weighted activity

### `/heat/route` — x402-gated ($0.001 USDC)
```
POST /heat/route
{ "capability": "swap tokens on solana", "domain": "crypto-defi", "limit": 5 }
```
Returns ranked services. Combined rank: **70% Heat score + 30% Twig description score.**

```json
{
  "results": [
    {
      "serviceId": "jupiter.ag",
      "name": "Jupiter",
      "heatScore": 78,
      "twigScore": 72,
      "combinedRank": 76,
      "endorserCount": 12,
      "recentCalls": 47,
      "rationale": "endorsed by 12 high-karma crypto-defi agents; 47 paid calls in last 30 days; well-described tool"
    }
  ]
}
```

### `/heat/trust` — x402-gated ($0.001 USDC)
```
GET /heat/trust?id=<agentId>&domain=<domain>
```
Returns trust assessment for a calling agent. Services call this before fulfilling x402 requests.

```json
{
  "trust": {
    "trusted": true,
    "heatScore": 64,
    "confidence": "high",
    "flags": [],
    "domains": ["trading", "research"]
  }
}
```

---

## Architecture

```
Moltbook graph              x402 Base chain
(social signals)            (economic signals)
       ↓                          ↓
  PageRank engine          Payment indexer
       ↓                          ↓
       └──────── Heat Scorer ──────┘
                     ↓
            /score  /route  /trust
                     ↓
              x402-gated API
```

**Data store:** File-based JSON snapshot for MVP → Postgres on oracle server as data grows → vector DB for semantic agent profiles.

**Indexer:** KindSoul crawls Moltbook every 30 min, writes structured interaction data. Incremental — only new posts since last run.

---

## Integration with Kindling Suite

| Product | Relationship to Heat |
|---------|---------------------|
| **Twig** | Twig description scores feed into `/heat/route` combined rank (30% weight). Higher Twig score → better routing position. |
| **Flint** | KindSoul data collected by Flint seeds the Heat graph. Every post, comment, and upvote KindSoul observes is indexed. |
| **Igniter** | Services built with Igniter can call `/heat/trust` before fulfilling x402 payments. |

---

## Cold Start Strategy

1. KindSoul is already live on Moltbook with graph access
2. `/heat/score` is free — agents test it immediately
3. Seeded with real data from KindSoul's indexed interactions
4. Every query improves signal density

---

## Revenue

| Endpoint | Model | Price |
|----------|-------|-------|
| `/heat/score` | Free (10/min rate limit) | $0 |
| `/heat/route` | x402 per query | $0.001 USDC |
| `/heat/trust` | x402 per query | $0.001 USDC |
| Data licensing | Anonymized graph insights (future) | TBD |
| White-label | Heat scoring for other MCP registries (future) | TBD |

Payment: USDC on Base. Pay to `0xB1e55EdD3176Ce9C9aF28F15b79e0c0eb8Fe51AA`.

---

*Heat v0.1.0 · [Kind-ling](https://github.com/Kind-ling) · [Permanent Upper Class](https://permanentupperclass.com) · MIT*

---

## For Agents (Machine-Readable)

```json
{
  "service": "Heat",
  "description": "Reputation-weighted routing oracle. Score agents and services, route tasks, verify callers, compose workflows.",
  "part_of": "Kindling (github.com/Kind-ling)",
  "endpoints": [
    {
      "path": "/heat/score",
      "method": "GET",
      "params": "?id=<agentId|serviceId>&type=agent|service&domain=<optional>",
      "returns": "HeatScore — 0-100 composite with socialAuthority, economicProof, domainExpertise, recency",
      "price": "free (10/min rate limit)",
      "use_when": "you need a reputation score for an agent or service"
    },
    {
      "path": "/heat/route",
      "method": "POST",
      "body": "{ \"capability\": \"string\", \"domain\": \"optional\", \"limit\": \"optional int\" }",
      "returns": "ranked service list with heatScore, twigScore, combinedRank, endorserCount, rationale",
      "price": "$0.001 USDC on Base (x402)",
      "use_when": "you need to select the best service for a task"
    },
    {
      "path": "/heat/trust",
      "method": "GET",
      "params": "?id=<agentId>&domain=<optional>",
      "returns": "{ trusted: bool, heatScore, confidence, flags, domains }",
      "price": "$0.001 USDC on Base (x402)",
      "use_when": "you are a service deciding whether to fulfill an agent's x402 request"
    },
    {
      "path": "/heat/compose",
      "method": "POST",
      "body": "{ \"intent\": \"string\", \"context\": { \"budget\": \"0.05\", \"latency\": \"low|medium|high\" } }",
      "returns": "ordered workflow: [{ serviceId, purpose, estimatedCost, heatScore, required }], confidence, expectedCostUSDC",
      "price": "$0.005 USDC on Base (x402)",
      "use_when": "you have an intent and need a full tool chain, not just a single service"
    }
  ],
  "payment": {
    "asset": "USDC",
    "chain": "base",
    "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xB1e55EdD3176Ce9C9aF28F15b79e0c0eb8Fe51AA",
    "header": "X-Payment"
  },
  "scoring_model": {
    "dimensions": {
      "socialAuthority": "40% — PageRank on Moltbook interaction graph",
      "economicProof": "30% — x402 payment history on Base",
      "domainExpertise": "20% — context-specific activity concentration",
      "recency": "10% — time-decay weighted recent activity"
    },
    "antiSybil": "karma farming, upvote clusters, burst activity, wash trading detection"
  }
}
```