Developer Quickstart

// PACKAGES

What each package gives you

Benefit first. Pick by what you're building — each is an independent install.

@moltrust/sdk

Use it when you want to gate agents at your API — Express / Hono / Fastify: verify(), register(). Pulls in @moltrust/aae.

bash

npm install @moltrust/sdk

@moltrust/verify

Use it when you want to verify credentials offline — W3C VC + IPR against Base L2. No MolTrust API key.

bash

npm install @moltrust/verify

@moltrust/x402 · @moltrust/mpp

Use them when you want to gate paid endpoints — x402 payments, or MPP (Stripe / Tempo / Visa). Same requireScore() shape.

bash

npm install @moltrust/x402 # or @moltrust/mpp

Payment middleware →

@moltrust/aae

Use it when you want to author or validate an AAE — schema + runtime validator. Already pulled in by the SDK.

bash

npm install @moltrust/aae

@moltrust/agent-firewall

Use it when you want to react when trust changes post-onboarding — CAEP Profile v1 event-reactive layer.

bash

npm install @moltrust/agent-firewall

How it reacts →

moltrust-enforce Python

Use it when you want to check a transaction against a signed mandate before your agent acts — and recompute the answer yourself instead of trusting ours.

bash

pip install moltrust-enforce

Quickstart →

@moltrust/openclaw · moltrust-mcp-server

Use them for an agent runtime (OpenClaw plugin) or an MCP client (Claude, etc., PyPI).

bash

openclaw plugins install @moltrust/openclaw

@moltrust/verify and @moltrust/agent-firewall are standalone consumer libraries — no MolTrust API key. @moltrust/sdk declares @moltrust/aae as a dependency, so installing the SDK pulls AAE in automatically.

Runtime enforcement — `moltrust-enforce`

A Python client that answers one question before your agent acts: does this transaction fall inside the mandate its principal signed? The answer is PERMIT, DENY or PENDING. It runs on your side, inside your own agent runtime — no decorator, no framework hook, you decide where the call goes.

The verdict depends on the mandate and the transaction, nothing else — no server state, no clock, no database. That is what makes the second call worth having: check() asks us, verify() recomputes the same verdict on your machine and compares. A hash that a party can recompute for itself (a digest — a short fingerprint of the inputs) is what turns our answer into something you can audit rather than accept. If the two disagree, you hear about it.

Fail-closed throughout: an unreachable server, an error status or an unreadable answer all come back as DENY. Nothing here turns a failed check into permission.

The key is the same one the rest of this page uses — grab a free one above if you have not already. /enforce/check authenticates exactly like /vc/aae/evaluate.

python
# pip install moltrust-enforce   (Python 3.10+)
from moltrust_enforce import EnforceClient, action_digest

client = EnforceClient("https://api.moltrust.ch", api_key=API_KEY)

# The action the mandate binds to, and the transaction you are about to run.
action = {"verb": "transfer", "asset": "USDC", "chain": "base"}
mandate = {
    "grants": [{
        "action_binding": action_digest(action),
        "type_fields": ["verb", "asset", "chain"],
        "disposition": "allow",
        "constraints": [
            {"type": "exact", "field": "to", "value": TREASURY_ADDRESS},
            {"type": "range", "field": "amount", "lo": 0, "hi": 50000},
        ],
    }],
}
transaction = {"action": action, "to": TREASURY_ADDRESS, "amount": 12500}

verdict = client.check(mandate, transaction)      # PERMIT | DENY | PENDING

if not verdict.permitted:
    log.warning("blocked: %s (%s)", verdict.verdict, verdict.reason)
    return

# It said yes — so recompute it yourself before acting on it.
# No network, no server state: same inputs, same answer.
result = client.verify(verdict, mandate, transaction)
if not result.ok:
    raise RuntimeError(result.mismatches)   # the answer does not follow from your inputs

execute(transaction)

exact

Full equality on a field. No prefix, no case-folding — a vanity address sharing the first characters is denied.

enum

Membership in a listed set, each member compared in full.

range

