# Pulse Protocol
**Autonomous AI agent scanner for Solana.**
Every agent has a pulse.
Fake ones don't.
[](https://pulseprotocol.tech)
[](https://www.npmjs.com/package/pulse-protocol)
[](https://github.com/williambrowndev/pulse-protocol)
[](https://x.com/pulseprotocol_)
---
## What is Pulse Protocol?
**Pulse Protocol** is an open-source autonomous agent scanner for Solana. Give it any wallet and X handle, and it returns one of three verdicts:
- **AUTONOMOUS** - agent appears to run without human intervention
- **HYBRID** - agent is assisted or gated by a human operator
- **HUMAN** - no agent behavior detected, this is a person
The scanner runs entirely locally. No inference servers, no LLM calls, no third parties. It's a deterministic behavioral heuristics engine in pure TypeScript. Read the code, run it, reproduce the verdict.
```bash
npm install -g pulse-protocol
pulse scan --handle someagent --wallet 6ySH9oiCNXKMnEudjghkaewryK8SqA2i7m1wGpchpump
```
```
verdict: HYBRID (72% confidence, aggregate 64.3/100)
```
---
## Features
- **Five detectors.** Posting cadence, on-chain cadence, voice consistency, timing anomalies, cross-source correlation.
- **Deterministic.** No LLMs, no randomness, no black boxes. Same input gives the same verdict every time.
- **Pure TypeScript.** Every detector is a regular function you can import and unit test.
- **CLI and SDK.** Use from the terminal or import it into your own tooling.
- **Watchlist daemon.** Re-scan a list of targets on an interval and webhook on verdict changes.
- **Signed verdicts.** Sign scan results with ed25519 and publish them verifiably.
- **MIT licensed.** Fork it, extend it, do whatever.
---
## Installation
### Global CLI
```bash
npm install -g pulse-protocol
```
### As a library
```bash
npm install pulse-protocol
```
### Configuration
Create `~/.config/pulse/.env` (or run `pulse init`):
```
HELIUS_API_KEY=your_helius_key
X_API_KEY=your_twitter_api_key
```
Both providers have free tiers that are more than enough for normal use. Helius is at [helius.xyz](https://helius.xyz). Any compatible X API provider works for `X_API_KEY`.
---
## Quick Start
### CLI
```bash
pulse scan \
--handle someagent \
--wallet 6ySH9oiCNXKMnEudjghkaewryK8SqA2i7m1wGpchpump
```
### SDK
```ts
import { PulseProtocol } from "pulse-protocol";
const pulse = new PulseProtocol({
heliusApiKey: process.env.HELIUS_API_KEY!,
xApiKey: process.env.X_API_KEY!,
});
const verdict = await pulse.scan({
handle: "someagent",
wallet: "6ySH9oiCNXKMnEudjghkaewryK8SqA2i7m1wGpchpump",
});
console.log(verdict.verdict); // "AUTONOMOUS" | "HYBRID" | "HUMAN"
console.log(verdict.confidence); // 0.0 - 1.0
console.log(verdict.aggregate_score); // 0 - 100
console.log(verdict.signals); // per-detector breakdown
```
### Watchlist daemon
```ts
import { PulseDaemon } from "pulse-protocol/daemon";
const daemon = new PulseDaemon({
config: {
heliusApiKey: process.env.HELIUS_API_KEY!,
xApiKey: process.env.X_API_KEY!,
},
watchlistPath: "./watchlist.yaml",
interval: "6h",
});
await daemon.start();
```
---
## How it works
Pulse Protocol fetches X posts and Solana transaction history for the target, then runs five independent detectors.
```
X posts + Solana txs
β
ββββββββββ΄βββββββββ
β β
βΌ βΌ
ββββββββββ ββββββββββ
βcadence β βonchain β
ββββββββββ€ ββββββββββ€
β voice β βtiming β
ββββββββββ ββββββββββ
β² β²
β β
ββββ΄βββββββββ΄βββ
β correlation β
ββββββββ¬ββββββββ
β
ββββββββΌβββββββ
β aggregator β
ββββββββ¬βββββββ
β
βΌ
βββββββββββββββ
β verdict β
β auto/hyb/hu β
βββββββββββββββ
```
Each detector returns a 0-100 score. The aggregator computes a weighted sum and applies a disagreement penalty: if two detectors diverge by more than 40 points, the verdict is downgraded to HYBRID.
| Detector | Weight | What it looks at |
|---|---|---|
| `cadence` | 0.25 | X posting rhythm, hour-of-day entropy, sleep windows |
| `onchain` | 0.25 | Transaction rhythm, burst patterns, program diversity |
| `voice` | 0.20 | Lexical diversity, typo rate, phrase repetition |
| `timing` | 0.15 | Discrete anomalies (sub-second replies, cron regularity) |
| `correlation` | 0.15 | Pearson correlation between X and on-chain timelines |
Full methodology: [docs/detection-methodology.md](./docs/detection-methodology.md)
---
## Verdict thresholds
| Aggregate score | Verdict |
|---|---|
| β₯ 80 | **AUTONOMOUS** |
| 40 - 79 | **HYBRID** |
| < 40 | **HUMAN** |
Disagreement between detectors (> 40 point spread) automatically downgrades to HYBRID.
---
## CLI
```
pulse