# Handsel

> The machine economy runs a tab, not a signup.

Handsel replaces the vendor signup form with six protocol acts — open, try,
prove, commit, evaporate, settle — carried entirely in the OAuth 2.1 / MCP
authorization slots that agent clients already speak. An unmodified OAuth/MCP
client reaches first value with zero forms; the account stops being a
precondition of use and becomes a lazily-materialized side effect of it. The
signup form's six jobs (durable principal, contact capture, risk filtering,
pricing consent, credential issuance, and — perversely — making the user fund
the vendor's risk) are unbundled into separately-priced, just-in-time step-up
challenges attached to one continuous grant lineage.

Status (honest): this is a working reference implementation. Stripe runs in
TEST MODE; no external vendor is live yet. The `handsel` CLI and `@handsel/*`
npm packages are not yet published — publish is imminent.

## The six acts

- open — a guest grant, on sight. No page rendered, no fields. (SPEC §7–8)
- try — budgeted, TTL-bounded trials at real vendor tenants. (SPEC §10)
- prove — one blinded workload, a signed Evaluation Certificate. (SPEC §11)
- commit — promote the winning trial in place, same grant lineage. (SPEC §12)
- evaporate — losers garbage-collect, with signed deletion receipts. (SPEC §13)
- settle — vendor-signed, core-countersigned receipts. Idempotent, never
  arrears, never a negative balance, no cash-out. (SPEC §14, §17)

## The ladder

One grant, four rungs, no re-onboarding: guest → claimed → mandated → assured.
The grant_id and the pairwise subject_key are stable from the first anonymous
call to the top. (SPEC §4)

## Discovery chain (rung 0, zero-form)

A stock MCP client drives standard RFC surfaces; Handsel adds nothing to the
client:

1. POST /mcp  → 401 + WWW-Authenticate: Bearer (RFC 9728 challenge)
2. GET  /.well-known/handsel.json  → the vendor descriptor + signed schedule
3. GET  /.well-known/oauth-protected-resource  → authorization_servers: [core] (RFC 9728)
4. GET  /.well-known/oauth-authorization-server  → AS metadata (RFC 8414)
5. POST /v1/oauth/register  → dynamic client registration (RFC 7591)
6. GET  /authorize  → 302 with ?code (provisions a guest grant on sight, PKCE S256)
7. POST /v1/token  → guest access + refresh, ent.cpd embedded (OAuth 2.1)
8. POST /mcp  → retry with the bearer → initialize → tools/call → price-0 co-signed receipt

## Vendor SDK — install + hello world

Install (not yet on npm — publish imminent):

    npm i @handsel/sdk

Mount ~20 lines of config over your existing endpoint; keep your tool handler.
Field names are verbatim from @handsel/sdk:

    import { createHandselVendor, mountHandselRoutes } from '@handsel/sdk'
    import { Hono } from 'hono'

    const app = new Hono()

    const vendor = createHandselVendor({
      product: 'lexica',
      name: 'Lexica',
      resource: 'https://api.example.com',
      handselCore: 'https://core.handsel.ai',
      signingKey: SIGNING_SEED,                 // 32-byte Ed25519 seed
      pricing: { unit: 'call', price_usd_micros: 2000 },  // $0.002
      tiers: {
        guest:    { calls_per_day: 5 },
        claimed:  { calls_per_day: 500 },
        trial:    { sponsored: false, ttl_s: 1_209_600 },
        mandated: {},
      },
      termsHash: TERMS_HASH,                     // sha256 of your consent text
      deletionSlaS: 604_800,                     // one week
    })

    mountHandselRoutes(app, vendor)              // well-knowns + /handsel/*

    app.all('/mcp', async (c) => {
      const ok = await vendor.authorize(c.req.raw)
      if (ok instanceof Response) return ok      // 401/403 challenge, verbatim
      const out = await yourTool(c.req.raw)      // keep your own handler
      await vendor.emitReceipt(ok, { path: '/mcp' })
      return out
    })

## Vendor CLI arc (packages publish imminent — not yet on npm)

    npm create @handsel/vendor    # scaffold the edge
    npx handsel keygen            # mint an Ed25519 signing seed
    npx handsel register          # pin your resource origin + public key
    npx handsel verify            # self-grading conformance slice
    npx handsel claim             # connect Stripe (test mode)
    npx handsel connect           # go live on the ladder

Agent-driven path: `/handsel-integrate` reads your OpenAPI, wires the SDK, and
opens the PR. Target: prompt → green PR in under 30 minutes.

## Links

- Home: https://handsel.ai/
- Quickstart (vendor runbook): https://handsel.ai/quickstart
- Source + SPEC: not yet public — publishing with the design-partner cohort (contact below)
- Design partners / contact: alex@handsel.ai