Documentation
Everything you need to integrate with Clstr
//Overview
Clstr is a Solana cluster-analysis engine that detects coordinated wallet activity — sybil rings, wash trading, and pump-and-dump cabals. It maps on-chain relationships between wallets using funding overlap, timing correlation, and fund circulation analysis, then renders the results as a visual cluster graph. Scan results are protected with zero-knowledge proofs: you can prove a cluster exists without revealing which wallets are in it.
//How It Works
01 — Funding Overlap
Traces SOL and token funding sources for every wallet that traded a given token. Wallets sharing the same funding parent or grandparent are linked. High overlap between a group of wallets is a strong sybil signal.
02 — Timing Correlation
Measures the temporal distance between buy/sell transactions across wallets. Wallets that consistently trade within seconds of each other — especially in low-liquidity windows — are flagged as likely coordinated.
03 — Fund Circulation
Detects closed loops where funds cycle between wallets — A sends to B, B sends to C, C sends back to A. These cycles indicate wash trading or artificial volume generation between colluding wallets.
//API Reference
| Method | Path | Params | Response |
|---|---|---|---|
| POST | /api/scan/:ca | ca — token contract address | { scanId, status: "queued" } |
| GET | /api/scan/:ca/status | ca — token contract address | { status, progress, eta } |
| GET | /api/scan/:ca/result | ca — token contract address | { clusters, edges, wallets, risk } |
| GET | /api/trending | none | [{ ca, name, symbol, scanCount }] |
| GET | /api/balance/:address | address — wallet public key | { balance, tier, limits } |
| GET | /api/scan/:ca/proof | ca — token contract address | { proof, publicInputHash } |
| POST | /api/verify | { proof, publicInputHash } | { valid: boolean } |
| GET | /api/flags/:wallet | wallet — wallet public key | [{ flagId, reason, txSig, ts }] |
//Tier System
Your tier is determined by the amount of CLSTR tokens held in your connected wallet. Higher tiers unlock deeper scan depths and more daily scans.
| Tier | CLSTR Required | Daily Scans | Max Depth |
|---|---|---|---|
| Free | 0 | 3 | 50 wallets |
| Observer | 1,000 | 10 | 150 wallets |
| Analyst | 10,000 | 50 | 500 wallets |
| Strategist | 100,000 | 200 | 2,000 wallets |
| Overseer | 1,000,000 | Unlimited | Unlimited |
//ZK Proof
Each scan result produces a SHA-256 commitment proof. The proof lets anyone verify that a cluster was detected without revealing the underlying wallet addresses or transaction details.
Public (revealed)
- Token contract address
- Number of clusters found
- Risk score (0–100)
- Scan timestamp
- Public input hash
Hidden (committed)
- Individual wallet addresses
- Transaction signatures
- Funding flow details
- Cluster membership mapping
- Edge weights and scores
Verification
// Verify a scan proof
const res = await fetch('/api/verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ proof, publicInputHash }),
});
const { valid } = await res.json();//Flagging
Any user can flag a wallet as suspicious by burning CLSTR tokens. The burn transaction serves as an immutable, on-chain record that a specific wallet was flagged at a specific time.
How it works
- Connect your wallet and navigate to a scan result
- Click “Flag Wallet” on any wallet node in the cluster graph
- Confirm the burn transaction — a small amount of CLSTR is burned
- The flag is recorded on-chain with the wallet address, reason, and tx signature
- Flagged wallets appear highlighted in future scan results
Cost
Each flag burns 100 CLSTR. This cost prevents spam flagging while keeping the mechanism accessible. The burn is permanent and non-refundable.
//SDK
A TypeScript SDK for programmatic access to all Clstr endpoints is coming soon. It will support scan submission, result polling, proof verification, and wallet flagging with full type safety.
// Coming soon
import { Clstr } from '@clstr/sdk';
const clstr = new Clstr({ apiKey: '...' });
const scan = await clstr.scan('token_ca_here');
const result = await scan.waitForResult();
console.log(result.clusters);Coming soon — follow @clstrlabs for updates