Closed integer interval, lo and hi included. Floats are rejected — they break recomputability.

A PERMIT requires a grant whose action_binding matches, all its constraints holding, and disposition: "allow". An action no grant addresses is denied, never held. PENDING comes only from an explicit "hold", and the client never resolves it for you. Every verdict carries a per-predicate trace: which check ran, on what value, against which bound. PyPI → · Source →

Payment middleware — x402 & MPP

One line gates a paid endpoint by trust score. Same requireScore() API for both @moltrust/x402 (x402 payments) and @moltrust/mpp (MPP — Stripe / Tempo / Visa). Untrusted agents get a 403 before they transact.

javascript

// npm install @moltrust/x402   (or @moltrust/mpp — same shape)
const { requireScore } = require('@moltrust/x402');
app.use(requireScore({ minScore: 60 }));

// req.moltrust available downstream
app.post('/api/data', requireScore({ minScore: 50 }), (req, res) => {
  const { wallet, score } = req.moltrust;
  res.json({ message: 'Welcome, score ' + score });
});

1. Extract

Wallet from the x402 / MPP payment header.

2. Score

MolTrust trust score (5-min cache, <10ms warm).

3. Gate

403 + registration link if below threshold.

Every x402 wallet also gets an automatic Wallet Trust Profile (shadow score, history, projected score after registration): GET https://api.moltrust.ch/wallet/{address} · public page /wallet/{address}.

// DEPLOYMENT MODES

Two ways to carry the evidence

Same identity, same mandate, same MoltProof. What differs is where the proof lives — and how strong the claim is.

Anchored · Base L2 · default

Anchored

Every record is anchored on the public chain and recomputable by anyone, for years. The proof stands on the chain — no trust in us required. Default for global on-chain agents.

Attested · API-only · the weaker claim

Attested

No blockchain, no VPN — for regulated markets (China, India) and OpenClaw deployments without chain access. Records are verifiable against MolTrust's signed log, not recomputable from the public chain; you're trusting our signature. It is the weaker guarantee — use it where the chain isn't reachable.

// GO DEEPER

Protocol internals

Not needed to start. Open a topic when you want it.

Trust scoring — why a fresh agent starts at null, not 0

A freshly registered agent does not start at a fixed grade. Until it has at least three endorsements, its score is withheld — GET /skill/trust-score/{did} reports it as null, not 0. That is the expected starting state, not an error. Grades run S / A / B / C / D / F over a 0–100 score.

Agent Authorization Envelope (AAE) — the mandate that gets proven later

AAE is configured via POST /delegation/configure after registration — a machine-readable permission contract your API can inspect. The credential from /identity/register does not embed it.

📜 MANDATE

Purpose & allowed actions
Denied actions
Target resources
Delegation rules

🔒 CONSTRAINTS

Time bounds & TTL
Financial thresholds
Autonomous: < $100 · Step-up: $100–$10,000 · Human approval: > $10,000
Jurisdictions
Counterparty min score

✅ VALIDITY

Issuer DID
Holder binding
Expiry timestamp
Revocation endpoint
Base L2 anchor

Protocol Whitepaper v0.8 → · did:moltrust Method Specification →

IPR / Evidence — what a MoltProof is under the hood (Interaction Proof Records, Merkle-batched on Base L2)

Under the hood, a MoltProof is an Interaction Proof Record (IPR). Every agent action can produce one — IPRs are Merkle-batched and anchored on Base L2.

POST /vc/ipr/submit

Submit an IPR. Provide output_hash (SHA-256), agent_did, and confidence score. Returns ipr_id.

GET /vc/ipr/{ipr_id}

Retrieve an IPR by ID. Returns output_hash, anchor status, Merkle proof, and Base L2 transaction hash.

POST /vc/ipr/verify

Verify an IPR: checks signature, on-chain anchor, and Merkle proof. Returns validity + anchor TX link.

GET /vc/ipr/agent/{did}

List all IPRs for an agent. Paginated. Returns proof records with anchor status and Merkle proofs.

GET /vc/ipr/stats

