Skip to content

Commit 39d7a57

Browse files
webbrain-onewebbrain-one
committed
docs: add Spanish README
1 parent fdeca2e commit 39d7a57

1 file changed

Lines changed: 270 additions & 0 deletions

File tree

‎README.es-ES.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# hermes-pmxt
2+
3+
Integración de mercados de predicción para [Hermes Agent](https://github.com/NousResearch/hermes-agent).
4+
Busque mercados, compare precios, detecte arbitrajes y opere en múltiples intercambios de mercados de predicción a través de [pmxt](https://github.com/pmxt-dev/pmxt) (>= 2.50.0).
5+
6+
## Qué es esto
7+
8+
Una habilidad de Hermes + un conjunto de herramientas de Python que otorga a cualquier agente de Hermes acceso en tiempo real a los mercados de predicción. En lugar de alucinar probabilidades, el agente verifica los precios reales del mercado.
9+
10+
```
11+
Usuario: "¿Ganará Trump en 2028?"
12+
Agente: *llama a pmxt_search + pmxt_quote*
13+
Agente: "El mercado implica una probabilidad del 1.9% (No: 98.1%). Polymarket está valorando esto muy bajo."
14+
```
15+
16+
## Instalación
17+
18+
El paquete de PyPI ya está disponible. Para la mayoría de los usuarios, esta es la instalación completa:
19+
20+
```bash
21+
pip install hermes-pmxt
22+
```
23+
24+
Verifique que funcione:
25+
26+
```bash
27+
python3 -c "from hermes_pmxt import pmxt_runtime_status; print(pmxt_runtime_status())"
28+
```
29+
30+
### Configuración de la Habilidad de Hermes
31+
32+
Instale el archivo de habilidad de Hermes para que su agente sepa cuándo utilizar el paquete:
33+
34+
```bash
35+
mkdir -p ~/.hermes/skills/pmxt
36+
curl -fsSL https://raw.githubusercontent.com/0xharryriddle/hermes-pmxt/main/skill/SKILL.md \
37+
-o ~/.hermes/skills/pmxt/SKILL.md
38+
```
39+
40+
Si su instalación de Hermes admite la instalación de habilidades/plugins respaldados por GitHub, use:
41+
42+
```text
43+
https://github.com/0xharryriddle/hermes-pmxt
44+
```
45+
46+
### Actualización
47+
48+
```bash
49+
pip install --upgrade hermes-pmxt
50+
```
51+
52+
### Instalación para Desarrollo
53+
54+
Solo clone el repositorio si va a modificar hermes-pmxt:
55+
56+
```bash
57+
git clone https://github.com/0xharryriddle/hermes-pmxt.git
58+
cd hermes-pmxt
59+
python3 -m venv .venv
60+
source .venv/bin/activate
61+
pip install -e ".[dev]"
62+
```
63+
64+
## Modos
65+
66+
hermes-pmxt admite tres modos de ejecución:
67+
68+
| Modo | Configuración | Comportamiento |
69+
|------|--------|----------|
70+
| **Hosted** | Establezca `PMXT_API_KEY` | Se comunica con `https://api.pmxt.dev`. Gestiona las conexiones a los intercambios, el almacenamiento en caché y los límites de tasa automáticamente. Recomendado para la mayoría de los usuarios. |
71+
| **Custom** | Establezca `PMXT_API_URL` o `PMXT_BASE_URL` | Apunta a cualquier servidor compatible con PMXT. |
72+
| **Local Sidecar** | Sin clave/URL de API configurada | Asume que el núcleo de PMXT se está ejecutando en `http://localhost:3847`. Para auto-hospedaje / desarrollo. |
73+
74+
Verifique su modo actual:
75+
```python
76+
from hermes_pmxt import pmxt_runtime_status
77+
print(pmxt_runtime_status())
78+
```
79+
80+
## Inicio Rápido
81+
82+
```python
83+
from hermes_pmxt import pmxt_search, pmxt_quote, pmxt_runtime_status
84+
85+
# Verificar estado
86+
print(pmxt_runtime_status())
87+
88+
# Buscar
89+
result = pmxt_search("bitcoin", exchange="polymarket", limit=5)
90+
for m in result["data"]:
91+
prices = m.get("outcomes", [])
92+
if prices:
93+
print(f"{m['title'][:60]}: YES={prices[0]['price']*100:.1f}%")
94+
95+
# Cotización
96+
quote = pmxt_quote("bitcoin reach", exchange="polymarket")
97+
print(f"YES: {quote['data']['yes_pct']} NO: {quote['data']['no_pct']}")
98+
```
99+
100+
## Modelo de Datos
101+
102+
```
103+
Evento (tema amplio)
104+
└── Mercado (pregunta negociable)
105+
├── Resultado "Yes"
106+
└── Resultado "No"
107+
```
108+
109+
Cuando los usuarios pregunten sobre un tema, comience con eventos (`pmxt_events`), luego profundice en mercados y resultados.
110+
111+
## Herramientas
112+
113+
### Descubrimiento e Investigación
114+
115+
| Función | Auth | Descripción |
116+
|----------|------|-------------|
117+
| `pmxt_search(query, exchange?, limit?, sort?, search_in?, slug?)` | No* | Buscar mercados por palabra clave |
118+
| `pmxt_events(query, exchange?, limit?, sort?, search_in?, slug?)` | No* | Buscar grupos de eventos |
119+
| `pmxt_quote(identifier, exchange)` | No* | Obtener probabilidades YES/NO |
120+
| `pmxt_order_book(outcome_id, exchange, limit?)` | No* | Profundidad del libro de órdenes |
121+
| `pmxt_ohlcv(outcome_id, exchange, resolution?, limit?)` | No* | Velas de precio |
122+
| `pmxt_trades(outcome_id, exchange, limit?)` | No* | Operaciones recientes |
123+
| `pmxt_execution_price(outcome_id, exchange, side, amount)` | No* | Estimación de deslizamiento (slippage) |
124+
125+
### Inter-Plataforma y Arbitraje
126+
127+
| Función | Auth | Descripción |
128+
|----------|------|-------------|
129+
| `pmxt_compare_market(query, exchanges?, limit?)` | No* | Comparar precios entre intercambios |
130+
| `pmxt_arbitrage_scan(query, exchanges?, threshold?)` | No* | Detectar oportunidades de arbitraje |
131+
| `pmxt_call("compareMarketPrices", "router", ...)` | No* | Comparación nativa del enrutador |
132+
| `pmxt_call("fetchArbitrage", "router", ...)` | No* | Búsqueda de arbitraje nativa |
133+
| `pmxt_call("fetchHedges", "router", ...)` | No* | Oportunidades de cobertura (hedging) |
134+
135+
### Portafolio y Cuenta
136+
137+
| Función | Auth | Descripción |
138+
|----------|------|-------------|
139+
| `pmxt_balance(exchange)` | Yes | Balance de la cuenta |
140+
| `pmxt_positions(exchange)` | Yes | Posiciones abiertas |
141+
| `pmxt_portfolio(exchanges?)` | Yes | Portafolio multi-intercambio |
142+
143+
### Trading (Todas destructivas -- Requieren Confirmación Explícita)
144+
145+
| Función | Auth | Descripción |
146+
|----------|------|-------------|
147+
| `pmxt_build_order(...)` | Yes | Construir/firmar orden sin enviarla (SEGURO) |
148+
| `pmxt_submit_order(built, exchange, confirmed=True)` | Yes | Enviar una orden pre-construida |
149+
| `pmxt_cancel_order(order_id, exchange, confirmed=True)` | Yes | Cancelar una orden abierta |
150+
| `pmxt_order(...)` | Yes | Orden heredada de un solo paso (se prefiere build+submit) |
151+
152+
### Llamada Genérica a la API
153+
154+
| Función | Auth | Descripción |
155+
|----------|------|-------------|
156+
| `pmxt_call(method, exchange, ...)` | Varía | Llamada genérica a la API de PMXT con comprobaciones de seguridad |
157+
158+
### Servidor y Diagnósticos
159+
160+
| Función | Auth | Descripción |
161+
|----------|------|-------------|
162+
| `pmxt_runtime_status()` | No | Estado completo del tiempo de ejecución |
163+
| `pmxt_list_exchanges()` | No | Intercambios conocidos/disponibles |
164+
| `pmxt_server_status()` | No | Diagnósticos del sidecar |
165+
| `pmxt_server_start()` | No | Iniciar sidecar |
166+
| `pmxt_server_stop()` | No | Detener sidecar |
167+
168+
\* Las herramientas de solo lectura funcionan sin credenciales en el modo sidecar local. El modo Hosted requiere `PMXT_API_KEY` para todas las operaciones.
169+
170+
## Seguridad en el Trading
171+
172+
**Las operaciones destructivas (crear, enviar, cancelar órdenes) requieren la confirmación explícita del usuario.**
173+
174+
```python
175+
# SEGURO: Construir orden para previsualización (NO coloca ninguna orden)
176+
built = pmxt_build_order(
177+
market_id="market-uuid",
178+
outcome="yes",
179+
side="buy",
180+
order_type="limit",
181+
amount=10,
182+
price=0.55,
183+
exchange="polymarket",
184+
)
185+
186+
# DESTRUCTIVO: El envío requiere confirmed=True
187+
result = pmxt_submit_order(built, "polymarket", confirmed=True)
188+
189+
# Sin confirmed=True:
190+
result = pmxt_submit_order(built, "polymarket")
191+
# => {"success": False, "error": "Operation 'submit_order' is destructive..."}
192+
```
193+
194+
## Intercambios Compatibles
195+
196+
hermes-pmxt conoce 17 plataformas, incluyendo:
197+
198+
- `polymarket` / `polymarket_us`
199+
- `kalshi` / `kalshi-demo`
200+
- `limitless`
201+
- `probable` / `baozi` / `myriad` / `opinion`
202+
- `metaculus` / `smarkets`
203+
- `gemini-titan` / `hyperliquid` / `suibets` / `rain`
204+
- `mock` / `router`
205+
206+
La disponibilidad real depende de la versión de `pmxt` instalada. Ejecute `pmxt_list_exchanges()` para verificarlo.
207+
208+
## Variables de Entorno
209+
210+
```bash
211+
# Modo Hosted (recomendado)
212+
export PMXT_API_KEY="pmxt_live_..."
213+
export PMXT_WALLET_ADDRESS="0x..."
214+
export PMXT_PRIVATE_KEY="0x..."
215+
216+
# Servidor personalizado
217+
export PMXT_API_URL="https://your-server.com"
218+
# o
219+
export PMXT_BASE_URL="https://your-server.com"
220+
221+
# Específicos de la plataforma (modo auto-hospedado)
222+
export POLYMARKET_PRIVATE_KEY="0x..."
223+
export POLYMARKET_PROXY_ADDRESS="0x..." # Opcional
224+
export KALSHI_API_KEY="..."
225+
export KALSHI_PRIVATE_KEY="..."
226+
export LIMITLESS_API_KEY="..."
227+
export LIMITLESS_PRIVATE_KEY="..."
228+
export POLYMARKET_US_API_KEY="..."
229+
export POLYMARKET_US_PRIVATE_KEY="..."
230+
```
231+
232+
## Estructura del Proyecto
233+
234+
```
235+
hermes-pmxt/
236+
├── hermes_pmxt/
237+
│ ├── __init__.py # Exportaciones de la API pública
238+
│ ├── config.py # Configuración de ejecución y detección de modo
239+
│ ├── exchanges.py # Inicialización + normalización de intercambios
240+
│ ├── registry.py # Registro de herramientas con anotaciones de seguridad
241+
│ ├── shaper.py # Moldeado de resultados para el contexto del LLM
242+
│ └── tools.py # Funciones principales de las herramientas
243+
├── skill/
244+
│ └── SKILL.md # Instrucciones de la habilidad del agente Hermes
245+
├── examples/
246+
│ └── demo.py # Demo interactiva
247+
├── tests/
248+
│ ├── conftest.py # Configuración de rutas de prueba
249+
│ ├── test_exchanges.py # Pruebas unitarias de conexión de intercambios
250+
│ └── test_tools.py # Pruebas unitarias + de integración
251+
├── pyproject.toml
252+
└── README.md
253+
```
254+
255+
## Pruebas
256+
257+
```bash
258+
# Pruebas unitarias (no requiere pmxt)
259+
python3 -m pytest -q -m unit
260+
261+
# Todas las pruebas no destructivas
262+
python3 -m pytest -q -m "not trading"
263+
264+
# Pruebas de integración (requiere pmxt + sidecar/API)
265+
python3 -m pytest -q -m integration
266+
```
267+
268+
## Licencia
269+
270+
MIT

0 commit comments

Comments
 (0)