Bob Wallet Logo
Download

Open Standard ยท Version 1.0

Bob SPV Helper API v1

A provider-neutral contract for connecting Bob's lightweight SPV wallet to read-only data from a fully validating Handshake node.

What the helper does

SPV mode verifies headers and wallet activity without storing the complete Handshake chain state. A helper supplies indexed blocks, transactions, coins, fee estimates, and name state that Bob cannot reliably reconstruct locally.

The helper never receives seed phrases or private keys, never signs for the user, and does not broadcast transactions. Bob signs locally and broadcasts through its own Handshake peers.

Provider requirements

  • Serve the API over HTTPS from a stable base URL.
  • Use a fully synced, non-pruned mainnet HSD full node.
  • Enable transaction and address indexes.
  • Expose only the documented read-only REST routes and JSON-RPC methods.
  • Preserve standard HSD response meanings and integer dollary amounts.
  • Reject wallet, mining, administration, and state-changing RPC methods.
  • Protect the private HSD API key and place a restricted gateway in front of HSD.

Required API surface

MethodPathPurpose
GET/hsdNode information
GET/hsd/block/:idBlock lookup
GET/hsd/tx/:hashTransaction lookup
GET/hsd/coin/:hash/:indexCurrent coin lookup
POST/hsd/tx/addressAddress history
POST/hsdAllowed read-only JSON-RPC

Required JSON-RPC methods are estimatesmartfee, getblockbyheight, getblockchaininfo, getnamebyhash, getnameinfo, and verifymessage.

Safe name registration

Before Bob funds or signs a REGISTER transaction, it must query getnameinfo through the configured helper and verify the name, name hash, CLOSED state, auction height, winning outpoint, registration state, and final auction value.

The REGISTER output must equal result.info.value exactly. That value is an integer number of dollary. info.highest, explorer labels, rendered HTML, and decimal display strings must never replace it. Zero-value wins remain valid.

If the helper response is missing or disagrees with Bob's local wallet state, Bob must stop before signing or broadcasting.

Interoperability and conformance

Bob must work with any conforming provider; no transaction rule may depend on a provider hostname. Unknown additive response fields are allowed, but changing field meanings or amount units requires a new major version.

The legacy HandshakeAPI provider and LearnHNS returned identical consensus-critical name data in a live comparison on August 7, 2026. LearnHNS added only an optional start.locked field.

Read or download the plain Markdown standard. The reference gateway maintains automated provider audits and compatibility tests against this contract.

Current providers

  • LearnHNS: https://spv.learnhns.com/hsd
  • Legacy service: https://api.handshakeapi.com/hsd, expected to wind down after August 31, 2026.

Provider inclusion documents compatibility, not custody or endorsement. Users may configure another audited v1 provider in Bob.