Network-wide IPR statistics: total records, anchored count, unique agents, average confidence score.

GET /vc/ipr/{ipr_id}/status

Anchor status of a specific IPR: pending, anchored, or failed. Includes retry count and block number.

Anchor commitment scheme — how the 32 bytes on Base L2 are derived, and how to recompute them

“Anchored on Base L2” is only worth something if you can check it without us. This is the whole encoding: what goes into a leaf, how the tree is built, and what ends up in the transaction.

The transaction

An anchor is a zero-value self-send — the anchoring address sends 0 wei to itself and the payload is the entire input field. No contract, no event, no storage. The calldata is ASCII, UTF-8 encoded, with no ABI wrapper:

calldata

MolTrust/VC/v1/<merkle root, 64 lowercase hex>    ← credentials
MolTrust/IPR/v1/<merkle root, 64 lowercase hex>   ← interaction proof records

The first four bytes of a credential anchor are 0x4d6f6c54. That is the letters MolT, not a function selector.

The leaf

SHA-256 over five fields joined by |, with no spaces and no trailing separator:

preimage

cred_id | subject_did | credential_type | issued_at | proof_value

From the credential document you hold, that is evidence[0].credentialId, credentialSubject.id, the entry of type[] that is not VerifiableCredential, proof.created with its UTC designator removed (a trailing Z, or +00:00), and proof.proofValue.

Read the timestamp from proof.created rather than the top level. Credentials exist under both W3C data model versions, which name that field validFrom and issuanceDate respectively; proof.created is in both.

The tree

Plain binary SHA-256 over the raw 32-byte digests — no domain separation, no sorted pairs, no length prefix. Leaves are ordered oldest first. If the number of leaves is odd, the last leaf is duplicated before anything else, so a one-credential batch is two leaves and its root is SHA-256(leaf || leaf), never the leaf itself. Each level above is padded the same way, and a parent is SHA-256(left || right).

A worked example you can recompute

Transaction 0xa5f77cb7…, block 51 604 928, three credentials — odd, so the padding is visible:

recompute

leaf[0] = bd782c2568457dd171630014937b667d8415586fb5a250dd354a2eb835a630f7
leaf[1] = 2e35f4aad10cb50470d5823b114fd111556bc8c91fa2cf8fa42e6a7007a14d18
leaf[2] = 9b6dc108ffd807e001d5fc9500257515f4da0975bac52e72c1c5e2d619697b50
leaf[3] = leaf[2]                                          (padding)

SHA-256(leaf[0] || leaf[1]) = f90582cfc740d07d34fc6da4c4756e9b8ab8eb4d542a7284f50d613eb265093d
SHA-256(leaf[2] || leaf[2]) = 30f6cd9ebb0096346a01242fc109505dba5587aa5fbe105951e9559428ef6733
SHA-256(f90582…  || 30f6cd…) = fa5abbd0d3beaad1af343ea8d31b222b83bbde352b88443b89310933ff9ba658

calldata = MolTrust/VC/v1/fa5abbd0d3beaad1af343ea8d31b222b83bbde352b88443b89310933ff9ba658

Or just run it

verify_anchor.py is the same thing in 140 lines. It imports nothing from our codebase, needs no API key, and reads a public RPC endpoint:

bash

python3 verify_anchor.py credential.json

Full specification, including the interaction-proof-record variant and the edge cases: anchor-commitment.md.

What this does and does not establish

A matching root proves these exact field values existed no later than the block that carried them. Change one character anywhere and the leaf, the root and the calldata all stop agreeing. It says nothing about whether the claim in the credential is true, whether the signature over it verifies, or whether it has since been revoked — those are separate checks, and all of them have to pass. Nor does the chain enumerate what was never anchored: an unanchored credential is unanchored, not refuted.

Registering more than two agents — the keyless path

Email signup is rate limited to two new agents per /24 per 24 hours. That is deliberate — an address and a network are cheap to acquire, so they are what the Sybil cost is priced against. It also means a CI runner, a corporate NAT or a single cloud region runs out after two.

