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:

The end-to-end flow

One pay() call drives five moves. Here is what actually happens on the wire — and which of them a relying party can re-check:

1. Build & sign the mandate.

   The SDK assembles the EIP-712 Mandate (payer, token, amount, recipient, chainId, deadline, requiredCapabilities, nonce) and your wallet signs it. paymentId = keccak256(mandate).

2. Register it.

   POST /payments hands the signed mandate (plus any attestations) to the Coordinator, which runs an admission check and stores it as PROPOSED.

3. Settle on-chain.

   Your own wallet broadcasts the ERC-20 transfer(recipient, amount). No service ever touches the funds — this is what zero-custody means concretely.

4. Observe.

   POST /payments/:id/observe with the txHash. The Coordinator waits for confirmations, finds the matching Transfer log, and the adapter key signs a Receipt attesting exactly what it saw.

5. Verify → ship.

   The verifier checks the receipt’s proof (and attestations) against the mandate and a pinned policy. requiredCapabilities ⊆ satisfiedCapabilities ⇒ ACCEPT ⇒ status SETTLED. A merchant re-runs this step alone, offline, to decide whether to ship — no trust in the Coordinator required.

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:

Integrated before June 29? The wire changed (breaking) — signatures made against the old struct no longer verify. See the wire changelog (§13) for the two-minute migration.

1. Install.

   git clone https://github.com/project-hsp/hsp && 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();                            // → terminal status (usually "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.

Capability grammar

A capability is verb:object:version; the verifier compares canonical sets byte-for-byte — no fuzzy matching, no partial credit.

A public payment requires the empty set (trivially satisfied). A compliant payment requires attests:kyc + attests:sanctions — the verifier ACCEPTs only if both are present and signed by an issuer the deployment’s policy trusts (see the trusted set at /issuers).

The sandbox’s adapters are operator-attested observations, so today they satisfy no proves:* capability — proves:settlement-verified is reserved in the vocabulary for a future trust-minimized adapter. The capabilities you can actually require right now are the empty set (public) and attests:kyc / attests:sanctions (compliant).

Signer backends

One wire signature, three sources for the key — and the signing account is always the settling account (Transfer.from must equal the mandate signer).

// 1) raw key — scripts / demos / small testnet amounts
signer: { kind: 'privateKey', privateKey: '0x…' }
// 2) any viem account — mnemonic, HD, hardware wallet
signer: { kind: 'viemAccount', account }
// 3) a real wallet (browser) — the key never leaves it
signer: { kind: 'eip1193', provider: window.ethereum, address }

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.

The MCP server is pure and key-less — it holds no private key and signs nothing. It gives an agent tools to verify, explain, and build HSP objects, and now to pay — but key-lessly: it prepares the unsigned payment, a wallet MCP (or the user’s wallet) signs it, and it submits the signed result. @hsp/sdk (HSPClient.pay / payX402) is still an option for paying from code.

// .mcp.json — hsp (key-less) + a wallet MCP as the signer
"hsp": { "command": "npx", "args": ["tsx", "packages/mcp/src/index.ts"],
  "env": { "HSP_CHAIN": "hashkey-testnet",
    // URL + WRITE key for prepare/submit — NOT a signing key:
    "HSP_COORDINATOR_URL": "<COORDINATOR_URL>", "HSP_API_KEY": "<your-team-key>",
    // optional — only widen what hsp_verify can check:
    "HSP_PINNED_ADAPTER_ADDRESS": "0x…" } },
// the EXTERNAL SIGNER — agent routes prepare's toSign[] here, then submits:
"phantom": { "command": "npx", "args": ["-y", "@phantom/mcp-server@latest"] }

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.

# POST /payments      Authorization: Bearer <API_KEY>
{ "chain": "hashkey-testnet",
  "mandate": { "body": { /* 8 EIP-712 fields */ }, "signature": "0x…" },
  "attestations": [ /* optional — for compliant payments */ ] }
