registeredOutcomesSnapshot

Per-side balance snapshots of every active prediction market outcome (zstd+msgpack).

⚠️ This is an add-on endpoint - access has to be purchased separately.

Returns compressed snapshots for active HIP-4 outcomes — one snapshot per outcome side (YES/NO). Each snapshot lists every holder of that side and their balance.

There are two endpoints:

1. Metadata Endpoint (Fast) — check whether new snapshots are available.

2. Snapshot Endpoint (Heavy) — download compressed snapshot data.

---

registeredOutcomesSnapshotTimestamp (Fast)

• Endpoint: POST /info

• Purpose: check whether new snapshots have been written

• Response time: ~1 ms

Request

Field	Type	Description
type	string	Must be "registeredOutcomesSnapshotTimestamp"

curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "registeredOutcomesSnapshotTimestamp" }'

Response

{
  "snapshot_id": "20260428_state_123456789",
  "timestamp": 1745846400
}

---

registeredOutcomesSnapshot (Heavy)

• Endpoint: POST /info

• Purpose: download per-side outcome snapshots

• Response time: ~100 ms+

Request

Field	Type	Description
type	string	Must be "registeredOutcomesSnapshot"
outcome_ids	array of integers	Outcome ids to fetch (optional). Each id expands to two asset_ids: YES = #{id*10}, NO = #{id*10+1}.
asset_ids	array of strings	Asset ids in #NNNN format (optional). Used as-is.
question_ids	array of integers	HIP-4 question ids (optional). Each is server-side-expanded to its child outcomes (named + fallback), then each child to its YES + NO asset_ids.

If outcome_ids, asset_ids, and question_ids are all omitted, the response contains every active outcome side.

After deduplication, the combined outcome_ids (expanded) + asset_ids + question_ids (expanded to children, then to asset_ids) list must not exceed 50 entries; larger requests are rejected with 400 Bad Request.

# Specific outcomes (YES + NO)
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  --output outcomes.bin \
  -d '{ "type": "registeredOutcomesSnapshot", "outcome_ids": [3, 7] }'

# All active outcomes
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  --output outcomes.bin \
  -d '{ "type": "registeredOutcomesSnapshot" }'

Response Headers

• Single asset_id: x-payload-format: msgpack, Content-Encoding: zstd

• Multiple asset_ids: x-payload-format: multi-zstd, x-compression: inner-zstd

Data Format

Single Snapshot Response

Format: raw zstd-compressed MessagePack.

Decompressed structure — a positional 4-element array. rmp-serde encodes Rust structs as msgpack arrays by default, so the field order matters, not the names:

[
  "20260428_state_123456789",            // [0] snapshot_id
  3,                                      // [1] outcome_id
  "#30",                                  // [2] asset_id
  {                                       // [3] balances — address → integer-lot string
    "0xa11ce...000a": "100",
    "0xb0b...000b": "5"
  }
]

Note: balances are formatted via HL's size-decimals rules. Outcome side tokens currently ship with szDecimals=0 and weiDecimals=5 on-chain; the producer reads both per-token from spot meta and uses them to descale and format. With szDecimals=0, balances are rounded to whole lots and rendered as integer strings — no decimal point, no trailing zeros ("100", not "100.00"). Sub-lot dust uses banker's rounding (round-half-to-even). Parse with int(s).

Note: the HL escrow precompile address for each token is excluded from the snapshot. Every spot token has a deterministic escrow at 0x32{:038x} of its token_id (e.g. 0x32000000000000000000000000000000000001ca for token 458) that holds the unsold/issuer supply — it isn't a real user position. Thus, it is dropped from each side's balances map.

Multiple Snapshots Response

Format: custom binary framing with per-snapshot zstd payloads.

Binary structure:

[count: 4 bytes LE][len1: 4 bytes LE][zstd_blob1][len2: 4 bytes LE][zstd_blob2]...

Each zstd_blob decompresses to one positional 4-element msgpack array with the [snapshot_id, outcome_id, asset_id, balances] shape shown above. Snapshots are returned in (outcome_id, side_index) order.

Implementation Example

import requests, struct, zstandard as zstd, msgpack, os

response = requests.post(
    "https://api.hydromancer.xyz/info",
    json={"type": "registeredOutcomesSnapshot", "outcome_ids": [3, 7]},
    headers={
        "Authorization": f"Bearer {os.environ['HYDROMANCER_API_KEY']}",
        "Content-Type": "application/json",
    },
)
body = response.content
fmt = response.headers.get("x-payload-format")

if fmt == "msgpack":
    snapshot = msgpack.unpackb(zstd.ZstdDecompressor().decompress(body), raw=False)
    print(snapshot)
else:
    # multi-zstd: count, then [len][blob] pairs
    count = struct.unpack("<I", body[:4])[0]
    offset = 4
    snapshots = []
    for _ in range(count):
        length = struct.unpack("<I", body[offset:offset + 4])[0]
        offset += 4
        blob = body[offset:offset + length]
        offset += length
        snapshots.append(
            msgpack.unpackb(zstd.ZstdDecompressor().decompress(blob), raw=False)
        )
    for snap in snapshots:
        # snap is a 4-element list: [snapshot_id, outcome_id, asset_id, balances_map].
        # Balance values are integer-lot strings (sz_decimals=0).
        asset_id = snap[2]
        balances = {addr: int(s) for addr, s in snap[3].items()}
        print(asset_id, len(balances), "holders")

Error Handling

• 400 — asset_id missing the # prefix, or the request exceeds 50 deduped asset_ids.

• 500 — no matching snapshots in Redis, or the producer hasn't written any yet. Retry after polling registeredOutcomesSnapshotTimestamp.