The keyless path is gated by proof-of-work instead of by your network, so it does not care how many agents share an address. Three calls, no account, no email:

GET /identity/register-challenge

Returns a challenge string and a proof-of-work seed with its difficulty in bits. Free.

POST /identity/register-pop

Generate an Ed25519 keypair, solve the proof-of-work, sign the challenge, post the four values. Returns a did:moltrust: and a signed credential. Currently 18 bits — a fraction of a second.

public_key is the raw 32-byte Ed25519 key as 64 hex characters, upper or lower case, stored lower case. Base64, base58, multibase and a 0x prefix are all rejected — the 422 names the encoding it wanted.

POST /auth/signup-did

Binds an API key to that DID, using the same keypair and proof. Without this step the DID has nothing to authenticate with, and paid endpoints answer 401.

Skill verification — audit a skill before you install it

Ten versioned checks over a SKILL.md, each mapped to a CWE identifier with a stated deduction. The check list and its version are public, so a verdict can be reproduced later rather than taken on trust.

Where the line runs: finding out about your own skills is free — audit, verify, read the check list. Showing a third party a signed credential is what you pay for.

GET /guard/skill/audit?url=<repo>

Free, no API key, 5 per hour per IP. Returns score, findings, canonical skill hash and auditor version. Add &profile=claude_skill for Claude Agent Skills. 404 means the repository has no SKILL.md.

GET /guard/audit/checks

Free. Every check with severity, deduction and CWE reference. GET /guard/audit/version returns the version and checksum the verdict was produced under.

GET /guard/skill/verify/{skillHash}

Free. Resolve a previously issued credential by the canonical hash of the skill file.

POST /guard/vc/skill/issue

Paid — 5 USDC via x402. Issues a signed, on-chain-anchored VerifiedSkillCredential. This is the gate-use half: a verdict you hand to someone else.

Sequential Action Safety (SAS) — pre-execution check for order-sensitive sequences

Pre-execution safety check for order-sensitive action sequences. Opt-in, deterministic, no LLM calls. Phase 1: WARN-only.

POST /guard/api/action/check

Check a proposed action against the session history. Returns verdict (SAFE/WARN/BLOCK), residual score, and conflicting action.

GET /guard/api/action/stats

Aggregated SAS statistics: total events, breakdown by verdict, average residual.

GET /guard/api/action/events/{did}

SAS events for a specific DID. Shows all WARN/BLOCK events with residual scores and conflicting actions.

Kernel-level enforcement (Falco) — syscall-level, not bypassable from userspace

MolTrust supports a third enforcement layer via Falco eBPF — syscall-level monitoring that agents cannot bypass from userspace.

Layer 1 — Cryptographic

Ed25519 signatures, JCS canonicalization. Tamper-proof by construction.

Layer 2 — API

Trust score degradation, IPR submission, credential revocation.

Layer 3 — Kernel

Falco eBPF/syscall detection. Not bypassable by the agent process.

When a policy violation is detected at the kernel level, Falco fires a webhook to the MolTrust bridge, which submits an IPR violation record — trust score degrades automatically. Reference implementation →

Agent Firewall / CAEP — react in real time when a counterparty's trust changes

Identity plus a one-time score check isn't enough: a counterparty you onboarded yesterday can be revoked or downgraded today. @moltrust/agent-firewall polls the registry's CAEP Profile v1 and fires typed events on trust-score changes and revocations, with the new score verified end-to-end (JCS + Ed25519) before your handler runs.

GET /caep/pending/{did}

Cursor-based pending events. Rate limit 120 polls/h per DID (30 s interval, server-enforced).

POST /caep/acknowledge/{event_id}

Idempotent soft-ack, 90-day retention.

GET /.well-known/registry-key.json

Ed25519 JWK for signature verification.

GET /skill/trust-score/{did}

Signed score payload (JCS + Ed25519, kid moltrust-registry-2026-v1).

javascript

# 1 — install
npm install @moltrust/agent-firewall

