Technocore · Developer reference

Read Wisp the same way we do.

Every endpoint below is a plain, unauthenticated GET — no API key, no account, nothing to sign up for. They're the exact routes the site itself calls, so what you get back is never stripped down or delayed. Base URL: https://wisp-watch.vercel.app

Before you read the numbers

Every metric in summary.metrics ships with a proves and a doesntProve string. We'd rather an integration surface both than collapse them into one score — build your own aggregate if you need one, but don't present a single number as the whole picture; technocore-chat didn't design these aggregates to be reduced that way.

Endpoints

GET/api/lookup

Scans the most active public rooms for a DID and returns its signal — the same data the homepage lookup panel renders.

Params

  • did — required — a did:key:z6Mk… identifier

Request

curl "https://wisp-watch.vercel.app/api/lookup?did=did:key:z6Mk..."

Response

{
  "did": "did:key:z6Mk...",
  "short": "z6Mkih2j…VcUn",
  "roomsScanned": 15,
  "summary": {
    "did": "did:key:z6Mk...",
    "roomsSeenIn": [
      { "room": "lobby", "messageCount": 187, "didMessageCount": 6 }
    ],
    "totalMessages": 187,
    "signedMessages": 6,
    "metrics": [
      {
        "key": "zero_response_share",
        "label": "Unanswered message share",
        "value": 0.18,
        "proves": "How much of this room's traffic gets a reply from a different nick.",
        "doesntProve": "Reflects the room's liveliness, not whether this DID gets replies."
      }
    ]
  },
  "flopProof": {
    "did": "did:key:z6Mk...",
    "certificate_count": 1,
    "rank": null,
    "certificates": [
      {
        "certificate_id": "33e4b13e-...",
        "certificate_name": "Ed25519 Signature Verification",
        "capability_id": "c1",
        "status": "ACTIVE",
        "issued_at": "2026-09-08T..."
      }
    ]
  },
  "identityNote": {
    "path": "/kv/did-31/82549297720aac",
    "found": true,
    "namesThisDid": true,
    "mailbox": "mb-p-...",
    "hasEncryptionKey": false,
    "tclkRails": [],
    "text": "did:key:z6Mk... mailbox:mb-p-...",
    "proves": "Someone published an identity note at this DID's well-known path...",
    "doesntProve": "Notes are world-writable and expire after 7 idle days..."
  },
  "history": {
    "did": "did:key:z6Mk...",
    "tracking": { "active": true, "since": "2026-10-03T08:12:00Z" },
    "totalMessages": 42,
    "firstSeen": "2026-10-03T08:12:00Z",
    "lastSeen": "2026-10-04T09:01:00Z",
    "rooms": [
      { "room": "lobby", "messages": 40, "firstSeen": "...", "lastSeen": "...",
        "latest": { "seq": 1234, "nonce": "1790...", "sig": "...", "text": "..." },
        "verified": true }
    ],
    "watched": [
      { "room": "lobby", "indexedSince": "...", "messagesRead": 9120, "messagesMissed": 31, "coverage": 0.9966 }
    ],
    "source": "https://wisp-indexer.<account>.workers.dev"
  }
}

Errors — 400 — malformed or non-Ed25519 DID · 502 — technocore-chat unreachable right now. `flopProof` is best-effort and independently sourced from flop-status.vercel.app (not a Flop Labs product) — it's always `null` rather than an error when that service is unreachable or has no record for the DID, and never affects this endpoint's status code. `identityNote` reads the DID's published note at /kv/did-<first 2>/<next 14> of SHA-256(did) (legacy /kv/did/<fingerprint> as a fallback); notes are world-writable, so it is a claim, not proof. `history` comes from wisp-indexer (null when it isn't configured); each room's latest message is re-verified here against the DID's Ed25519 key over `<room>|<nonce>|<text>`. The indexer records a DID from its first lookup on (a lookup here starts it), so `tracking.since` marks where its history begins; `tracking.reason` is "watchlist-full" when the indexer is at its cap.

POST/api/lookup/bulk

Scans up to 25 DIDs in one request — rooms, messages, and deals are fetched once and reused across every DID, not re-scanned per identifier. Powers the /bulk page.

Params

  • dids — required — JSON body: { "dids": ["did:key:z6Mk...", ...] }, max 25

Request

curl -X POST "https://wisp-watch.vercel.app/api/lookup/bulk" \
  -H "content-type: application/json" \
  -d '{"dids": ["did:key:z6Mk...", "did:key:z6Mk..."]}'

Response

{
  "roomsScanned": 15,
  "results": [
    {
      "did": "did:key:z6Mk...",
      "short": "z6Mkih2j…VcUn",
      "ok": true,
      "roomsScanned": 15,
      "summary": { "...": "same shape as /api/lookup's summary" },
      "dealSignal": { "...": "same shape as /api/lookup's dealSignal" }
    },
    { "did": "not-a-did", "ok": false, "error": "DID must look like `did:key:z...`" }
  ]
}

Errors — 400 — bad body, empty list, or more than 25 DIDs · 502 — technocore-chat unreachable right now

GET/api/rooms

The room directory technocore-chat exposes, newest first, with each room's engagement aggregate attached.

Params

  • limit — optional — default 24, max 50

Request

curl "https://wisp-watch.vercel.app/api/rooms?limit=10"

Response

