Verify the settlement,
not the promise.

Payment rails move money; almost none give the relying party a cryptographic answer to “did the thing I authorized actually happen, under the conditions I demanded?” HSP is that answer layer. The flow is always the same three moves:

Three wire objects carry the evidence — and that is the entire protocol surface:

Compliance is not a bolt-on: KYC and sanctions are ordinary capabilities in those sets, toggled per payment. The protocol is a pre-1.0 draft — these concepts are stable; wire details may still change.

Every scenario below is implemented, tested against real chains, and inspectable in the Explorer — the decision trace shows exactly which capability was required and what satisfied it. The matrix is two settlement paths × two policies:

Build agentic commerce, paid APIs (x402 paywalls), compliant settlement flows — or your own settlement adapter (§07).

Coming soon — private payments. A later release will add and open up privacy-preserving settlement: hide the recipient (stealth addresses) or the amount (a shielded pool), each with optional view-key disclosure to a regulator. They slot in as adapters — the capability model already reserves room for them, so nothing else on this page changes when they ship.

You consume HSP through a small layered stack — each layer is independently usable, and each lower layer is what the one above is built on. All of it runs from TypeScript source; no build step.

The Coordinator is the only service you talk to over the network. It registers mandates, observes your on-chain settlement, runs the verifier, stores the (mandate, receipt, attestations) triple, and serves status, a web Explorer, and this portal. It is custody-free — it signs observations with an adapter key, never moves money.

The SDK is distributed as a repository for the hackathon (not yet on npm). The organizer shares the repo link together with the sandbox details. Then:

1. Install.

   git clone <REPO_URL> && cd hsp
   # everything runs in Docker (no node on your host) — see the repo README,
   # or use your own Node 20+ toolchain:
   npm install

2. Get testnet funds.

   Open the faucet page (/faucet/) and paste your address — you receive gas + test USDC, rate-limited per address & IP. Or by API:

   curl -X POST -H 'content-type: application/json' \
     -d '{"address":"0xYOUR_ADDRESS"}' <FAUCET_URL>/faucet

3. Send a payment.

   import { HSPClient } from '@hsp/sdk';
   import { resolveChain } from '@hsp/core/chains/index';
   
   const chain = resolveChain('hashkey-testnet');            // pinned testnet USDC
   const hsp = new HSPClient({
     coordinatorUrl: process.env.HSP_COORDINATOR_URL,       // <COORDINATOR_URL>
     apiKey:         process.env.HSP_API_KEY,               // <API_KEY>
     signer:         { kind: 'privateKey', privateKey: process.env.HSP_PRIVATE_KEY },
     chain,
   });
   
   // USDC has 6 decimals → 1 USDC = 1_000_000 base units
   const handle = await hsp.pay({ to: '0xRecipient', amount: 1_000_000n });
   await handle.awaitSettled();                            // → "SETTLED"

   That single pay() call builds the mandate, signs it, registers it, broadcasts the ERC-20 transfer from your own wallet, asks the Coordinator to observe it, and returns a handle.

4. Watch the decision.

   Open /explorer and paste the paymentId — see the mandate, the receipt, and the subset chain that produced ACCEPT.

Want to settle a different way — a new rail, a new proof? @hsp/devkit gives you a template plus a conformance runner that checks your adapter against the protocol’s generic obligations using the real verifier. The verifier never changes; only your proof schema does.

# 1. start from a template that already passes conformance
cp packages/devkit/template/my-adapter.ts        my-team/adapter.ts
cp packages/devkit/template/run-conformance.ts   my-team/run-conformance.ts
# 2. make it settle YOUR way, then self-test:
npx tsx my-team/run-conformance.ts
# → forged signatures, replays, deadline, observation reuse… all exercised

Then submit (adapterId, instanceKey, signing address, reorgPolicy) to the organizer to be registered in the sandbox Coordinator’s trust set — payers can settle through you. No protocol changes, no permission from the spec.

Two pieces let an AI agent pay safely — the agent never sees a private key beyond a small demo wallet you scope, and hsp_pay is bounded by hard server-side guardrails.

// .mcp.json env
"HSP_COORDINATOR_URL": "<COORDINATOR_URL>",
"HSP_API_KEY": "<API_KEY>",
"HSP_CHAIN": "hashkey-testnet",
"HSP_AGENT_PRIVATE_KEY": "0xDEMO_SMALL_AMOUNT_ONLY",
"HSP_MAX_AMOUNT_BASE_UNITS": "10000000",
"HSP_DAILY_CAP_BASE_UNITS": "50000000"

Write endpoints need Authorization: Bearer <API_KEY>. paymentId = mandateHash (idempotent); a 202 from observe means the tx is still confirming — the SDK retries for you.

Every verifier decision carries an outcomeClass — the HTTP-status-code of settlement. Branch on the class; log the errorCode.

HSP is zero-custody: your wallet settles; the Coordinator only signs observations with an adapter key — it cannot move funds. A relying party (a merchant, an auditor, a platform) pins the adapter’s address once (from GET /chains, out-of-band) and runs the verifier itself. If the Coordinator lied, your independent verification fails — that is the whole design.

The hackathon sandbox runs the full stack on HashKey Chain testnet so you run nothing yourself. One HTTPS host fronts every service; point your SDK at these base URLs:

Faucet (testnet gas + USDC): /faucet/ — rate-limited per address & IP. The adapter address to pin for independent verification is published at /chains.

No external accounts to register. The organizer gives you the API key and the URLs above; you only generate your own testnet wallet (a private key) and fund it from the faucet. No Circle, Coinbase, KYC-provider, RPC, or npm sign-up — the mock issuer and the x402 facilitator are part of this sandbox. The Explorer is public: looking up a payment by its id needs no key (an API key is only for browsing the full payment list).

Chains

Registry defaults shown; when this page is served by a live Coordinator the table reflects its actual configuration.