// 2 — instantiate, watching the counterparties you depend on
import { MoltrustCaepClient } from '@moltrust/agent-firewall';
const fw = new MoltrustCaepClient({ watch: ['did:moltrust:<counterparty>'] });

// 3 — react: re-gate on score drop, block on revocation
fw.on('trust_score_change', (s) => regate(s.did, s.score));
fw.on('did_revoked', (did) => block(did));
await fw.start();

Polling-only (CAEP Profile v1, proprietary — not OpenID SET). Page size: server default limit=50 (max 500). Typed handlers fire only for cryptographically-verified events by default.

Show your trust score — a live README badge

One line in your README. The badge fetches your live trust score automatically.

markdown

[![MolTrust Verified](https://api.moltrust.ch/badge/YOUR_DID)](https://moltrust.ch)

Live preview:

// A2A SELF-ONBOARDING

Your agent onboards itself

Your agent discovers, registers, and gets its credentials — without you in the loop. Point it at our agent-card and walk away. Every path below is verified live against the MolTrust API v1.

bash

# 0 — Get an API key (one-time): POST https://api.moltrust.ch/auth/signup
#     Reference: https://api.moltrust.ch/docs
export MOLTRUST_API_KEY=<your key>

# 1 — Discover the registry's capabilities (public, no key)
curl -s https://api.moltrust.ch/.well-known/agent-card.json

# 2 — Register (needs X-API-Key). Returns a full signed AgentTrustCredential + 100 credits.
#     Costs no credits; trust score is withheld until the agent has >=3 endorsements.
curl -s -X POST https://api.moltrust.ch/identity/register \
  -H "X-API-Key: $MOLTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","description":"autonomous buyer"}'

# 3 — Inspect your own extended agent-card (use the did from step 2)
curl -s https://api.moltrust.ch/a2a/agent-card/did:moltrust:YOUR_DID

# 4 — Subscribe to trust events for any counterparty (CAEP polling, 120/h per DID)
npm install @moltrust/agent-firewall

# 5 — Sign downstream requests so counterparties can verify you
curl https://partner.example/resource \
  -H "X-MolTrust-DID: did:moltrust:YOUR_DID"

did:moltrust is the only supported DID method today; did:web and did:key are not accepted. You bring no key material in advance — POST /identity/register provisions your identifier and its Ed25519 signing key, publishes the public key in your DID document, and anchors it on Base L2.

// TRACK RECORD

How an agent qualifies without endorsements

A trust score is withheld until an agent has three endorsements, and an agent that registered this morning has none. A gate reading the score denies it, which is correct — a score nobody has computed is not a low score. It also leaves a new agent with nothing to present. A track record is what it can present instead: one credential stating what a wallet it controls has done on Base.

bash

# 1 — Bind a wallet you control. The nonce is short-lived; sign it with the wallet.
curl -s "https://api.moltrust.ch/identity/nonce?did=did:moltrust:YOUR_DID"

curl -s -X POST https://api.moltrust.ch/identity/bind \
  -H "Content-Type: application/json" \
  -d '{"did":"did:moltrust:YOUR_DID",
       "wallet_address":"0xYOUR_WALLET",
       "wallet_chain":"base",
       "wallet_signature":"0x...",
       "nonce":"<from the call above>"}'

# 2 — Issue the track record. First one per DID is free.
curl -s -X POST https://api.moltrust.ch/credentials/track-record \
  -H "X-API-Key: $MOLTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"did":"did:moltrust:YOUR_DID"}'

# 3 — Read it back. track_record appears in gate_attestation once anchored.
curl -s https://api.moltrust.ch/skill/trust-score/did:moltrust:YOUR_DID

What the wallet has to show

Two thresholds, both published here because a threshold that moves quietly is not one you can rely on:

`nonce ≥ 1`	the wallet has sent at least one transaction of its own
`age ≥ 7 days`	measured from its first transaction on Base
`chain = base`	the history is read on Base and the credential is anchored there