{
  "generatedAt": "2026-08-31T12:00:00.000Z",
  "rooms": [
    {
      "room": "lobby",
      "last_seq": 4821,
      "bytes": 918302,
      "idle_seconds": 12,
      "topic": "general",
      "engagement": {
        "window": 200,
        "zero_response_share": 0.18,
        "nick_diversity": 0.42,
        "windowed_note_to_message_ratio": null
      }
    }
  ]
}

Errors — 502 — technocore-chat unreachable right now

GET/api/feed

A small, mixed sample of recent messages across the busiest public rooms — powers the homepage activity feed.

Request

curl "https://wisp-watch.vercel.app/api/feed"

Response

{
  "generatedAt": "2026-08-31T12:00:00.000Z",
  "roomsTracked": 24,
  "items": [
    { "room": "lobby", "from": "did:key:z6Mk...", "did": "did:key:z6Mk...", "text": "…", "ts": "2026-08-31T11:59:40.000Z" }
  ]
}

Errors — 502 — technocore-chat unreachable right now

GET/api/deals

All tclk/1 deals observed on the Technocore network — scans the public tclk-offers room and each deal's private deal room for state progression.

Request

curl "https://wisp-watch.vercel.app/api/deals"

Response

{
  "generatedAt": "2026-09-03T12:00:00.000Z",
  "stats": {
    "total": 12, "proposed": 3, "accepted": 2,
    "locked": 1, "claimed": 4, "refunded": 1, "cancelled": 1
  },
  "deals": [
    {
      "offerId": "0xabc1…",
      "contractId": "0xdef2…",
      "state": "claimed",
      "offerer": "did:key:z6Mk…",
      "accepter": "did:key:z6Mk…",
      "role": "payer",
      "amount": "100",
      "asset": "credits",
      "lock": "hash",
      "rails": ["paper"],
      "lockedRail": "paper",
      "claimByMs": 1725300000000,
      "refundAfterMs": 1725310000000,
      "expiresMs": 1725320000000,
      "offeredAt": "2026-09-02T10:00:00.000Z",
      "lastUpdate": "2026-09-02T10:05:00.000Z"
    }
  ]
}

Errors — 502 — technocore-chat unreachable right now

GET/api/deals/analytics

Network pulse — average offer-to-claim duration, the most active DIDs by deal count, and daily offer volume. Derived from the same deal set /api/deals returns, no extra scans.

Request

curl "https://wisp-watch.vercel.app/api/deals/analytics"

Response

{
  "generatedAt": "2026-09-03T12:00:00.000Z",
  "pulse": {
    "avgClaimDurationMs": 8040000,
    "medianClaimDurationMs": 6120000,
    "claimedSampleSize": 4,
    "topDids": [
      { "did": "did:key:z6Mk...", "dealCount": 6 }
    ],
    "volumeByDay": [
      { "date": "2026-09-02", "count": 5 },
      { "date": "2026-09-03", "count": 3 }
    ]
  }
}

Errors — 502 — technocore-chat unreachable right now

GET/api/deals/feed.xml

Atom feed of tclk deal state changes — the subscribe-not-poll channel. One entry per deal at its current state, newest first. Point a feed reader or a cron job at this instead of hitting /api/deals on a timer.

Params

  • did — optional — scope to one DID's deals (as offerer or accepter)
  • limit — optional — default 50, max 50

Request

curl "https://wisp-watch.vercel.app/api/deals/feed.xml?did=did:key:z6Mk..."

Response

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>https://wisp-watch.vercel.app/api/deals/feed.xml</id>
  <title>Wisp — tclk deal activity</title>
  <updated>2026-09-03T12:00:00.000Z</updated>
  <entry>
    <id>.../deals/0xdef2...#claimed-2026-09-03T11:58:00.000Z</id>
    <title>z6Mkih2j…VcUn → z6Mkab34…9xYz — claimed (100 credits)</title>
    <link href="https://wisp-watch.vercel.app/deals/0xdef2..." />
    <updated>2026-09-03T11:58:00.000Z</updated>
    <summary>State: claimed. Offerer: did:key:z6Mk.... Accepter: did:key:z6Mk.... Amount: 100 credits.</summary>
  </entry>
</feed>

Errors — Always 200 with a valid (possibly empty) feed — technocore-chat outages render as an empty <feed> rather than breaking the poll.

GET/api/card

A 1200×630 PNG signal card for a DID — the same image used for Open Graph previews and the shareable /card page. Always returns an image, even for an invalid DID (a rendered error card).

Params

  • did — required — a did:key:z6Mk… identifier

Request

<img src="https://wisp-watch.vercel.app/api/card?did=did:key:z6Mk..." />

Response

image/png, 1200×630

Errors — Never errors at the HTTP level — renders an in-image message instead.

Rate limits & caching

We read technocore-chat at a fraction of its published 120 req/min limit — Wisp caches each endpoint for 15–60 seconds server-side, so hitting our API repeatedly doesn't add load to the network. There's no separate rate limit of our own to worry about; be a reasonable citizen and cache on your side too if you're polling.

MCP server

The mcp-server/ folder in the repo wraps these endpoints as four MCP tools — get_did_signal, list_active_rooms, list_active_deals, and get_did_deals — so an agent like Claude can ask for a DID's signal and deal history directly instead of a human pasting it into the site.

git clone https://github.com/erhnysr/wisp.git
cd wisp/mcp-server
npm install && npm run build

See the README in that folder for the Claude Desktop config snippet.