[lib] pyth-hermes — Pyth Network Hermes (oraculo precios) [VALIDADO]

[robertruben98]

Objetivo

Crear pyth-hermes (PyPI): cliente Python para la Pyth Network Hermes API (oráculo de precios real-time). Hueco CONFIRMADO: no existe wrapper Python serio.

Contexto API

• Qué es: servicio off-chain que observa Pythnet + Wormhole y expone price feeds vía HTTPS/WSS.
• Endpoints públicos:
  • Producción: https://hermes.pyth.network
  • Beta (testnets): https://hermes-beta.pyth.network
• OpenAPI/Swagger: https://hermes.pyth.network/docs/ ← usar para generar/validar modelos.
• Docs: https://docs.pyth.network/price-feeds/core/api-instances-and-providers/hermes

---

🔴 VALIDACIÓN EXHAUSTIVA (hecha en vivo + docs) — LEER ANTES DE EMPEZAR

Hallazgo CRÍTICO — auth obligatoria desde 31-jul-2026

• Hoy (jun-2026) el endpoint público es sin API key, PERO el "Pyth Core upgrade" del 31-jul-2026 hace API key OBLIGATORIA para todo usuario (faltan ~40 días).
• Implicación de diseño: el cliente DEBE soportar API key desde el día 1 (param opcional ahora, requerido pronto) + base URL configurable (para los providers de pago: Triton, P2P, extrnode, Liquify, y el endpoint beta).
• El header exacto de la API key aún no está documentado → dejar el mecanismo parametrizable (header name configurable) y seguir el "upgrade preparation guide" al implementar.

Rate limits (confirmado en docs)

• 10 requests / 10 segundos por IP. Exceder → 429 durante los siguientes 60 segundos.
• El cliente DEBE manejar 429 con backoff que respete la ventana de 60s (no reintentar agresivo).

Endpoints probados EN VIVO (jun-2026)

Endpoint	Estado	Nota
GET /v2/price_feeds	✅ 200	Devuelve 3056 feeds. attributes: asset_type, base, country, description, display_symbol, publish_interval, quote_currency, schedule, symbol
GET /v2/updates/price/latest?ids[]=...&parsed=true	✅ 200	Multi-id OK. Devuelve binary + parsed[] con {price, conf, expo, publish_time}
GET /v2/updates/price/{timestamp}?ids[]=...	✅ 200	Histórico por timestamp OK
GET /v2/updates/price/stream (SSE)	✅	~3 eventos/seg, estable
GET /v2/updates/twap/{window}/latest	❌ 400	TWAP DEPRECADO — NO implementar. Responde: "The TWAP endpoint has been deprecated and is no longer available."

Competencia (hueco confirmado real)

• NO hay cliente Python oficial de Hermes — el oficial es solo JS/TS (@pythnetwork/hermes-client en npm).
• hermes-python en PyPI = NO relacionado (bindings Snips/MQTT).
• pyth-client-py = datos on-chain de Solana, NO la API Hermes.

Nombre PyPI

• ✅ LIBRE: pyth-hermes (preferido, más limpio), pyth-hermes-py, pyth-client, pyth-sdk.
• ❌ Tomados: pyth, pyth-py, hermes-client.

---

Endpoints a cubrir (v1)

• GET /v2/price_feeds — catálogo/búsqueda de feeds (filtro por query y asset_type).
• GET /v2/updates/price/latest — último precio para 1..N feed IDs (binary + parsed).
• GET /v2/updates/price/{publish_time} — precio histórico por timestamp.
• GET /v2/updates/price/stream — SSE streaming de updates.
• NO implementar TWAP (deprecado).

Scope (v1)

• Solo lectura (no firma transacciones). Consumo de precios off-chain.
• Helper expo: precio real = price * 10**expo. Validado: BTC price=6395282153102, expo=-8 → $63,952.82.
• Búsqueda feed→id por símbolo. ⚠️ Confirmado en vivo: /v2/price_feeds?query=... trae feeds variantes/DEPRECATED primero (MBTC, XBTC...). Filtrar por attributes.symbol == "Crypto.BTC/USD" exacto, NO substring. Feed canónico BTC/USD = e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43.

Stack

• httpx (async + sync).
• pydantic v2 (PriceFeed, Price, PriceUpdate, BinaryUpdate) — derivar del OpenAPI.
• SSE: httpx-sse o impl propia con reconnect+backoff.
• Salida opcional a pandas.DataFrame para históricos.

Deliverables

• Cliente sync + async, con soporte de API key + base URL configurable desde el inicio.
• Manejo de rate limit (429 → respetar 60s).
• Modelos Pydantic de todos los responses.
• Streaming SSE con async iterator + reconnect.
• Helper símbolo→feed_id (match exacto) + helper expo→decimal.
• Tests (mock HTTP) + ejemplos en examples/.
• README, publicar en PyPI como pyth-hermes, CI (ruff + mypy --strict + GitHub Actions).

Criterios de aceptación

• pip install pyth-hermes funciona.
• Obtener precio BTC/USD en <5 líneas.
• Stream SSE estable (reconnect con backoff).
• 429 manejado sin crashear (espera 60s).
• API key opcional hoy, lista para cuando sea obligatoria (31-jul-2026).
• mypy --strict pasa.

Prioridad

Tier S — mejor primer proyecto: flujo validado end-to-end en vivo, demanda altísima, hueco limpio. ⏰ Ventana de oportunidad: publicar ANTES del 31-jul-2026 para capturar adopción justo cuando todos necesiten migrar a auth con key.

[robertruben98]

🗂️ Añadido al board global pero sin calificar. Para entrar en /plan-time, puntúa Impact/Confidence/Ease (1-10) y añade estimados por tarea con · Nm.

Usa el Issue Form planned o corre /register-work pyth-hermes.