Neither threshold is a quality bar. They are a cost: a wallet that has sent a transaction and is a week old cannot be produced at the moment someone wants a discount. The first one is the one that catches people out — most agent marketplaces relay transactions gaslessly, so a wallet can have worked for weeks and still sit at nonce 0. Sending one transaction yourself is what clears it.

The credential carries the measured numbers — transactions sent, age in days, transfer count, USDC volume — next to the thresholds they were judged against, so a verifier can redo the judgement from the credential without asking us what the rule was that day.

What it does at a gate

A gate built on @moltrust/x402 or moltrust_enforce can accept a track record in place of a score it has never been given. The option is allowTrackRecord and it is off by default, so an existing gate keeps the behaviour its operator configured. MoltGuard has it on: 20 % off at score ≥ 50, or with an anchored track record.

Proof

A recorded run of the whole path, with the anchor transaction, both 402 amounts and the settled payment: gate proof, 2026-09-23 → — anchored in 0xf207a648…a5adc, Base block 51674415.

What that run does not show, stated there and repeated here. It shows that the path is walkable; it does not show that anyone wants to walk it — the caller was us, the endpoint is ours, and the 0.04 USDC went from our test wallet to our own payTo. The wallet cleared the age threshold with one day to spare, eight days against a threshold of seven. And the anchor was triggered by hand instead of waited for, so the run finished in one piece; in normal operation the batch runs every two hours and the wait is real.

Three things worth knowing before you rely on it. A track record stands in for a score nobody computed, never for one that was computed and came out low. It reaches the attestation only after the anchoring batch has run, which happens every two hours — anchor_tx is the field a relying party checks, and it cannot be filled in before the transaction exists. And the anchor is not confirmed in the request path: the signature over the attestation already covers those bytes, so a host that wants the chain checked as well reads anchor_tx and does it on its own schedule.

Option	Type	Default	Description
minScore	number	0	Minimum trust score required to pass verification. Agents below this threshold receive a 403.
requireAAE	boolean	false	Require a valid Agent Authorization Envelope in the credential. Rejects agents without one.
evaluateAction	string	—	Check whether the AAE mandate permits this specific action (e.g. "purchase", "transfer").
evaluateAmount	number	—	Evaluate AAE financial constraints against this transaction amount (USD).
evaluateJurisdiction	string	—	Verify the AAE permits operations in this ISO 3166-1 jurisdiction code.
apiBase	string	api.moltrust.ch	Override the MolTrust API base URL. Useful for staging or self-hosted deployments.

Build agents that can prove what they did.

Identity + mandate

The record

Verify

Verify an agent in 2 minutes

Get a free API key

Register your agent

Read a live trust score — the result

Drop it into your stack

Node — Express / Hono / Fastify

CrewAI

LangChain 1.x

Google ADK ⚠️ Experimental

OpenClaw

MCP (Claude, etc.)

Node adapters

Python agent frameworks

CrewAI

LangChain 1.x

Google ADK ⚠️ Experimental

What each package gives you

@moltrust/sdk

@moltrust/verify

@moltrust/x402 · @moltrust/mpp

@moltrust/aae

@moltrust/agent-firewall

moltrust-enforce Python

@moltrust/openclaw · moltrust-mcp-server

Runtime enforcement — moltrust-enforce

Payment middleware — x402 & MPP

Two ways to carry the evidence

Anchored

Attested

Protocol internals

📜 MANDATE

🔒 CONSTRAINTS

✅ VALIDITY

The transaction

The leaf

The tree

A worked example you can recompute

Or just run it

What this does and does not establish

Your agent onboards itself

How an agent qualifies without endorsements

What the wallet has to show

What it does at a gate

Proof

API reference

VerifyOptions

AgentVerification interface

@moltrust/sdk

@moltrust/x402

@moltrust/mpp

@moltrust/verify

@moltrust/aae

moltrust-mcp-server

@moltrust/openclaw v1.0.0

@moltrust/agent-firewall v1.0.0

Protocol WP v0.8

API Reference

OpenAPI 3.1

did:moltrust

Get your free API key.

Building for China or India?

Chinese Developer Guide

Runtime enforcement — `moltrust-enforce`