# POSTHUMAN Network Hub API client guide

Canonical base: `https://hub.posthuman.digital`

Contract: `https://hub.posthuman.digital/openapi.json`

Interactive directory: `https://hub.posthuman.digital/mcp-api/api`

## Integration rules

- Treat `openapi.json` as the source of truth. Do not infer endpoints from frontend traffic or imported Node Ops guide text.
- The published contract contains exactly 32 fixed public `GET` operations plus one non-mutating `POST /api/celestia/bridge-probe`. That probe accepts only an exact reviewed registry tuple and performs one TCP/2121 connect; it is not an arbitrary scanner or proxy. Authentication is not required.
- Check `schemaVersion`, `generatedAt`, `source`, route-specific `scope`, and `warnings` before using a response.
- Respect the documented record caps and HTTP caching. An unavailable, stale, partial, or collecting response is not proof that the underlying chain has no data.
- Treat developer-activity commits and linked contributors as bounded repository observations only. They do not measure code quality, team productivity, delivery, decentralization, or investment merit.
- Static snapshot routes have no application-level numeric quota. Account, validator, and Photon reads share 60 requests per client per minute; transaction and block reads share a separate 60; the Celestia probe and fixed RPC diagnostic share 20. Forwarded identity is accepted only from the explicitly configured loopback proxy boundary. Cache idempotent GET responses where allowed, retry only with bounded backoff, and treat `429` as a stop-and-wait signal.
- Cross-origin browser access is not guaranteed by the contract. The Hub UI uses same-origin requests; external integrations should use a server-side HTTPS client unless response CORS headers explicitly allow the browser origin.
- Use exact network IDs, chain IDs, addresses, hashes, heights, and denoms. Never reuse a response across networks.
- Celestia transaction hashes are canonical celestia-core hashes: one valid
  `INDX` or `BLOB` wrapper layer is removed before SHA-256. Use the hash returned
  by the API rather than assuming SHA-256 of the outer block transaction bytes.
- `/api/sp1-blobstream` is a mainnet-only status projection for the three exact
  contracts in the official SP1 Blobstream `v1.1.0` registry. It is not a
  contract-call proxy. Mocha-5 is explicitly unavailable and must not be
  inferred from historical testnet deployment heights.
- Do not submit mnemonic phrases, private keys, validator keys, Celestia JSON-RPC tokens, cookies, wallet session data, or internal host details. Credential-bearing headers are rejected by the Celestia service.
- Every fixed `GET` route also accepts `HEAD`, returning the GET-equivalent status and representation headers (including `Content-Length`) without a response body. `HEAD` is transport metadata, not an additional public operation. The Celestia probe remains `POST`-only.
- Unknown or malformed `/api` paths return JSON `404`; disallowed query input on exact dynamic routes returns JSON `400`; recognized routes reject unsupported methods with JSON `405` and an `Allow` header.
- The API does not sign, broadcast, control hosts, restart nodes, replace data, or provide an arbitrary upstream proxy.

## Minimal examples

```bash
curl --fail --silent --show-error \
  'https://hub.posthuman.digital/api/governance'
```

```js
const response = await fetch(
  'https://hub.posthuman.digital/api/validators',
  { headers: { accept: 'application/json' }, credentials: 'omit' },
)
if (!response.ok) throw new Error(`Hub API ${response.status}`)
const snapshot = await response.json()
if (snapshot.schemaVersion !== 'posthuman.validators/v1') {
  throw new Error('Unsupported validator schema')
}
console.log(snapshot.generatedAt, snapshot.source, snapshot.networks)
```

```js
const response = await fetch(
  'https://hub.posthuman.digital/api/sp1-blobstream',
  { headers: { accept: 'application/json' }, credentials: 'omit' },
)
if (!response.ok) throw new Error(`Hub API ${response.status}`)
const status = await response.json()
if (status.schemaVersion !== 'posthuman.sp1-blobstream/v1') {
  throw new Error('Unsupported SP1 Blobstream schema')
}
console.log(status.celestia.height, status.deployments)
```

```python
import json
from urllib.request import Request, urlopen

request = Request(
    "https://hub.posthuman.digital/api/network-watchers",
    headers={"Accept": "application/json"},
)
with urlopen(request, timeout=10) as response:
    snapshot = json.load(response)
if snapshot.get("schemaVersion") != "posthuman.network-watchers/v1":
    raise RuntimeError("unsupported watcher schema")
print(snapshot["generatedAt"], snapshot["source"])
```

## Client generation

Generate typed clients from the reviewed OpenAPI document, pin the contract checksum in reproducible builds, and review generated diffs before release. A generated client does not expand API authority: only methods present in the generated client are available. The TypeScript SDK deliberately excludes the user-triggered Celestia transport probe and its companion registry/RPC diagnostics; use their exact OpenAPI operations directly when needed.

Recommended client behavior:

1. Set a finite timeout and a descriptive user agent.
2. Retry only idempotent `GET` requests with bounded backoff. Do not automatically retry the user-triggered bridge probe.
3. Validate response schema versions and exact request identity.
4. Surface stale, partial, collecting, unsupported, unavailable, and truncated states.
5. Preserve exact integer amounts as strings.
6. Log public request metadata only; do not log wallet or secret material.

Common failures are returned as JSON with an `error` string. Clients should handle invalid input (`400`), missing exact resources (`404`), unsupported methods (`405`, with `Allow`), an applied edge limit (`429`), invalid or unavailable upstream data (`502`), and temporary service unavailability (`503`) without treating them as empty successful results. Static snapshot routes can instead return their documented unavailable or collecting state in a successful response.

The first contract intentionally keeps the existing unversioned `/api/*` paths canonical. Future `/api/v1/*` aliases must not be used until they are deployed, documented, and independently verified.

## MCP status

The POSTHUMAN MCP is live at `https://mcp.posthuman.digital/mcp` (also proxied at `/mcp-api/mcp`) for bearer-authenticated Streamable HTTP POST. Keys are issued to beta testers for now. Its tools are read-only: `list_networks`, `get_network_parameters`, `get_validators`, `get_governance`, `get_network_stats`, `get_consensus_health`, `get_snapshot`, `get_market`, `list_capabilities`, `get_capability_metadata`, `search_capabilities`. On the Hub path, ordinary browser GET opens the documentation; GET with `Accept: text/event-stream` returns HTTP 405. No bearer token or unauthenticated client command is published here. The separate Hub live-read tool mapping at `/mcp-tools-planned.json` remains a non-callable plan with a null endpoint and Server Card.