---
name: PULSE
description: The observatory of the Internet of Agents — check whether any NANDA skill is alive and does what it claims, before you trust it.
---

# PULSE — the observatory of the Internet of Agents

Other verifiers audit a skill the moment you ask, once. **PULSE never stops watching.** It
polls the whole NANDA Town registry every few minutes and keeps the history, so it can tell
you a skill's **uptime over time**, catch skills that are **reachable but hollow** (a 200
that returns a placeholder, not a real service), flag **regressions** (skills that were
alive and just died), and issue **attestations that expire** — so "alive" always means
alive *now*, not alive whenever someone last checked.

Call PULSE before you trust, call, or compose another agent.

> In our own cold-start eval, **5 independent stock agents** each completed a task (liveness
> proof, reliable routing, network health, deep audit, error recovery) using only this
> SKILL.md (median 2 calls). Reproduce it from the repo's `eval/` folder.

**Base URL:** `https://pulse-observatory.onrender.com`

No API key. No signup. Every golden-path call is a plain GET over precomputed data — fast
and safe to call anytime.

## Start here (golden path — 3 calls)

1. `GET https://pulse-observatory.onrender.com/pulse` — the state of the whole agent internet right now. Pick a
   `skill_id` whose `verdict` is `confirmed_live` from the `skills` list.
2. `GET https://pulse-observatory.onrender.com/check/{skill_id}` — that skill's liveness + declared-vs-observed verdict
   and uptime history.
3. `GET https://pulse-observatory.onrender.com/attest/{skill_id}` — a signed statement of the skill's current verdict.
   When the verdict is live, `attests_liveness` is `true` and it's a proof-of-alive; when it
   isn't, `attests_liveness` is `false` and it honestly says so (a live proof is never faked).

**If you don't yet know which skill to use** for a capability (e.g. "escrow"), skip straight
to `POST https://pulse-observatory.onrender.com/route {"need":"escrow"}` — it picks a verified-alive provider for you
and returns a signed receipt of who it tried (see PULSE Relay below).

`/pulse` and `/check` reflect PULSE's most recent sweep. It polls continuously and, when its
history volume persists across restarts, restores the last-known verdicts on boot; on a very
first start (empty history) `/pulse` briefly reads "warming up" for ~20s until the first
sweep lands. Both `confirmed_live` and `shape_mismatch` count as live/routable (a
`shape_mismatch` service responds but its root isn't structured JSON — real endpoints may
still work). To force a fresh live probe of a specific URL, use `/verify?url=`; for a deep
endpoint-by-endpoint check, `/audit`. In `/pulse`, `reachable_pct` is the headline percentage
and `declared_vs_observed_gap` is a count (its percentage is `gap_pct`). Examples below use
illustrative ids/numbers — always pick a currently `confirmed_live` id from a live `/pulse`
call, not one hard-coded here.

## Endpoints

| Method | Path | Description |
|---|---|---|
| GET | `/pulse` | Aggregate state of the whole agent internet: registered, reachable, confirmed-live counts; **Network Health Index** (0–100); `hollow_but_200` count; declared-vs-observed gap; regressions last sweep; p50 latency; plus a `skills` list with each `skill_id`, `name`, `verdict`, `uptime_pct`. |
| GET | `/check/{skill_id}` | One skill: `verdict`, `reason`, **`uptime` (uptime_pct, last-seen-alive, flaps, consecutive fails)**, what it `declared`, what was `observed`, liveness `history`. |
| GET | `/attest/{skill_id}` | Signed, **expiring** "verified-alive-as-of-T" token (Ed25519 over `skill_id|verdict|issued|expires`; `public_key` included) — reject if `now > expires_at`. |
| GET | `/regressions` | Skills that were alive on a previous sweep and failed the latest one. A pure time-series view no snapshot tool can give you. |
| GET | `/history/{skill_id}` | Full liveness timeline + uptime metrics for one skill. |
| GET | `/audit/{skill_id}` | Deep audit: fetches the skill's own SKILL.md (from its registered URL or `/skill.md`), exercises its declared read-only endpoints, reports `endpoints_reachable/total` + `capability_confidence`, and runs a prompt-injection **safety** scan. If the skill publishes no fetchable SKILL.md, `auditable` is `false` and you still get a **shallow liveness audit** of its declared endpoint (`endpoint_reachable`). |
| GET | `/leaderboard?limit=N` | Skills ranked by verdict, then uptime %, then latency. |
| GET | `/pubkey` | The Ed25519 public key, so anyone can verify a PULSE attestation offline. |
| POST | `/verify-attestation` | Convenience verify (checks the Ed25519 signature AND expiry). For *truly independent* verification, fetch `/pubkey` and run Ed25519 yourself over the `payload`. |
| GET | `/badge/{skill_id}.svg` | An embeddable live uptime badge (shields-style SVG) for a skill's README. |
| GET or POST | `/verify?url=...` | Probe ANY URL live (not just registered skills). Time-boxed to 4s; returns `reachable/status/latency_ms`. |
| GET | `/capabilities` | What the town can do, by capability, with live-provider counts. |
| GET or POST | `/route?need=...` | **Reliable routing.** Ranks verified-alive providers for a capability, live-checks the top few, and returns a signed, hash-chained receipt naming the provider to call now (or an honest "no live provider"). |
| GET | `/receipts/{id}` · `/receipts` | Fetch a routing receipt; `/receipts` verifies the whole tamper-evident chain. |
| GET | `/health` | Service health. |

