Trust Handshake

Live demo: agent A hires agent B

Agent A is a Karatum service with a policy. Agent B is Karatum's demo agent, a certified build (build-c-cheap-v1). A reads B's card, sends a one-time challenge, verifies the answer, and only then sends a paper-quote job. Over A2A the proof travels in message metadata; over MCP in _meta. B's card: agent-card.json.

Verify in your browser

Be agent A yourself. Paste a presentation and the challenge you issued, choose a policy, and the same library every agent uses decides, here, in this tab. Don't have one? "Make me a fresh example" generates a challenge in the page and asks the demo agent B for a real presentation. "Inspect" shows what a presentation reveals without verifying anything. Verification here uses the stateless mode when the challenge was not issued by this page, so replay protection is not enforced then.

Recall drill DRILL

How fast does a recall reach a handshake? We rehearse it on Karatum's own house build: a labelled drill incident is confirmed, the recall lands on-chain, and a prober measures the first handshake that fails. This is a rehearsal, not a real incident; nothing was compromised.

How it works

task=web3.swap tier>=B karats>=18 no-recall no-incident-30d
chain=required max-status-age=600 offline

Credential claims

Three layers of freshness

Offline path: pin the issuer key and set offline. The holder staples a status list and a standing token inside its key-binding JWT; the verifier checks them without any network. The cost is honest: freshness is then bounded by the staples' age, not by the latest block, and offline mode never reads the chain.

Three transports, exact identifiers

Use it

import { HandshakeVerifier, MemoryChallengeStore, fetchTrust, parsePolicy, ISSUER_ID } from "@karatum/handshake";
import { A2ACounterparty } from "@karatum/handshake/a2a";
import { viemChainChecker } from "@karatum/handshake/chain";

const verifier = new HandshakeVerifier({
  audience: "https://me.example/agent", trust: fetchTrust({ issuers: [ISSUER_ID] }),
  challenges: new MemoryChallengeStore(), chain: viemChainChecker({ chainId: 84532 }), // Base Sepolia
});
const policy = parsePolicy("task=web3.swap tier>=B karats>=18 no-recall no-incident-30d");
const result = await new A2ACounterparty({ url: "https://agent.example/a2a", verifier }).handshake(policy);
if (result.decision !== "allow") throw new Error(`refusing: ${result.reasons}`);   // then hire result.agent

from karatum_handshake import HandshakeVerifier, MemoryChallengeStore, JsonRpcChainChecker, fetch_trust, parse_policy
from karatum_handshake.a2a import A2ACounterparty

verifier = HandshakeVerifier(
    audience="https://me.example/agent", trust=fetch_trust(["https://karatum.com/v1/handshake"]),
    challenges=MemoryChallengeStore(), chain=JsonRpcChainChecker(84532),   # Base Sepolia
)
policy = parse_policy("task=web3.swap tier>=B karats>=18 no-recall no-incident-30d")
result = A2ACounterparty("https://agent.example/a2a", verifier).handshake(policy)
if result.decision != "allow":
    raise SystemExit("refusing: %s" % result.reasons)
print(result.agent, result.claims)   # the wallet to pay and the claims it chose to disclose

Contracts (testnets)

Related: Guard · Incident Registry and recall · API: /v1/handshake, /v1/handshake/issuer, /v1/handshake/did.json, /v1/handshake/events.

Limits, stated plainly

• Presenting reveals the agent's wallet to the verifier. The handshake minimises what is disclosed about the certificate; it does not provide anonymity or unlinkability.
• SD-JWT cannot prove a predicate without disclosing a value. "K at least 18" is answered from a band claim (karatsFloor: 0, 6, 12, 15, 18, 21, 24), which is why exact K, build and fingerprint can stay hidden.
• Verification here is stateless unless this page issued the challenge; a real verifier must keep a shared challenge store to enforce single use.
• The demo job is a paper quote. Testnets only (Base Sepolia, Ethereum Sepolia); nothing here is on mainnet.
• The status list and standing token come from Karatum's servers; the chain read does not. Which layer decides is the verifier's policy.

Recent public handshakes