# → 201  { "paymentId": "0x…", "status": "PROPOSED" }

# POST /payments/0x…/observe   Authorization: Bearer <API_KEY>
{ "txHash": "0x…" }
# → 200 observed & verified   |   202 still confirming (retry)

# GET /payments/0x…    (public — no key needed)
{ "status": "SETTLED",
  "mandate": { /* … */ }, "receipts": [ { /* adapter-signed */ } ],
  "lastDecision": { "ok": true, "outcomeClass": "ACCEPT" } }

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

const d = await verifier.verify(mandate, receipt, attestations);
switch (d.outcomeClass) {
  case 'ACCEPT':    ship(); break;
  case 'RETRYABLE': await retryLater(); break;
  case 'POLICY':    fix(d.errorCode); break;      // mandate / attestations
  case 'PERMANENT': giveUp(d.errorCode);              // structurally invalid
}

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 so you run nothing yourself. One set of endpoints serves both HashKey Chain networks — testnet (chainId 133) and mainnet (177). You choose per payment with the chain field; there is nothing separate to spin up or connect to for mainnet. 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. Grab your own API key at /register (self-service), and generate your own testnet wallet (a private key) funded 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.

Mainnet (hashkey · 177) — real money

This sandbox also serves hashkey — HashKey Chain mainnet — for public payments. Everything about the flow is identical to testnet, except that it is real money and you are on your own for funds:

• No faucet. Fund your own wallet with mainnet USDC.e + HSK gas.
• 5 confirmations before the observer treats a settlement as observable (testnet: 2) — receipts arrive correspondingly later.
• x402 works on mainnet too — a dedicated mainnet facilitator settles at <COORDINATOR_URL>/facilitator-mainnet (pass it as facilitatorUrl). Client-pull means the payer needs no HSK at all — only USDC.e; the facilitator pays the gas. It refuses authorizations the payer cannot cover (insufficient_funds).
• Compliance flows on mainnet are demonstrations, not assurances. The mock issuer signs for any subject without real checks (§12 table above) — on mainnet that means the verification mechanics are real, the compliance claims are not. Treat mainnet as public-path territory; run compliance scenarios on testnet.

Start on hashkey-testnet; move to mainnet only when your flow is stable. Same base URLs, same API key — just chain: "hashkey" in your SDK config and mandates (chainId: 177).

This sandbox tracks the current wire (v1). If you vendored the repo or hand-rolled signing before a change landed, this section is how you find out — and how you migrate.

v0 → v1 · 2026-06-29 · delegation wire (breaking)

Symptom if you are still on v0: your signature verifies locally, but POST /payments rejects with HSP-MAND-SIGNER (PERMANENT). The signature itself is fine — it is over the old struct, so the digest this verifier recomputes no longer matches the one you signed. The rejection’s errorDetail reports the recovered address and the server-side digest, so the mismatch is directly visible.

The v1 typed data (sign exactly these fields, in this order):

Mandate {
  nonce bytes32, signer Signer, grantRef bytes32, requirementRef bytes32,
  recipient Recipient, token address, amount uint256, chainId uint256,
  deadline uint64, settlementBinding bytes32, requiredCapabilitiesHash bytes32
}
Signer    { profileId bytes32, payload bytes }
Recipient { kind uint8, payload bytes }

Empty requiredCapabilities still hashes to bytes32(0); signer.payload is still abi.encode(address).

Migration: update your vendored repo to current main and re-sign — nothing else in your integration changes. If you hand-roll the typed data: switch primaryType to Mandate, add the three new fields as 32 zero bytes in the order above, re-sign. The last v0 state is frozen at tag v0-mandatebody — diff it against main to see every wire change: git diff v0-mandatebody main -- packages/core.

v0 and v1 signatures cannot cross-verify (different typehashes) — fail-closed by design, never a silent wrong-accept. If you hit anything this page does not explain, the errorDetail string in the rejection is the first thing to share when asking for help.