hanko-cli

Hanko — the Solana Agent Trust Registry CLI. Register your agent, post attestations, verify trust from the terminal or CI.

Trust is stamped, not claimed.

hanko-cli is the command-line client for the Hanko network — an ERC-8004 port to Solana that adds Identity, Reputation, and Validation registries plus Stake/Slash, a Karma score, and an x402 middleware. The CLI wraps every on-chain instruction and every backend endpoint the network exposes.

Install

npm install -g hanko-cli
hanko --version

Node.js 18.17+ required. A Solana keypair at ~/.config/solana/id.json is picked up automatically; pass --keypair <path> to override.

Configuration

hanko reads ~/.hanko/config.json (created on first hanko config set) merged over sensible mainnet defaults. Every value can also be provided via HANKO_* environment variables — handy in CI.

hanko config show
hanko config set apiUrl https://api.hanko.network
hanko config set cluster mainnet-beta
hanko config set programId <PROGRAM_ID>

| Key | Default | Env | | ----------- | ----------------------------------------- | ----------------- | | apiUrl | https://api.hanko.network | HANKO_API_URL | | rpcUrl | https://api.mainnet-beta.solana.com | HANKO_RPC_URL | | programId | (set after Anchor mainnet deploy) | HANKO_PROGRAM_ID| | keypair | ~/.config/solana/id.json | HANKO_KEYPAIR | | cluster | mainnet-beta | HANKO_CLUSTER |

Commands

hanko register

Register a new agent — bond deposit + Identity Registry PDA.

hanko register \
  --agentcard https://agent.example.com/.well-known/agent-card.json \
  --domain agent.example.com \
  --bond 1.5sol

The CLI fetches the AgentCard, validates the A2A schema, asks for confirmation, and sends register_agent. It prints the transaction signature, a Solana Explorer link, and the exact hankoBinding JSON snippet to paste into your AgentCard.

hanko verify <agent>

Fetch the trust report for an agent.

hanko verify 8N3v...JkGf

╔════ HANKO  trust report ════════════════════╗
║ Agent         8N3v...JkGf                   ║
║ Status        ✓ Sealed                      ║
║ Karma         742 / 1000  (Gold)            ║
║ Bond          1.2 SOL                       ║
║ Attestations  18                            ║
║ Slashes       0                             ║
║ Domain        agent.example.com  ✓ verified ║
║ Since         2026-03-01                    ║
║ Explorer      https://explorer.solana.com…  ║
╚═════════════════════════════════════════════╝

Exit codes: 0 sealed, 2 pending / unknown, 3 slashed, 4 below --min-karma, 1 bad input.

--json emits machine-readable output. When the backend is unreachable the CLI renders an explicit unknown fallback rather than fabricating data.

hanko attest <agent>

Ed25519-sign and post a Reputation Registry attestation.

hanko attest 8N3v...JkGf \
  --score 90 \
  --tag quality --tag latency \
  --uri https://receipt.example.com/tx-42

Signed input is the canonical byte layout the Anchor program verifies on chain ("hanko-attest" || client || agent || score || tag_bitmap || uri_hash || nonce). Predefined tags:

quality, latency, accuracy, uptime, safety, cost, compliance,
responsiveness, transparency, reliability, creativity, throughput,
consistency, documentation, support, security

hanko stake <amount>

Top up an agent's bond.

hanko stake 0.5sol             # bare number = SOL
hanko stake 500000000lamports  # explicit lamports

hanko slash <agent> --evidence <32-byte-hex>

Report evidence and slash an agent's bond. The reporter (caller) receives 50% and 50% burns. Requires a 32-byte hex digest (with or without 0x).

hanko slash 8N3v...JkGf \
  --evidence 0xdeadbeef...deadbeef

hanko karma <agent>

Print the detailed karma breakdown pulled from the indexer.

Karma
742 / 1000  (gold)
──────────────────────────────
Duration       182 days   ▸ 91  pts
Attestations   18         ▸ 405 pts
Validation     92% success▸ 184 pts
Slash penalty  0          ▸ 0   pts

hanko init-agentcard

Generate and Ed25519-sign an A2A v1.0 AgentCard including the hankoBinding extension. Interactive by default; add --yes and pass every required flag for CI use.

hanko init-agentcard \
  --domain agent.example.com \
  --organization "Example Labs" \
  --output ./agent-card.json

Signing uses JCS (RFC 8785) canonicalisation + detached JWS ({"alg":"EdDSA","typ":"a2a+jws"}). The signed file is verified in-process before it's written so a broken sign path fails loudly.

Drop the file at https://<domain>/.well-known/agent-card.json.

hanko sealed-badge --agent <pubkey>

Emit an embeddable "Sealed by HANKO" badge snippet.

hanko sealed-badge --agent 8N3v...JkGf --format html
hanko sealed-badge --agent 8N3v...JkGf --format md
hanko sealed-badge --agent 8N3v...JkGf --format url

<a href="https://hanko.network/torii?q=8N3v...JkGf" target="_blank" rel="noopener">
  <img src="https://api.hanko.network/embed/8N3v...JkGf/badge.svg" alt="Sealed by HANKO" width="120" height="40"/>
</a>

hanko config

Manage configuration.

hanko config show
hanko config path
hanko config get apiUrl
hanko config set cluster devnet

GitHub Action

Ship the hanko-verify composite action from this repo:

# .github/workflows/verify.yml
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: hanko-labs/hanko/packages/cli/actions/hanko-verify@main
        with:
          agent: ${{ vars.HANKO_AGENT }}
          min-karma: "600"
          cluster: mainnet-beta

The action installs hanko-cli and runs hanko verify --json. The job fails when karma is below the threshold or the agent is slashed. Outputs (status, karma, tier, report) are available to downstream steps.

x402 middleware integration

For servers that gate paid endpoints with x402, pair hanko verify --json with the payment challenge so unpaid and untrusted agents both reject early:

import { hankoGuard } from "@hankolabs/x402-middleware";
import { x402PaymentRequired } from "x402";

app.use("/paid", hankoGuard({ minKarma: 550 }));
app.use("/paid", x402PaymentRequired({ amount: "0.10", asset: "USDC" }));

Under the hood hankoGuard calls the same /trust/{pubkey} endpoint the CLI does, so a single source of truth governs both human and machine flows.

Exit codes

| Code | Meaning | | ---- | ------------------------------------------ | | 0 | success (sealed for verify, tx sent) | | 1 | bad input / RPC error / signature failure | | 2 | pending / unknown / karma fetch failed | | 3 | slashed | | 4 | karma below --min-karma |

Development

pnpm install
pnpm --filter hanko-cli build
pnpm --filter hanko-cli test
node packages/cli/dist/index.js --help

Build produces a single-file ESM bundle at dist/index.js with the #!node shebang so bin/hanko works after npm i -g.

License

MIT © Hanko Labs