API para integraciones
Una API de sólo lectura para socios y revendedores: el escaparate de traders con sus cifras reales, las noticias del mercado y el calendario económico. Con clave propia, ámbitos y cuota.
Dirección base
Todas las rutas de esta página cuelgan de este prefijo. Es el único sitio de la API pensado para que lo llame alguien de fuera.
https://luxor.algorvexa.com/api/v1/publicaEl resto de la API no sale de nuestra red. No es algo pendiente de abrir: cada ruta publicada es superficie que hay que defender, y este prefijo existe para ser el único que lo esté. Si algún día hay que cerrar la puerta, se cierra aquí sin tocar nada más.
Empezar en tres pasos
No hay registro automático de desarrolladores. Las claves las emitimos nosotros, y eso es deliberado: una credencial permanente que lee datos de traders reales no se reparte desde un formulario.
- Pídenos una clave. Dinos quién eres, para qué la quieres y qué vas a mostrar. Emitimos la clave con los ámbitos mínimos que necesites y, si procede, con caducidad.
- Guárdala como una contraseña. Te la entregamos una sola vez. No la guardamos: de nuestra base de datos sólo sale un hash, así que no podemos recuperarla ni enseñártela otra vez. Si se pierde, la revocamos y emitimos otra. No la pongas en el código ni en un repositorio: va en una variable de entorno o en un gestor de secretos.
- Llama primero a /estado. Te dice qué ámbitos tiene tu clave, cuándo caduca y cuánta cuota llevas gastada este minuto. Es la llamada que evita descubrir en la tercera ruta que te falta un ámbito.
Autenticación
Una cabecera y nada más. No hay OAuth, ni tokens que refrescar, ni sesiones que caduquen a los treinta minutos.
X-API-Key: lx_a1b2c3d4_TU-SECRETOComprueba que funciona
curl -s https://luxor.algorvexa.com/api/v1/publica/estado \
-H "X-API-Key: $LUXOR_API_KEY"- Va en una cabecera, nunca en la URL
- Una clave en la cadena de consulta acaba en los registros de todos los proxys por los que pase la petición, en el historial del navegador y en los informes de errores. Si te llega un ejemplo que la pone en la URL, está mal.
- La clave lee los datos de tu organización
- Y de ninguna otra. El alcance se fija al emitirla y no cambia, ni siquiera si cambia el administrador que la creó.
- Sólo por HTTPS
- Sin excepciones. En claro, tu clave la tiene cualquiera que comparta red con tu servidor.
- Se revoca en el acto
- Si crees que se ha filtrado, dínoslo. Revocarla es inmediato y no afecta a ninguna otra clave. Por eso conviene una clave por integración y no una compartida entre tres.
Ámbitos
Cada clave lleva la lista de lo que puede leer. Es una lista de permitidos: un ámbito nuevo que añadamos mañana no lo hereda ninguna clave existente. Pedir una ruta sin su ámbito responde 403 y no 404 — no tiene sentido esconder que la ruta existe cuando está documentada aquí.
traders:leer- Escaparate de traders publicados, su ficha y su rendimiento: curva, resultado por mes y exposición.
mercados:leer- Noticias del mercado y calendario económico.
No hay ámbito de señales, y es una decisión, no un olvido. Una señal se entrega a un cliente según el plan que paga, y una clave no es un cliente: dársela significaría o ninguna señal o todas, y «todas» sería regalar por una clave de socio lo que un cliente paga por el nivel más alto. Si tu caso necesita señales, hablemos del modelo de reventa; no se resuelve con un ámbito más.
Rutas
Todas relativas a la dirección base. Todas devuelven JSON.
| Ruta | Ámbito | Qué devuelve |
|---|---|---|
GET/publica/estado | — | Quién eres: nombre de la clave, ámbitos, caducidad y cuota consumida este minuto. |
GET/publica/traders | traders:leer | Escaparate paginado de traders publicados, con sus métricas. |
GET/publica/traders/{slug} | traders:leer | Ficha de un trader. |
GET/publica/traders/{slug}/rendimiento | traders:leer | Curva de capital, resultado por mes y exposición por símbolo. |
GET/publica/noticias | mercados:leer | Titular, nuestro resumen y enlace al medio original. |
GET/publica/calendario | mercados:leer | Eventos económicos con dato publicado, previsto y anterior. |
Aquí no hay ni una operación de escritura. No falta ninguna: no existe ninguna. Una credencial permanente, guardada en la configuración de un sistema sobre el que no tenemos control, con capacidad de mover algo, es la peor combinación posible — y en una plataforma de trading, «algo» puede ser dinero de un cliente.
Ejemplos
Pégalos tal cual con tu clave en la variable de entorno. Los nombres de campo son los que devuelve la API.
curl
curl -s https://luxor.algorvexa.com/api/v1/publica/estado \
-H "X-API-Key: $LUXOR_API_KEY"Python
import os
import httpx
CLAVE = os.environ["LUXOR_API_KEY"]
BASE = "https://luxor.algorvexa.com/api/v1/publica"
with httpx.Client(headers={"X-API-Key": CLAVE}, timeout=20) as cliente:
# Primero el estado: dice qué ambitos tiene esta clave y cuanta cuota queda.
estado = cliente.get(f"{BASE}/estado").raise_for_status().json()
print(estado["nombre"], estado["ambitos"])
r = cliente.get(f"{BASE}/traders", params={"page": 1, "page_size": 20})
if r.status_code == 429:
# Esperar, no reintentar en bucle. La cabecera Retry-After dice cuanto.
raise SystemExit(f"cuota agotada, reintentar en {r.headers['Retry-After']}s")
r.raise_for_status()
for trader in r.json()["traders"]:
# Las cifras solo se usan si la muestra las sostiene.
if trader["sample_sufficient"]:
print(trader["slug"], trader["win_rate"], trader["profit_factor"])
else:
print(trader["slug"], "muestra insuficiente")JavaScript
const CLAVE = process.env.LUXOR_API_KEY;
const BASE = "https://luxor.algorvexa.com/api/v1/publica";
async function pedir(ruta) {
const respuesta = await fetch(BASE + ruta, {
headers: { "X-API-Key": CLAVE },
});
if (respuesta.status === 429) {
const espera = Number(respuesta.headers.get("Retry-After") ?? 60);
throw new Error(`Cuota agotada. Reintentar en ${espera} s.`);
}
if (!respuesta.ok) {
const { detail } = await respuesta.json();
throw new Error(`${respuesta.status}: ${detail}`);
}
return respuesta.json();
}
const estado = await pedir("/estado");
console.log(estado.nombre, estado.ambitos);Errores
Todos llegan como JSON con un campo «detail» en lenguaje legible. Lo que importa de esta tabla no es el código: es si reintentar sirve de algo.
| Código | Qué pasó | Qué hacer |
|---|---|---|
401 | La clave no vale: no existe, está revocada o ha caducado. | No reintentar. Es el mismo error para los tres casos a propósito: distinguirlos permitiría averiguar qué claves existen probando. |
403 | La clave es válida pero le falta el ámbito de esa ruta. | No reintentar. Pídenos el ámbito. |
404 | No existe, o no es visible para tu organización. | No reintentar y no deducir que el identificador está mal escrito: un trader sin publicar responde igual que uno inexistente. |
422 | Un parámetro no valida. | Corregirlo. La respuesta trae la lista de campos con el motivo, y nunca el valor que mandaste. |
429 | Has gastado la cuota del minuto. | Esperar los segundos que diga la cabecera Retry-After. Reintentar en bucle sólo alarga el bloqueo. |
503 | Nos falta un dato indispensable para responder con honestidad. | Reintentar más tarde con espera creciente. Preferimos no responder que responder con datos que no tenemos. |
En un 422, «field» usa puntos para lo anidado y nunca viaja el valor que enviaste: un dato rechazado no puede acabar en los registros de un proxy por haberlo repetido en la respuesta.
Manda una cabecera X-Request-ID con cada petición. Te la devolvemos igual, y es lo que nos permite seguir tu petición concreta por nuestros registros cuando nos escribas. Si no la mandas, generamos una.
Cuota y límites
Hay dos, y ninguno sustituye al otro.
- Por clave: el tope de peticiones por minuto que lleva tu clave. Lo consultas en /publica/estado, en el campo «peticiones_este_minuto». Un cliente bien hecho frena antes de recibir el 429, no después.
- Por dirección IP: un límite en el frontal, antes de llegar a la aplicación. Admite ráfagas —una pantalla que pide seis cosas seguidas no lo nota— y para en seco un bucle sin espera.
- Los contadores van por minutos naturales y se reinician en el segundo cero de cada minuto. No es una ventana deslizante, así que puedes gastar la cuota al final de un minuto y otra entera al empezar el siguiente.
- Si tu integración necesita más, dilo antes de montarla. Subir el tope de una clave es un cambio de un minuto; descubrir el límite en producción un viernes no.
Lo que no está aquí
Preferimos decirlo antes de que lo busques. Una integración se planifica contra lo que hay, no contra lo que parece razonable que haya.
- Ninguna operación de escritura
- No se puede crear una cuenta, suscribir a nadie, abrir una posición ni modificar un stop. Y no está previsto: para lo que mueve dinero, la credencial de un tercero no es el camino.
- Ningún dato de clientes
- Ni sus cuentas, ni sus posiciones, ni sus correos, ni sus resultados. Una clave de socio no es una vía para leer a las personas que usan la plataforma.
- Las señales
- Por lo explicado arriba: están ligadas al plan que paga cada cliente y falta decidir cómo se revenden.
- Avisos hacia ti (webhooks)
- Hoy preguntas tú. Cuando los hagamos, irán firmados, con reintentos y con cola: un aviso a ciegas que se pierde en el primer corte de red es peor que no avisar, porque nadie se enteraría de que se perdió.
- El resto de la API
- Existe, y no sale de nuestra red. El navegador nunca habla con ella: habla con el panel, y el panel le habla desde dentro. No publicamos su documentación interactiva por lo mismo.
Un caso aparte: el bot de MetaTrader 5
Si lo que buscabas es el bot que opera en tu cuenta, eso no es esta API. El bot se descarga ya configurado desde tu panel y se instala con doble clic: no hace falta programar nada ni usar ninguna clave. Su protocolo es interno y su credencial la emite el propio instalador, ligada a una sola cuenta de MetaTrader 5.
Pedir una clave
Escríbenos diciendo quién eres, qué vas a mostrar y en qué ámbitos. Respondemos con la clave, sus ámbitos y su caducidad.