# Bob SPV Helper API v1

Version: 1.0
Published: 2026-08-07
Canonical public page: https://bobwallet.org/docs/spv-helper-api-v1

## Purpose

Bob SPV Helper API v1 is a provider-neutral, read-only compatibility contract
between Bob Wallet and a fully validating HSD backend. It supplies indexed
chain and name state that Bob's local SPV node cannot reliably reconstruct.

The helper is not a wallet, broadcaster, or custodian. Keys and signing remain
local to Bob. Clients must treat helper responses as untrusted input and fail
closed when consensus-critical data is missing or inconsistent.

The words MUST, MUST NOT, SHOULD, and MAY describe requirements.

## Transport

- Public base URLs MUST use HTTPS.
- JSON-RPC uses `POST <base-url>` with `Content-Type: application/json`.
- Responses MUST contain `result`, `error`, and the request `id` when supplied.
- Successful responses MUST use HTTP 200 and `error: null`.
- Clients MUST ignore unknown additive fields.
- Amounts MUST be non-negative integer dollary, HSD's base unit.
- Providers and clients MUST NOT convert wire amounts to display HNS.

## Required REST routes

| Method | Route | Purpose |
| --- | --- | --- |
| GET | `/hsd` | Node information |
| GET | `/hsd/block/:height-or-hash` | Block lookup |
| GET | `/hsd/tx/:hash` | Transaction lookup |
| GET | `/hsd/coin/:hash/:index` | Current coin lookup |
| POST | `/hsd/tx/address` | Address transaction history |

## Allowed JSON-RPC methods

`POST /hsd` exposes only:

- `estimatesmartfee`
- `getblockbyheight`
- `getblockchaininfo`
- `getnamebyhash`
- `getnameinfo`
- `verifymessage`

State-changing, wallet, mining, and administrative RPC methods MUST be
rejected.

## Backend requirements

The backing node MUST be Handshake mainnet, fully synced, full-node rather than
SPV, non-pruned, wallet-disabled, transaction-indexed, and address-indexed.
Its authenticated HSD API MUST remain private behind the restricted gateway.

## REGISTER contract

For REGISTER construction, `getnameinfo` MUST preserve standard HSD semantics.
These fields are authoritative:

| Field | Requirement |
| --- | --- |
| `result.info.name` | Requested normalized ASCII name |
| `result.info.nameHash` | HSD hash of that name |
| `result.info.state` | `CLOSED` |
| `result.info.height` | REGISTER covenant auction height |
| `result.info.owner` | Reveal or claim outpoint spent by REGISTER |
| `result.info.value` | REGISTER output value in integer dollary |
| `result.info.registered` | `false` before first registration |

`info.highest` is informative and MUST NOT replace `info.value`. Explorer
labels, HTML, decimal display strings, and third-party auction summaries MUST
NOT be used to construct REGISTER. Zero-value wins are valid.

Before funding or signing, Bob MUST:

1. query `getnameinfo` through the configured helper in SPV mode or connected
   full HSD node in full-node mode;
2. validate all consensus-critical fields above;
3. require the local input outpoint and auction height to match;
4. set the REGISTER output to `info.value` before coin selection, change, fee
   calculation, and signing; and
5. stop without broadcasting when validation fails.

Clients MUST NOT edit the outputs of an already signed transaction.

## Compatibility and evolution

Bob MUST work with any conforming provider. No transaction rule may depend on
a provider hostname. Additive response fields and optional read-only routes MAY
be added within v1. Changing a field meaning, amount unit, required method, or
security boundary requires a new major version.

Known compatible endpoints at publication time:

- `https://spv.learnhns.com/hsd`
- `https://api.handshakeapi.com/hsd` (legacy service scheduled to wind down
  after 2026-08-31)

Provider compatibility is a technical statement, not custody or endorsement.