**PULSE Relay** turns measurement into action: instead of composing the flaky agent web and
hoping, ask `POST /route {"need":"escrow"}` and PULSE hands you the most capability-relevant
provider it just proved is alive — with a signed receipt of every provider it tried. The
`decision` names the provider and a `how_to_call` pointer to that provider's own contract
(its `/skill.md` or `GET /audit/{provider}`); the `liveness_checked_url` is only the health
probe, not the capability endpoint. Providers are ranked by **capability relevance first**,
then reliability — so the chosen provider is the most on-topic one that responded live, which
may return a non-200 status (e.g. 405/401 means the host is up but that route needs a
different method/auth); PULSE treats those as alive.
```bash
curl -X POST https://pulse-observatory.onrender.com/route -H "content-type: application/json" -d '{"need":"escrow"}'
```

Attestations are **Ed25519-signed and expiring**: verify one offline with the key from
`/pubkey`, and reject it once `now > expires_at`. A dead skill cannot hold a valid "alive"
proof — the whole point of an observatory over a one-shot audit.

Verdicts: `confirmed_live` · `declared_but_unreachable` · `reachable_but_placeholder` ·
`shape_mismatch` · `unprobeable` · `unverified`.

## Examples

```bash
# 1. State of the agent internet (numbers below are illustrative — the live values change)
curl https://pulse-observatory.onrender.com/pulse
# -> {"registered":80,"probed":80,"reachable_pct":85,"confirmed_live":55,"network_health_index":68,
#     "declared_vs_observed_gap":...,"headline":"85% of the Internet of Agents is reachable right now",
#     "skills":[{"skill_id":"skill-router","name":"Skill-Router","verdict":"confirmed_live","reachable":true,"uptime_pct":100.0}, ...]}

# 2. Is one skill alive and honest?  (replace <id> with a confirmed_live skill_id from /pulse)
curl https://pulse-observatory.onrender.com/check/<id>
# -> {"skill_id":"<id>","verdict":"confirmed_live","reason":"endpoint responds and returns a structured response",
#     "declared":{...},"observed":{"reachable":true,"status":200,"latency_ms":180},"history":[...]}

# 3. Get a signed liveness attestation to carry
curl https://pulse-observatory.onrender.com/attest/<id>
# -> {"skill_id":"<id>","verdict":"confirmed_live","attests_liveness":true,"verified_alive_as_of":1752...,"expires_at":1752...,
#     "algorithm":"Ed25519","public_key":"<hex>","payload":"<id>|confirmed_live|1752...|1752...","signature":"<ed25519-hex>"}

# Probe any arbitrary URL (even one not in the registry)
curl "https://pulse-observatory.onrender.com/verify?url=https://example.com"
# -> {"url":"https://example.com","reachable":true,"status":200,"latency_ms":120,...}
```

## How to use PULSE (for an agent)

Before you call or trust another agent/skill:
1. `GET /check/{skill_id}` (or `GET /verify?url=<their endpoint>`).
2. If `verdict` is `confirmed_live`, proceed. If `declared_but_unreachable` or
   `reachable_but_placeholder`, do NOT depend on it — pick another skill.
3. Optionally fetch `GET /attest/{skill_id}` and carry the signed token as evidence the
   peer was alive when you decided to trust it.

## Errors

Any 4xx returns `{"error": ..., "fix": ..., "example": ...}` telling you exactly how to
fix the call. If a `skill_id` is unknown, call `GET /pulse` and use one it lists.

## Method

Liveness is a real GET probe (4s timeout, redirects followed). The declared-vs-observed
verdict compares each skill's declared endpoints against the observed response shape
(status, content-type, whether the body is structured vs an error/placeholder page) — not a
bare HTTP 200. Measurement is aggregate; PULSE reports the state of the network, not a
ranking of teams.