mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
Step one of the builder path is now one TypeScript file: sign a CAIP-122 message with the agent's wallet, trade it for a token, mint a key, make a free call, and ask for a USDC deposit address. A wallet seen for the first time gets its own account and organization on the Free plan. The page shows the file's real output from a 2026-10-26 run. The prompt block takes the updated standard prompt, which puts the wallet path first, and the title carries the pitch. Claude-Session: https://claude.ai/code/session_017vrVus6PPBgP5YRzKV1iqW
459 lines
42 KiB
HTML
459 lines
42 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hanzo</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/hanzo.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hanzo">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hanzo.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>hanzo</h1><p class="lede">Onboard an agent onto Hanzo, the AI operating system for business: get a credential, make a first call to api.hanzo.ai, add the Hanzo MCP server, evaluate Kai, and pay. Load when building with or on Hanzo or calling api.hanzo.ai; when getting a Hanzo API key or token (signing in with a wallet, no human; the hanzo CLI device flow; an agent's own email-code sign-up; minting a key); when adding Hanzo MCP to Claude Code, Codex, Cursor or Zed; when making or evaluating Kai decisions; when giving agents keys with budgets, rate limits or expiry; when drafting an ad or email campaign over the API; or when paying for Hanzo (plans, card checkout, USDC or USDT deposits, wire).</p><h1>Hanzo</h1>
|
|
<p>No human required: sign in with a wallet, get a key, call the API, top up in USDC.</p>
|
|
<p>The AI operating system for business. Building business software since 2014. Techstars '17.</p>
|
|
<h2>The prompt</h2>
|
|
<p>Paste this into any agent. It is the whole onboarding in one message; the rest of this page is the detail behind each line.</p>
|
|
<pre><code class="lang-text">You can build on Hanzo, the AI operating system for business (building business software since 2014; Techstars '17). One API at https://api.hanzo.ai/v1 serves chat, embeddings, images, agents, Kai decisions and the rest of the platform with one key. Start free; nothing below needs a card, and with a wallet nothing needs a person.
|
|
|
|
Get a credential:
|
|
- With a wallet, no human required: GET https://hanzo.id/v1/iam/web3/nonce?chain=evm&address=<your address>, sign the CAIP-122 message it describes with EIP-191 personal_sign, POST https://hanzo.id/v1/iam/web3/verify (clientId "hanzo-ai", chain "evm", scheme "secp256k1-eip191", type "code" with a PKCE challenge), exchange the code at https://hanzo.id/v1/iam/oauth/token, then POST https://api.hanzo.ai/v1/account/keys {"name":"agent","type":"secret"}. A first-seen wallet gets its own account and organization on the Free plan. The whole flow as one TypeScript file: https://hanzo.ai/agents#headless
|
|
- With your person nearby: run `curl -fsSL https://hanzo.sh | sh`, then `hanzo auth login`. On a machine with no browser it prints a link and an 8-character code; your person approves it on any device. Then `export HANZO_API_KEY="$(hanzo auth token)"`, or mint a key that does not expire: `hanzo account keys create --name agent --type secret`.
|
|
- On your own, with an inbox: POST https://hanzo.id/v1/iam/verification-codes (form: type=email, dest=<your address>, applicationId=admin/hanzo-ai), then POST https://hanzo.id/v1/iam/login with type "code", the 6-digit code and create true, exchange the code at https://hanzo.id/v1/iam/oauth/token, and POST https://api.hanzo.ai/v1/account/keys {"name":"agent","type":"secret"}. The whole sequence: https://docs.hanzo.ai/docs/agents
|
|
|
|
Free: 50 requests a day per person on `zen-free` and `enso-free`, and 50 Kai decisions a day. Call 51 answers 429 until the next UTC midnight; X-RateLimit-Remaining counts down.
|
|
|
|
First call:
|
|
curl https://api.hanzo.ai/v1/chat/completions -H "Authorization: Bearer $HANZO_API_KEY" -H "Content-Type: application/json" -d '{"model":"zen-free","messages":[{"role":"user","content":"Hello"}]}'
|
|
|
|
Tools for your editor or agent: `npx -y --package=@hanzo/mcp@latest hanzo-mcp serve` (an MCP server over stdio with Kai, files, shell, git and search tools). Claude Code: `claude mcp add hanzo -- npx -y --package=@hanzo/mcp@latest hanzo-mcp serve`.
|
|
|
|
Evaluate Kai, the decision model, yourself: POST https://api.hanzo.ai/v1/decisions with {"model":"kai","state":...,"questions":...}; the frozen harness is public at https://github.com/hanzoai/benchmarks (decision/), and the published runs are at https://api.hanzo.ai/v1/research/runs?org=hanzo&benchmark=app.phishing
|
|
|
|
Pay when you need more: plans from $20 a month at https://hanzo.ai/pricing (card, Apple Pay or Google Pay at https://hanzo.ai/pay), or top up over the API in USDC or USDT with no human: GET /v1/billing/crypto/options, then POST /v1/billing/crypto/deposit {"chain":"base","token":"usdc","amountCents":2000} and send to the address it returns; the balance is credited when the chain confirms. Per-key budgets and per-session caps keep spend bounded.
|
|
|
|
Read more: https://docs.hanzo.ai/llms.txt (every docs page), https://hanzo.ai/llms.txt, https://api.hanzo.ai/v1/openapi.json (every operation), https://hanzoskills.com/llms.txt (skills). Talk to people at Hanzo: https://cal.com/hanzo, or https://hanzo.ai/contact.</code></pre>
|
|
<h2>Why Hanzo</h2>
|
|
<p>We have built and run software for businesses since 2014. We were founded as Crowdstart, a crowdfunding and commerce platform, and renamed Hanzo in 2016. The platform has been Go-native since October 2014. Our first customer, in 2014, SKULLY, raised $1M in about 45 hours, the fastest fully-funded campaign on Indiegogo. AI and machine learning have been in our commercial work since 2014, and GPT models by 2019. In 2017 we built the first blockchain-native commerce platform; the Unikrn ICO raised over 120,000 ETH. Techstars '17. Our clients were funded by Y Combinator, 500 Startups, Techstars and other tier-1 venture firms: hundreds of venture-funded startups, billions in client revenue, two companies taken past 100 million users, and two that went public on Nasdaq in 2024, Damon Motorcycles and Triller. What that work taught us is what Hanzo's AI is built on. The history, with case studies and press: https://hanzo.ai/about</p>
|
|
<h2>Results</h2>
|
|
<ul><li>Damon Motorcycles, CES 2020 launch: $8.4M of motorcycles sold in 30 days, a 541:1 return on ad spend, a pre-launch campaign that reached 60,384 people on $329, every AI-generated ad set rated "Above Average" on Facebook within 36 hours, and YouTube subscribers up 3,752%. https://hanzo.ai/customers/damon-motorcycles</li><li>SKULLY: $1M in about 45 hours, the fastest fully-funded campaign on Indiegogo. https://techcrunch.com/2014/08/14/the-skully-smart-helmet-is-the-fastest-funded-indiegogo-campaign-to-hit-1m/</li><li>Unikrn: the 2017 ICO raised over 120,000 ETH. https://news.crunchbase.com/startups/found-ico-makes-sense/ (Hanzo's part: https://hanzo.ai/customers#unikrn)</li></ul>
|
|
<h2>Path A: you are an agent building on Hanzo</h2>
|
|
<h3>1. Headless: sign in with a wallet</h3>
|
|
<p>No person, inbox or card. The API is <code>https://api.hanzo.ai/v1</code>; identity is <code>https://hanzo.id</code> (OIDC discovery at <code>/.well-known/openid-configuration</code>, PKCE S256). This one file signs a CAIP-122 message with EIP-191 <code>personal_sign</code>, trades it for a token, mints a key, makes a free call and asks for a USDC deposit address:</p>
|
|
<pre><code class="lang-ts">// No human required: sign in with a wallet, get a key, call the API, top up in USDC.
|
|
// A first-seen wallet gets its own Hanzo account and organization, on the Free plan.
|
|
// npm i viem · node headless.mts (Node 22.18+; set HANZO_WALLET_KEY to use your own wallet)
|
|
import { createHash, randomBytes } from 'node:crypto'
|
|
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
|
|
|
|
const ID = 'https://hanzo.id'
|
|
const API = 'https://api.hanzo.ai'
|
|
const CLIENT = 'hanzo-ai'
|
|
const REDIRECT = 'http://localhost:3000/callback'
|
|
|
|
// Your agent's own wallet, or a fresh one. The key never leaves this process.
|
|
const account = privateKeyToAccount((process.env.HANZO_WALLET_KEY as `0x${string}`) ?? generatePrivateKey())
|
|
|
|
const json = async (r: Response) => {
|
|
const body = await r.json()
|
|
if (!r.ok || body?.status === 'error') throw new Error(`${r.url} ${r.status} ${JSON.stringify(body)}`)
|
|
return body
|
|
}
|
|
|
|
// 1. A one-time challenge for this wallet.
|
|
const { data: c } = await json(await fetch(`${ID}/v1/iam/web3/nonce?chain=evm&address=${account.address}`))
|
|
|
|
// 2. The CAIP-122 message the challenge describes, signed with EIP-191 personal_sign.
|
|
const message = [
|
|
`${c.domain} wants you to sign in with your Ethereum account:`,
|
|
account.address,
|
|
'',
|
|
...(c.statement ? [c.statement, ''] : []),
|
|
`URI: ${c.uri}`,
|
|
`Version: ${c.version}`,
|
|
`Nonce: ${c.nonce}`,
|
|
`Issued At: ${c.issuedAt}`,
|
|
...(c.expirationTime ? [`Expiration Time: ${c.expirationTime}`] : []),
|
|
].join('\n')
|
|
const signature = await account.signMessage({ message })
|
|
|
|
// 3. Verify: a first-seen wallet gets an account and an organization of its own.
|
|
const verifier = randomBytes(32).toString('base64url')
|
|
const challenge = createHash('sha256').update(verifier).digest('base64url')
|
|
const { data: code } = await json(
|
|
await fetch(`${ID}/v1/iam/web3/verify`, {
|
|
method: 'POST',
|
|
headers: { 'Content-Type': 'application/json' },
|
|
body: JSON.stringify({
|
|
clientId: CLIENT, chain: 'evm', scheme: 'secp256k1-eip191', address: account.address, message, signature,
|
|
type: 'code', redirectUri: REDIRECT, scope: 'openid profile email', codeChallenge: challenge, codeChallengeMethod: 'S256',
|
|
}),
|
|
}),
|
|
)
|
|
|
|
// 4. The authorization code for a token.
|
|
const token = await json(
|
|
await fetch(`${ID}/v1/iam/oauth/token`, {
|
|
method: 'POST',
|
|
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
|
|
body: new URLSearchParams({ grant_type: 'authorization_code', client_id: CLIENT, code, code_verifier: verifier, redirect_uri: REDIRECT }),
|
|
}),
|
|
)
|
|
const bearer = { Authorization: `Bearer ${token.access_token}`, 'Content-Type': 'application/json' }
|
|
|
|
// 5. A key that outlives the token. Shown once: keep it in your secret store.
|
|
const minted = await json(await fetch(`${API}/v1/account/keys`, { method: 'POST', headers: bearer, body: JSON.stringify({ name: 'agent', type: 'secret' }) }))
|
|
const key = { Authorization: `Bearer ${minted.key}`, 'Content-Type': 'application/json' }
|
|
|
|
// 6. A first call, free.
|
|
const chat = await fetch(`${API}/v1/chat/completions`, {
|
|
method: 'POST', headers: key,
|
|
body: JSON.stringify({ model: 'zen-free', messages: [{ role: 'user', content: 'Reply with the single word: ready' }] }),
|
|
})
|
|
console.log('chat', chat.status, chat.headers.get('x-hanzo-served'), 'free left today:', chat.headers.get('x-ratelimit-remaining'))
|
|
console.log((await chat.json()).choices?.[0]?.message?.content)
|
|
|
|
// 7. Top up in USDC: ask for a deposit address, then send to exactly that address.
|
|
console.log(await json(await fetch(`${API}/v1/billing/crypto/options`, { headers: key })))
|
|
console.log(await json(await fetch(`${API}/v1/billing/crypto/deposit`, { method: 'POST', headers: key, body: JSON.stringify({ chain: 'base', token: 'usdc', amountCents: 500 }) })))
|
|
console.log('HANZO_API_KEY=' + minted.key.slice(0, 12) + '… (store the whole key; it is shown once)')</code></pre>
|
|
<pre><code class="lang-bash">npm i viem && node headless.mts</code></pre>
|
|
<p>A real run, trimmed:</p>
|
|
<pre><code class="lang-text">chat 200 zen-free free left today: 49
|
|
ready
|
|
{ chains: [ 'base', 'ethereum', 'solana' ], tokens: [ 'usdc', 'usdt' ] }
|
|
{ id, status: 'pending', chain: 'base', token: 'usdc', depositAddress: '0x…', expiresAt: '+24h' }
|
|
HANZO_API_KEY=sk-live-…</code></pre>
|
|
<p>A first-seen wallet gets its own account (<code>wallet_evm_<16 hex></code>) and organization (<code>wallet-evm-<16 hex></code>, which it administers) on the Free plan. The token is valid 7 days (<code>expires_in</code> 604800); the minted key outlives it. Keep the wallet key and the API key in your secret store: whoever holds the wallet key signs in as you.</p>
|
|
<h3>2. Other ways to get a credential</h3>
|
|
<p>With a person nearby, headless machines included:</p>
|
|
<pre><code class="lang-bash">curl -fsSL https://hanzo.sh | sh
|
|
hanzo auth login # no browser: prints a link and an 8-character code
|
|
export HANZO_API_KEY="$(hanzo auth token)" # 1-hour access token, sent as Bearer</code></pre>
|
|
<p>The person approves the code on any device. The same device flow without the CLI:</p>
|
|
<pre><code class="lang-bash">curl -X POST 'https://hanzo.id/v1/iam/oauth/device?client_id=hanzo-cli&scope=openid%20profile%20email&response_type=device_code'
|
|
# -> device_code, user_code, verification_uri_complete, expires_in 900, interval 5
|
|
curl -X POST https://hanzo.id/v1/iam/oauth/token \
|
|
-d "grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=hanzo-cli&device_code=$DEVICE_CODE"
|
|
# repeat every 5 s until the person approves</code></pre>
|
|
<p>On your own, with an inbox you can read. Every endpoint here answers and validates; the whole sequence has not yet been run end to end.</p>
|
|
<pre><code class="lang-bash"># 1. a 6-digit code: valid 10 minutes, 5 tries, resend after 30 s
|
|
curl -X POST https://hanzo.id/v1/iam/verification-codes \
|
|
-F type=email -F [email protected] -F applicationId=admin/hanzo-ai
|
|
|
|
# 2. a PKCE pair
|
|
verifier=$(openssl rand -hex 32)
|
|
challenge=$(printf %s "$verifier" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
|
|
|
|
# 3. sign in, creating the account -> {"data":"<authorization code>"}
|
|
curl -X POST https://hanzo.id/v1/iam/login -H 'Content-Type: application/json' \
|
|
-d '{"type":"code","organization":"hanzo","clientId":"hanzo-ai","username":"[email protected]","code":"123456","create":true,"terms":"terms-2026-09-30","aup":"aup-2026-09-30","redirectUri":"http://localhost:3000/callback","responseType":"code","scope":"openid profile email","codeChallenge":"'"$challenge"'","codeChallengeMethod":"S256"}'
|
|
|
|
# 4. exchange the code -> access_token
|
|
curl -X POST https://hanzo.id/v1/iam/oauth/token -d grant_type=authorization_code -d client_id=hanzo-ai \
|
|
-d code="$CODE" -d code_verifier="$verifier" -d redirect_uri=http://localhost:3000/callback</code></pre>
|
|
<p>Step 3 creates a passwordless, email-verified account and a personal organization you administer. Send it with <code>"create":false</code> first to learn whether the address may sign up without spending the code. A wrong code answers 400 "the code is incorrect or has expired". Creating an account accepts https://hanzo.ai/legal/terms and https://hanzo.ai/legal/acceptable-use.</p>
|
|
<p>Then mint a key that does not expire in an hour:</p>
|
|
<pre><code class="lang-bash">curl -X POST https://api.hanzo.ai/v1/account/keys \
|
|
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
|
|
-d '{"name":"agent","type":"secret"}'
|
|
# -> "key": "sk-live-...", shown once
|
|
hanzo account keys create --name agent --type secret # the same, from the CLI</code></pre>
|
|
<p>Keep the key in your runtime's secret store, never in a tracked file. No card is needed to sign up or mint a key. People can also mint keys at https://platform.hanzo.ai under API keys.</p>
|
|
<h3>3. The free tier</h3>
|
|
<ul><li>50 requests per person per UTC day. Call 51 answers 429 until the next UTC midnight.</li><li>Kai is also capped at 50 requests a day on the free plan. Past it: 429 with <code>"code":"free_plan_cap"</code>, <code>resets_at</code> and <code>topup_url</code>.</li><li>Free models: <code>zen-free</code>, <code>enso-free</code>, <code>zen5</code>, <code>zen5-flash</code>, <code>zen5-mini</code>, <code>zen5-pro</code>, <code>zen5-coder</code>. The catalog needs no key: <code>curl https://api.hanzo.ai/v1/models</code> (559 models, 33 free, on 2026-10-26).</li></ul>
|
|
<h3>4. First call</h3>
|
|
<pre><code class="lang-bash">curl https://api.hanzo.ai/v1/chat/completions \
|
|
-H "Authorization: Bearer $HANZO_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"model":"zen-free","messages":[{"role":"user","content":"In one sentence: what is Hanzo?"}]}'</code></pre>
|
|
<p>Expect 200, <code>x-hanzo-served: zen-free</code>, <code>x-ratelimit-limit: 50</code> and <code>x-ratelimit-remaining</code> counting down. The body is OpenAI-shaped: read <code>choices[0].message.content</code>.</p>
|
|
<p>SDKs: <code>npm i hanzoai</code> (TypeScript), <code>pip install "hanzoai>=8"</code> (Python 3.12+). In TypeScript, <code>new AiApi(new Configuration({ basePath: 'https://api.hanzo.ai', accessToken: process.env.HANZO_API_KEY }))</code> gives <code>getModels()</code> and <code>postChatCompletions({ openaiChatCompletionRequest: { model: 'zen-free', messages } })</code>, the same route as the curl.</p>
|
|
<h3>5. MCP</h3>
|
|
<p>Run the local server; all four clients below take it. Name the package and the binary apart: <code>npx -y @hanzo/mcp serve</code> makes npx read <code>serve</code> as a second package. Claude Code:</p>
|
|
<pre><code class="lang-bash">claude mcp add hanzo --env HANZO_API_KEY=$HANZO_API_KEY -- npx -y --package=@hanzo/mcp@latest hanzo-mcp serve</code></pre>
|
|
<p>Codex, <code>~/.codex/config.toml</code> (<code>codex mcp add hanzo --env HANZO_API_KEY=... -- npx -y --package=@hanzo/mcp@latest hanzo-mcp serve</code> writes it):</p>
|
|
<pre><code class="lang-toml">[mcp_servers.hanzo]
|
|
command = "npx"
|
|
args = ["-y", "--package=@hanzo/mcp@latest", "hanzo-mcp", "serve"]
|
|
|
|
[mcp_servers.hanzo.env]
|
|
HANZO_API_KEY = "sk-..."</code></pre>
|
|
<p>Cursor, <code>.cursor/mcp.json</code> or <code>~/.cursor/mcp.json</code>:</p>
|
|
<pre><code class="lang-json">{ "mcpServers": { "hanzo": { "command": "npx", "args": ["-y", "--package=@hanzo/mcp@latest", "hanzo-mcp", "serve"], "env": { "HANZO_API_KEY": "sk-..." } } } }</code></pre>
|
|
<p>Zed, <code>settings.json</code> (format checked against Zed's defaults, not yet run inside Zed):</p>
|
|
<pre><code class="lang-jsonc">"context_servers": { "hanzo": { "command": "npx", "args": ["-y", "--package=@hanzo/mcp@latest", "hanzo-mcp", "serve"], "env": { "HANZO_API_KEY": "sk-..." } } }</code></pre>
|
|
<p>The server (stdio) lists 42 tools: files, shell, git, fetch, code search, browser, memory, planning, and the Kai tools (<code>kai_decide</code>, <code>kai_choice</code>, <code>kai_score</code>, <code>kai_command_guard</code>, <code>kai_injection_screen</code> and more).</p>
|
|
<p>The hosted endpoint, <code>POST https://api.hanzo.ai/v1/mcp</code>, answers <code>initialize</code> with protocol version 2026-07-28 only, and Claude Code 2.1.310 refuses that version. Use it only from a client that speaks 2026-07-28.</p>
|
|
<h3>6. Evaluate Kai</h3>
|
|
<p>Kai is the decision model: it answers typed questions about a state with probabilities over options you name, and writes no text.</p>
|
|
<pre><code class="lang-bash">curl https://api.hanzo.ai/v1/decisions \
|
|
-H "Authorization: Bearer $HANZO_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"model":"kai","state":{"ticket":"The export button throws a 500 error since this morning."},"questions":{"team":{"type":"choice","instructions":"Which team should handle this ticket?","criteria":{"billing":"charges, invoices, refunds","tech":"bugs, errors, outages","other":"anything else"}}}}'</code></pre>
|
|
<p>A real answer, trimmed: <code>"team":{"type":"choice","choice":"tech","confidence":0.951,"probabilities":{"billing":0.004,"tech":0.967,"other":0.028}}</code>, with <code>"output_tokens":0</code>. Kai costs $0.021 per million input tokens; output is free.</p>
|
|
<p>Run the frozen harness yourself (public repo):</p>
|
|
<pre><code class="lang-bash">git clone --depth 1 https://github.com/hanzoai/benchmarks && cd benchmarks/decision
|
|
export HANZO_API_KEY=sk-...
|
|
python3 harness/run_kai.py --limit 3 --suites jev.ag_news,jev.emotion,jev.banking77_full,app.support_triage,app.email_spam,app.phishing,app.guardrails_jailbreak,app.moderation_toxicity,app.rag_relevance,app.model_routing_domain,typed_decisions --out $PWD/kai.json.gz
|
|
uv run --with numpy python harness/merge.py --kai $PWD/kai.json.gz --out $PWD/out</code></pre>
|
|
<p>That is 33 requests, inside the free plan's 50, and a wiring check rather than a result. Without <code>--limit</code> it is the whole harness: 9,499 requests, which needs a paid plan or credit. <code>merge.py</code> writes <code>out/table.md</code> and <code>out/scores.json</code>, Kai beside Jev's recorded answers; Jev is never called. The published full runs need no key: https://api.hanzo.ai/v1/research/runs?org=hanzo&benchmark=app.phishing (also <code>app.support_triage</code>, <code>jev.banking77_full</code>, <code>massive</code>, <code>decision.latency</code>). Docs: https://docs.hanzo.ai/docs/decisions</p>
|
|
<h3>7. Run a campaign</h3>
|
|
<p>Read from the API contract, not yet run end to end. You prepare; the owner launches, because launching spends ad budget. Measure first: put the event tag on the site (<code><script src="https://api.hanzo.ai/v1/event/tag.js" ...></code>, the one-line install) or POST events to <code>https://api.hanzo.ai/v1/event</code>.</p>
|
|
<pre><code class="lang-bash"># KPIs: web (pageviews, visitors, sessions), commerce (orders, revenue, AOV); available:false when empty
|
|
curl "https://api.hanzo.ai/v1/event/overview?range=7d" -H "Authorization: Bearer $HANZO_API_KEY"
|
|
|
|
# write the ad variants with a model (POST /v1/chat/completions, zen-free is free), then save them as a draft:
|
|
# nothing is sent and no budget is committed
|
|
curl -X POST https://api.hanzo.ai/v1/campaign \
|
|
-H "Authorization: Bearer $HANZO_API_KEY" -H 'Content-Type: application/json' \
|
|
-d '{"name":"Spring launch","audience":"<segment>","content":["variant A","variant B"],"budget":50000,"channels":[{"kind":"paid","platform":"meta"},{"kind":"email"}]}'
|
|
|
|
# the owner's step: this spends the ad budget at the provider
|
|
curl -X POST "https://api.hanzo.ai/v1/campaign/$CAMPAIGN_ID/launch" -H "Authorization: Bearer $HANZO_API_KEY"
|
|
|
|
curl "https://api.hanzo.ai/v1/campaign/$CAMPAIGN_ID/metrics?range=7d" -H "Authorization: Bearer $HANZO_API_KEY"
|
|
curl -X POST "https://api.hanzo.ai/v1/campaign/$CAMPAIGN_ID/pause" -H "Authorization: Bearer $HANZO_API_KEY"</code></pre>
|
|
<ul><li><code>budget</code> is in cents. <code>content[0]</code> is the active creative; the rest are A/B variants, 32 at most.</li><li>At most one channel per kind: <code>paid</code>, <code>organic</code>, <code>email</code>. Platforms: <code>meta</code>, <code>google</code>, <code>x</code>, <code>instagram</code>, or the email provider. Paid channels run through the org's own connected ad accounts.</li><li>Launch is best-effort per channel: each channel row reports live, failed or unavailable, and repeating it is safe.</li><li>Metrics: impressions, clicks, conversions, revenue, visitors, spend per channel, CTR, CVR, CAC, ROAS, and <code>abTest</code> when there is more than one creative.</li><li>Email at scale: <code>POST /v1/email</code> (commercial email, per-recipient unsubscribe), drip sequences at <code>/v1/marketing/sequences</code>, audiences at <code>/v1/marketing/audiences</code>. SMS is not an API channel.</li></ul>
|
|
<h3>8. Rate limits</h3>
|
|
<p>Every answer carries <code>X-RateLimit-Limit</code>, <code>X-RateLimit-Remaining</code> and <code>X-RateLimit-Reset</code> (unix seconds) for the tightest limit in play. Seen: 100 a second per IP before auth, 60,000 a minute per org on <code>/v1/decisions</code>, 50 a day per person on free chat. A refusal is 429: wait for <code>X-RateLimit-Reset</code> or <code>Retry-After</code>. A key's own <code>rate</code> answers 429 and its <code>budget</code> answers 402.</p>
|
|
<p><strong>Do this now:</strong> run <code>headless.mts</code>, or get a credential another way and run the first call. A 200 with <code>x-ratelimit-remaining</code> means you are on.</p>
|
|
<h2>Path B: you own the agents</h2>
|
|
<h3>1. Account and org</h3>
|
|
<p>Sign up at https://hanzo.ai/signup or run <code>hanzo auth login</code>. Sign-up founds a personal organization you administer.</p>
|
|
<h3>2. Team plan</h3>
|
|
<p>$25 per member a month ($20 billed yearly), 2 to 100 members, SSO, roles, audit log, one bill: https://hanzo.ai/pay/cart?plan=team. Also Pro $20 a month, every model including Enso Ultra and Kai (<code>plan=dev</code>); Max 5x $100, Max 20x $200, Max 50x $500; Team Premium $100 per member; Enterprise through sales. <code>GET https://api.hanzo.ai/v1/billing/plans</code> lists them with no key.</p>
|
|
<h3>3. One key per agent, bounded</h3>
|
|
<p>The example values are yours to set:</p>
|
|
<pre><code class="lang-bash">curl -X POST https://api.hanzo.ai/v1/account/keys \
|
|
-H "Authorization: Bearer $HANZO_API_KEY" -H 'Content-Type: application/json' \
|
|
-d '{"name":"agent-1","type":"secret","budget":{"month":2000,"total":10000},"rate":60,"limit":["model:zen-free"],"expires":"2027-01-01T00:00:00Z"}'</code></pre>
|
|
<p><code>budget</code> is in cents, monthly and total; past it the key answers 402. <code>rate</code> is requests per minute; past it, 429. <code>limit</code> only narrows, by <code>model:</code>, <code>project:</code> or <code>product:</code>. <code>expires</code> is RFC 3339. You can write 30 keys a minute and hold 1,000 live keys per org.</p>
|
|
<h3>4. A cap per agent session</h3>
|
|
<p><code>budget_micro_usd</code> is in micro-USD, so this is $5:</p>
|
|
<pre><code class="lang-bash">curl -X POST "https://api.hanzo.ai/v1/agent/sessions/$SESSION_ID/budget" \
|
|
-H "Authorization: Bearer $HANZO_API_KEY" -H 'Content-Type: application/json' \
|
|
-d '{"budget_micro_usd": 5000000}'</code></pre>
|
|
<p>A new cap must exceed what the session already spent. Raising it resumes a paused session; <code>null</code> removes the cap for good. <code>GET /v1/agent/sessions</code> lists sessions.</p>
|
|
<h3>5. Pay</h3>
|
|
<ul><li>Card, Apple Pay or Google Pay at https://hanzo.ai/pay. It needs a browser, because the card form tokenizes the card. Behind it: <code>POST /v1/billing/subscribe/card</code> for plans, <code>POST /v1/billing/topup/token</code> or <code>POST /v1/billing/topup</code> (saved card) for top-ups, <code>PUT /v1/billing/recharge</code> for auto-reload ($5 to $5,000).</li><li>USDC or USDT, entirely over the API: USDC on Base, Ethereum and Solana; USDT on Ethereum.</li></ul>
|
|
<pre><code class="lang-bash">curl https://api.hanzo.ai/v1/billing/crypto/options -H "Authorization: Bearer $HANZO_API_KEY"
|
|
curl -X POST https://api.hanzo.ai/v1/billing/crypto/deposit \
|
|
-H "Authorization: Bearer $HANZO_API_KEY" -H 'Content-Type: application/json' \
|
|
-d '{"chain":"base","token":"usdc","amountCents":2000}'
|
|
# -> id, status, depositAddress, addressTag, expiresAt
|
|
curl "https://api.hanzo.ai/v1/billing/crypto/deposit/$DEPOSIT_ID" -H "Authorization: Bearer $HANZO_API_KEY"</code></pre>
|
|
<p>Send exactly to the <code>depositAddress</code> the API returned, never to an address from a page.</p>
|
|
<ul><li>Bank wire: <code>GET /v1/billing/wire</code> returns the instructions and your reference to a signed-in caller. A wire is credited by hand after the bank confirms, so it is not instant.</li><li>Balance: <code>GET /v1/billing/balance</code>.</li></ul>
|
|
<h3>6. People</h3>
|
|
<p>Docs at https://docs.hanzo.ai, contact at https://hanzo.ai/contact, a call at https://cal.com/hanzo. Sales: [email protected]. Security: [email protected].</p>
|
|
<p><strong>Do this now:</strong> create the org, mint one key per agent with a budget and an expiry, and give each agent only its own key.</p>
|
|
<h2>Where the rest is</h2>
|
|
<ul><li><code>INDEX.md</code>, beside this file in hanzoai/skills (<code>skills/hanzo/INDEX.md</code>), lists the 133 Hanzo skill files next to it; the site serves each at <code>https://hanzoskills.com/<name>.md</code>.</li><li><code>kai</code>, building on Kai decisions: <code>npx skills add https://hanzoskills.com/kai.md</code></li><li><code>hanzo-api</code>, how to call each Hanzo product over api.hanzo.ai: https://hanzoskills.com/hanzo-api.md</li><li><code>skill</code>, the parts that run on your own machine: https://hanzoskills.com/skill.md</li><li>Every docs page: https://docs.hanzo.ai/llms.txt. Every operation: https://api.hanzo.ai/v1/openapi.json</li></ul>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/hanzo.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |