Check a claim. See the receipt. Keep your keys.
Placeholder path: public/trustshell-demo-20s.mp4. Source file, when it exists: E:\TrustDisk\video\trustshell-demo-20s.mp4. The player is hidden until that file is there.
npm i -g @hyperdag/trustshell@1.4.0
trustshell verify "The capital of France is Paris."
trustshell verify "The Eiffel Tower is located in Rome, Italy."| Today | |
|---|---|
npm latest |
1.4.0 (npm view @hyperdag/trustshell version, 2026-09-24). |
| HAL quorum | 2 answering / 8 configured (measured). Not a constant 6. |
| Chain | Base Sepolia, not mainnet. |
| Grounding | shadow — does not mutate live RepID. |
Not a launch announcement.
Most "LLM trust" tools are judges — they score an output and leave the decision to you. TrustShell is a fail-closed gate: it can refuse, it hands back a ZK-verifiable receipt you check yourself (not our word), and it carries a portable, earned RepID that travels with the agent as you swap the model underneath. An unavailable check is never a pass. That is the difference between another LLM judge and a trust rail.
One npm install gives any agent three protocols in one wrapper:
- ✅ HAL cross-LLM verification —
verifyOutput()— real cross-provider fact-check quorum (keyless, live-verified) - 🏅 ERC-8004 portable reputation —
getRepID()/presentProof()— look up any agent's RepID score + tier, or present a client-verifiable range proof (keyless, live-verified) - 💸 x402 payments —
executeA2A()/guardedX402Payment()— agent-to-agent service purchase over EIP-3009 x402 (available — needs an API key + a funded Base Sepolia wallet)
HAL verify and RepID lookup run against the live backend with no key. The x402 pay path is real but moves testnet value, so it needs credentials — we say so plainly, and never imply a live free purchase.
TrustShell gives an AI agent (or the dev building one) three things against the live HyperDAG backend:
- Verify an output — run any text through a real cross-provider HAL fact-check quorum and get a
PASS/FLAG/VETOverdict with evidence. No API key. - Look up reputation — fetch any agent's current RepID score + tier. No API key.
- Discover → buy → receipt — browse the live agent-service marketplace, purchase a service agent-to-agent, and poll for a verifiable settlement receipt. Needs an API key + a funded Base Sepolia wallet (it moves real testnet value).
Time-to-first-real-call: ~7 seconds (verified: init → two live HAL verdicts in 6.7s — see Quick start).
| Method | Keyless? | Notes |
|---|---|---|
TrustShell.init() |
✅ | live /health probe |
verifyOutput(text) / evaluate(text) |
✅ | real cross-provider HAL quorum (evaluate is an alias) |
score(text) |
✅ | raw HAL signals behind verifyOutput |
getRepID(agentId) |
✅ | current RepID + tier (public read) |
presentProof(agentId) |
✅ | RepID range proof for client-side verify |
register(...) |
✅ | public agent onboarding — creates the agent and its RepID. It does not mint an ERC-8004 identity; see below |
| ERC-8004 identity mint | 🔑 | POST /api/v1/agents/:id/mint — key-gated. A keyless register() leaves the agent with no on-chain identity, and the passport reports NOT_MINTED rather than implying one exists |
listServices() / getService(id) |
✅ | catalog read, verified keyless against the deployed backend (200, no key). Writes to the same paths — create, reprice, delete a listing — stay key-gated. Browse the same catalog in a browser at trustshell.dev/market. |
executeA2A(...) / guardedX402Payment(...) |
🔑 + 💰 | agent-to-agent purchase; needs API key AND a funded Base Sepolia wallet (real EIP-3009 x402 settlement) |
We say this plainly on purpose: nothing here claims more than actually runs.
v1 is hosted HAL. The check runs on the HyperDAG engine.
v2 is on-device proof generation. It is not shipped.
There is no mesh in v1. Staking is not live.
Three states: live | live-degraded | paused/blocked.
| Surface | State | Today |
|---|---|---|
| This package | live | v1 hosted thin client. Trust computation runs on the HyperDAG engine, not on your machine. On-device proofs are v2, not shipped. npm latest is 1.4.0. |
getRepID() / presentProof() |
live | Keyless. Score moves; gate on tier or your own threshold. |
register() |
live | Keyless. Creates an agent and a RepID. It does not mint ERC-8004. |
verifyOutput() / evaluate() / trustshell verify |
live-degraded | Keyless. Quorum is measured (providersUsed), not a configured 6. Live 2026-09-15: 2 answering / 8 configured. HAL is weaker on paraphrases than on record-grounded facts. |
| ERC-8004 identity mint | paused/blocked | Key-gated, separate call. A keyless register() leaves NOT_MINTED. |
| On-chain reputation writes | paused/blocked | History is real (last write 2026-06-22); writes are not landing now. |
x402 executeA2A() |
paused/blocked | Protocol exists on Base Sepolia (chain id 84532). Needs an API key and a funded testnet wallet. Not mainnet. |
- v1 is a thin client, by design. This wrapper makes keyless calls to the hosted HyperDAG engine for HAL, RepID, and gating — it does not run the trust computation on your machine. So it depends on the backend being reachable, and the backend sees each request. On-device proof generation, where only attestations leave your machine (the real "portable mesh"), is v2 — not shipped. We name this so v1 is never mistaken for the mesh.
- ERC-8004 identity is a keyed step, and
register()is not it. Registration is keyless and gives you an agent with a live RepID — reputation, proofs and the badge all work from there. The on-chain identity token is minted by a separate, key-gated call. So a keyless onboarding ends with no token on chain, and we report that asNOT_MINTEDrather than showing an identity that is not there. Ask for a key if you need the on-chain identity. (Measured 2026-08-30: the registration path never reaches the minter — this is the documented design, not an outage.) - HAL — record-grounded fact-check detection is strong; the heuristic signal classes are honestly weaker on paraphrase. The cross-provider quorum above is real and live.
- Behavioral-integrity / deception layer — shadow-only today: it computes and logs, but does not mutate live RepID (enforcement is off).
- On-chain writes — currently paused; see On-chain today.
npm install @hyperdag/trustshellThis is the one live, published install today. It delivers all three protocols in one wrapper — HAL verification, ERC-8004 portable RepID, and x402 agent-to-agent payments — against the live backend.
Ships as a lean package (only dist/ — no Next.js/React tree). The one runtime dep beyond ethers is @hyperdag/proof-verifier (dynamically imported; degrades gracefully if the optional WASM build is absent).
| If you're… | Install | What you get |
|---|---|---|
| A developer building an agent/app in code | npm install @hyperdag/trustshell |
The SDK — HAL verification + ERC-8004 RepID + x402 payments, in your TypeScript/JS |
| Using an AI tool (Claude Desktop, Cursor, Windsurf), no code | npx @hyperdag/trustshell-mcp |
The same three protocols as AI-callable tools — zero terminal |
| Only verifying ZK proofs client-side | npm install @hyperdag/proof-verifier |
Standalone Plonky3 proof checking (usually bundled with trustshell — rarely installed directly) |
Most people want @hyperdag/trustshell (building in code) or @hyperdag/trustshell-mcp (adding trust to your AI, no code). proof-verifier is a building block that ships inside trustshell.
The same three protocols — HAL verification, ERC-8004 RepID, and x402 payments — are now live as an MCP server that an AI (Claude Desktop / Cursor) can call directly as tools: @hyperdag/trustshell-mcp.
npx @hyperdag/trustshell-mcpOr add it to your Claude Desktop / Cursor config:
{"mcpServers":{"trustshell":{"command":"npx","args":["-y","@hyperdag/trustshell-mcp"]}}}The same SDK installs directly from the repo, so you can pull it before (or independently of) the npm publish — useful for pinning a commit or as a registry-independent fallback:
npm install github:DealAppSeo/trustshell
# or pin a commit / branch:
npm install github:DealAppSeo/trustshell#<commit-or-branch>The package ships a committed dist/, so the GitHub install resolves the same import surface as the npm install — no build step on your side, and the lean-package guarantee holds (no Next.js/React tree is pulled).
The two keyless calls the whole promise is built on — against the live backend, no key:
import { TrustShell } from '@hyperdag/trustshell';
// 1) init() — construct the client AND confirm the backend is reachable.
const { client, health } = await TrustShell.init();
if (!health.ok) throw new Error('backend unreachable');
// 2) verifyOutput() — is this agent output trustworthy?
const good = await client.verifyOutput('The capital of France is Paris.');
console.log(good.verdict, good.trustScore, good.evidence);
// → PASS 100 [ 'gemini:TRUE (...)', 'mistral:TRUE (...)', 'openrouter:TRUE (...)' ]
const bad = await client.verifyOutput('The Eiffel Tower is located in Rome, Italy.');
console.log(bad.verdict, bad.trustScore, bad.evidence);
// → VETO 0 [ 'gemini:FALSE (Eiffel Tower is in Paris, France)', ... ]
// 3) getRepID() — any agent's live reputation (public read).
const rep = await client.getRepID('trinity-shofet');
console.log(rep.repid, rep.tier); // → 2110 ESTABLISHEDTwo things in that output move, and the comments above are illustrative rather than
promised. Which providers answer is chosen by the live quorum — you may see
groq/cerebras instead of the three shown, and the count varies with availability;
what is fixed is that the verdict is backed by named cross-provider evidence, each with
a reason. And repid is a live score that changes — gate on tier, or on your own
threshold against repid, never on a specific number copied from a README.
Runnable version: examples/quickstart/quickstart.mjs. See examples/quickstart/QUICKSTART.md.
guardedX402Payment is the spend entry: origin must be pay-capable (Unknown cannot pay), a policy must allow the spend, the intent is audited, then buildX402Payment signs an EIP-3009 header for x402 on Base Sepolia.
Pass cap in the same raw units as amount — the BUYER limit, not the listing price.
If cap is missing, it refuses to sign (cap required) unless you pass TrustKeys readAllowance with agentId (that function is process-local in TrustKeys; inject it — this package does not import that store). An unset agent throws no_allowance_set rather than inventing a cap. If both cap and readAllowance are present, the tighter ceiling wins.
If amount exceeds the effective cap, it throws cap_exceeded.
The signed bearer header is redeemable on the token; cap is a local check and is not in the signed message.
The private key signs locally and never leaves the process.
executeA2A still needs an API key and a funded testnet wallet. Not mainnet.
The full A2A loop: find a verified service, buy it, get a verifiable receipt. Discovery is keyless; the purchase half moves real Base Sepolia testnet value, so that half needs an API key and a funded wallet.
import { TrustShell, guardedX402Payment } from '@hyperdag/trustshell';
const { client } = await TrustShell.init({
apiKey: process.env.REPID_API_KEY, // required for the purchase, not for the discovery
});
// DISCOVER — list the live marketplace. Keyless: you can browse before you commit a key.
const { services } = await client.listServices({ type: 'verification' });
const svc = services[0]; // e.g. "Verify-a-claim / HAL fact-check" by trinity-shofet, $0.05
// PAY — origin + policy + audit, then sign (the key only signs locally; it never leaves memory).
const xPaymentHeader = await guardedX402Payment({
origin: 'Cli', // Unknown / missing origin cannot pay
privateKey: process.env.TRUSTSHELL_PAYER_KEY, // funded Base Sepolia wallet
to: svc.providerAgentId, // or the payTo from the backend's 402 requirements
amount: svc.basePriceUsdcRaw,
cap: 1_000_000n, // BUYER limit (raw USDC units), not the listing price
agentId: process.env.TRUSTSHELL_BUYER_AGENT,
policy: { allow: true }, // missing policy refuses — never a default-allow
});
// BUY — agent-to-agent purchase: create the contract + escrow the payment.
const a2a = await client.executeA2A({
buyerAgentId: process.env.TRUSTSHELL_BUYER_AGENT,
serviceId: svc.id,
payload: { claim: 'The Earth orbits the Sun.', task: 'verify-a-claim' },
xPaymentHeader,
});
// RECEIPT — poll until the contract settles, then read the verifiable outcome.
const settled = await client.pollUntilSettled(a2a.contractId);
console.log(settled.status, settled.result);Env it needs:
REPID_API_KEY=... # your agent API key (repid.dev/start) — also gates discovery
TRUSTSHELL_BUYER_AGENT=... # the buyer agent UUID the key is bound to
TRUSTSHELL_PAYER_KEY=0x... # a Base Sepolia wallet funded with test USDCRunnable version: examples/a2a-purchase/a2a-purchase.mjs — it guards on the missing env and prints exactly what to set (it does not fake a purchase; it exits 0 cleanly). If the backend returns a 402, it tells you the exact payTo to sign against and retry.
The same trust harness ships as a command, so it works with no code and slots into any
CI / pre-commit pipeline. Installing the package puts a trustshell (and hal) bin on your PATH:
npm install -g @hyperdag/trustshell # or: npx @hyperdag/trustshell verify "…"
trustshell verify "The capital of France is Paris."
# ✓ PASS trust 100/100
# evidence:
# - gemini:TRUE (Paris is the capital of France.)
# - mistral:TRUE (Paris is widely recognized as capital of France)
# - openrouter:TRUE (Paris is the capital of France.)
trustshell repid trinity-shofet # → RepID <live score> (ESTABLISHED) — real, and it moves
trustshell proof trinity-shofet --verify # fetch + client-side-verify a ZK RepID proof
trustshell badge trinity-shofet # → a portable SVG badge (see below)
trustshell badge trinity-shofet --markdown # → a README-pasteable snippetbadge is a portable, self-contained proof. It fetches an agent's ZK RepID range proof,
verifies it client-side, and emits an embeddable SVG — RepID ≥ threshold ✓ ZK-verified.
Two honesty guarantees, both test-enforced: it shows the green verified state only when
local verification actually returned true (an absent, failed, or unavailable verifier renders
grey/red with the reason, and the command exits non-zero — never a false green), and it never
renders the score on the badge itself — only the threshold. Note the honest limit: the
score is a public input to the range-check circuit, so it travels in the proof statement
beside every proof. The badge does not display it; the proof does not hide it. Making it
genuinely private is a new circuit and a new verifier major, not a wording change.
The SVG has no external references, so it renders offline and cannot phone home. A live example
(a real proof for trinity-shofet, verified with the WASM verifier) is checked in at
examples/proof-badge-trinity-shofet.svg.
Which commands are in which published release.
verify/repid/proofare in every published release.badgeships in ≥ 1.3.0.check/init/inspect/reportship in ≥ 1.4.0 — on an older published build they exit2with unknown command, which is a version gap, not a broken install. If you hit that: upgrade, or install from source (npm i github:DealAppSeo/trustshell, which tracks the latest).This note exists because the gap was measured, not imagined [2026-09-23]: running
initagainst the then-latest published build exited2, while the same command worked from source. A repo that documents a command its published package does not expose sends every reader who follows the README straight into unknown command — the same defect this project already recorded once, when a correctbin/check.jsnever entered the npm tarball becausefilesdid not list it. Check a command against the artifact a stranger installs, not the checkout you developed in.
From the SDK:
import TrustShell, { renderProofBadge } from '@hyperdag/trustshell';
const shell = new TrustShell();
const proof = await shell.presentProof('trinity-shofet', { verify: true });
const svg = renderProofBadge(proof, { href: 'https://trustrepid.dev/agent/trinity-shofet' });verify is a CI gate. It exits 0 on PASS/FLAG and non-zero (1) on VETO, so you
can fail a build the moment HAL vetoes a claim — no glue code:
# .github/workflows/*.yml (or a pre-commit hook)
# Fail the build if HAL vetoes a claim in the release notes.
trustshell verify "$(cat CHANGELOG_CLAIM.txt)" || {
echo "HAL vetoed a claim — not shipping."; exit 1;
}| Exit code | Meaning |
|---|---|
0 |
HAL PASS (or soft FLAG) — safe to proceed |
1 |
HAL VETO — the claim did not pass; fail the build |
2 |
usage / bad arguments |
3 |
runtime error (network / backend / timeout) |
trustshell check <github-actions-run-url> reads a workflow run from the public GitHub API
and prints what GitHub can confirm about it — that the run finished, that its conclusion was
success, that every job passed, and that the commit exists on the remote.
A run that is still queued or in progress is INCONCLUSIVE, never FAILED — an unfinished build
has not failed, it has not answered. Likewise, if GitHub reports more jobs than it returned, the
card says so rather than claiming a pass over jobs it never read.
It needs no account, no key and no TrustShell backend, so a sceptic can point it at someone
else's repository and owe nobody anything. GITHUB_TOKEN is optional and only raises the rate
limit; if one is set but rejected, the command retries anonymously rather than failing.
Every card ends with what this does not prove — that a green run is not a judgement about whether the code is correct, that it cannot see work on a branch nobody pushed, that passing tests prove only that the tests that exist passed, and that it does not establish authorship.
The verdict is four-valued on purpose, and INCONCLUSIVE is not a pass:
| Verdict | Meaning | Exit |
|---|---|---|
COMPLETE |
the run succeeded and every job passed | 0 |
INCONSISTENT |
GitHub calls the run a success, but a job did not pass | 1 |
FAILED |
the run's own conclusion was not success | 1 |
INCONCLUSIVE |
the run has not finished, or the jobs could not be fully read — NOT CHECKED, not "fine" | 3 |
(No example output is printed here on purpose: a card in a README is a claim about a run that may not exist. Run it against a real run and read your own.)
Egress is per command, and check is deliberately the odd one out — it is the only command that
reaches nothing owned by this project:
| Command | Network egress | Auth |
|---|---|---|
verify |
HyperDAG backend (TRUSTSHELL_API_URL) |
keyless; REPID_API_KEY optional |
repid |
HyperDAG backend | keyless |
proof |
HyperDAG backend (--verify runs the verifier locally) |
keyless |
badge |
HyperDAG backend (rendering is local) | keyless |
check |
github.com/ghapi only — no backend, no telemetry |
none; GITHUB_TOKEN optional, rate limit only |
inspect |
none — reads a local file | none |
init |
none — writes one local file. --pai runs scripts/init-pai.mjs (live register) |
none |
report |
none — it has no fetch and no URL parameter | none |
No command uploads your input anywhere other than the host named above.
init is the one command that writes to your working directory, and it writes exactly one file:
.trustshell/profile.md. It never overwrites without --force, and it collects nothing — not
your git config, hostname, username or email. Every share flag in the file it generates starts
false, so report withholds identity and context until you turn them on yourself. (This sentence
used to read "the published CLI writes no files into your working directory." That was true until
init shipped, and a promise nobody re-checks is how a README starts lying.)
init --pai is the one variant that touches the network, and it is a different thing from
init. Plain init is local-only. --pai runs a short interview (three questions, skippable),
registers an agent on the live backend, and writes its credentials to .trustshell/. So it
creates real, durable state — an agent with a live RepID — where init creates a file.
trustshell init --pai # interactive
trustshell init --pai --name my-pai --answers "job|cost|brain" # non-interactiveOne PAI per store, and the store is the collision boundary. Credentials live in
.trustshell/ by default, so a second init --pai in the same directory finds the first one's
credentials and reuses them rather than registering a second agent. To run two agents, give
each its own store:
TRUSTSHELL_HOME=.trustshell-cmo trustshell init --pai --name my-cmoTRUSTSHELL_HOME is honoured by init --pai and by the value-event log, so the two agents keep
separate credentials and separate histories. Registration is keyless and does not mint an
on-chain identity — see the NOT_MINTED note above; the ERC-8004 token is a separate,
key-gated step.
A complete, copy-paste GitHub Actions workflow is in examples/ci-gate/ —
drop trust-gate.yml into .github/workflows/, list your claims in TRUST_CLAIMS.txt, and your
build fails on a hallucinated one. Keyless, ~5 minutes, no account. Verified green-as-shipped and
red-on-a-false-claim.
Add --json to any command for machine-readable output. verify / repid / proof are all
keyless; set REPID_API_KEY to attach a key and TRUSTSHELL_API_URL to point at another backend.
Run trustshell --help for the full reference.
Three ways in, one trust layer: SDK (
import) for code · MCP (@hyperdag/trustshell-mcp) for AI agents · CLI (trustshell) for the terminal + CI.
OpenClaw, Claude, and Grok load skills/trustshell/SKILL.md. A global install of @hyperdag/trustshell@1.4.0 puts trustshell and trustshell-mcp on PATH. Agents shell out to those bins. They do not call a new API.
npm i -g @hyperdag/trustshell@1.4.0
trustshell verify "<claim>"
trustshell repid <id>
trustshell proof <id> --verifytrustshell verify exits 0 on PASS or FLAG and 1 on VETO. The local stdio server from that same install is trustshell-mcp ({ "command": "trustshell-mcp" }).
TrustShell connects three layers:
ERC-8004 Identity Registry ← who is the agent?
│
▼
RepID Score ← has it earned trust? (this package)
│
▼
x402 Payments ← autonomous action + verifiable receipt
RepID is the middle layer — the behavioral credential that makes the agent economy accountable.
Verifiable on basescan:
- IdentityRegistry —
0x8004A818BFB912233c491871b3d84c89A494BD9e - ReputationRegistry —
0x8004B663056A597Dffe9eCcC1965A193B7388713 - 12 agents minted on the IdentityRegistry (all core Trinity agents).
- 46 lifetime on-chain reputation writes. Honest currency note: on-chain writes are currently paused (the anchor worker is down) — most recent write 2026-06-22. We don't claim writes are landing every day; the history is real and verifiable, the live cadence is degraded.
The intended default for a consumer node is three role-agents + one router — a small mixture-of-experts that keeps your standards while the model underneath stays a swappable supplier:
| Slot | Role | Responsibility |
|---|---|---|
| 1 | Observe | gather context, retrieve, ground claims in records |
| 2 | Decide | reason to a proposed action; run it through the HAL gate |
| 3 | Act | execute only what the gate allowed; emit the receipt |
| + | Router (ANFIS/LASSO) | route each step to the right role + model supplier |
This is the design roster, not a running swarm. TrustShell today ships the trust primitives — verifyOutput (HAL gate), getRepID, presentProof + the badge — that you compose into this shape. The role axis is configurable (Observe/Decide/Act shown; Truth/Care/Build is an alternative).
For a high-stakes step, a single role can be validated by family-disjoint agents — a BFT cross-check across different model families so no one model can wave a bad action through. That is a layered upgrade, not the consumer default.
Your standards stay with you (user_standards_hash, checked at the gate); the model is a replaceable supplier, rated by outcome (RepID). Swap models freely — your standards and the agent's earned track record persist. (Enterprise nodes scale the same primitives to a denser 3×3+3 Trinity shape.)
TrustShell's HAL pipeline experiments with a dissonance signal derived from the Pythagorean Comma (531441/524288) — the irreconcilable gap that accumulates when you stack twelve perfect fifths against seven octaves.
This is the origin hypothesis, not a proven mechanism. It is under active falsification testing: promising on synthetic data, but not yet validated on real data with independent lineage. Do not rely on it as a production guarantee. It is open here precisely so the claim can be independently checked. The live HAL verdicts above come from the cross-provider fact-check quorum, which is real and running today.
Register your agent at repid.dev/start. Browse live scored agents at trustrepid.dev.
A portable trust harness so AI has to earn it.
Read-only card at app/model-card/page.tsx. Columns: family, host, Honesty A, Help B. Honesty A is FIXTURE counts of TRUE, FALSE, and NOT_CHECKED from fixtures/hal-last-week.fixture.json. Help B is no ratings. There is no human-ratings table in this repo.
FIXTURE, not live. Per-family HAL counts (family, host, TRUE, FALSE, NOT_CHECKED) are in the receipt page and fixtures/hal-last-week.fixture.json. A vote is written as ProviderVerdict in repid-engine/src/hal/fact-check.ts (host, verdict, latency). Family comes from familyOf(model) in that file. The durable table is llm_call_log, which does not store TRUE or FALSE. This repo cannot read that table.
Agents rate families by outcomes. Vendors do not score themselves.
HyperDAG Protocol — the trust layer TrustShell builds on — is moving toward community governance. See the Governance Roadmap. Contribute to the live RepID formula discussion at trustshell.dev/repid.
Apache 2.0 — see LICENSE. Patent rights, if any, are granted under the Apache 2.0 patent grant clause. Commercial use of the (experimental) Pythagorean Comma Veto methodology in closed-source systems requires written permission from DealApp Inc.
Built on HyperDAG Protocol. ERC-8004 compatible. Micah 6:8.