API para desarrolladores
Cómo emitir una clave API y llevar los datos de SpreadFighter a sus propios programas: REST con la cabecera X-API-KEY, flujos NATS por websocket, subjects por plan y límites. Las claves están disponibles en Pro y Max.
Qué es
Los datos que ve en el dashboard — screeners, indicadores, el order book, el funding, los flujos de los exchanges — se pueden llevar a sus propios programas: un bot, una hoja de cálculo, su propio servidor. Para ello necesita una clave API. La misma clave sirve tanto para REST como para los flujos NATS.
La documentación completa está en la página API access de la aplicación. Se abre después de iniciar sesión y tiene las secciones Start, REST, NATS, Subjects & plans y Limits. Este artículo es un resumen breve; consulte allí las listas de endpoints y de subjects: vienen del servidor y siempre están actualizadas.
Planes
| Plan | API |
|---|---|
| Free | No: no se puede emitir una clave |
| Pro | Sí: REST y los subjects NATS de su plan |
| Max | Sí: REST y los subjects NATS de su plan |
El plan se comprueba cada vez que se usa la clave, no solo al emitirla. Si su suscripción termina o su plan baja a Free, la clave deja de funcionar por sí sola; no hace falta revocarla. Un cambio de plan llega a la verificación de la clave en aproximadamente un minuto.
Cómo obtener una clave
- Abra su perfil: avatar en la esquina superior derecha → Profile.
- Busque la tarjeta API keys.
- Escriba un nombre para la clave, por ejemplo «bot en mi servidor», y haga clic en Issue key.
- Copie la clave con el botón Copy y haga clic en I saved it.
La clave completa se muestra una sola vez, en el momento de emitirla. Solo guardamos su hash, por lo que la clave no se puede recuperar. Si la pierde, emita una nueva y revoque la anterior.
Una clave tiene este aspecto: sf_live_<id de usuario>_<id de clave>_<secreto>.
La lista de claves muestra el nombre, el id de la clave, la fecha de creación, el último uso y el estado: active, revoked o expired. Revoque una clave que ya no necesite con el botón Revoke. El enlace How to connect de la tarjeta lleva a la página de documentación.
REST
REST sirve para consultas bajo demanda: historial, instantáneas, datos de referencia. La clave se envía solo en la cabecera X-API-KEY. No se acepta como parámetro de la URL ni en el cuerpo de la solicitud: así no queda en los logs de proxies ni en el historial del navegador.
curl -H "X-API-KEY: sf_live_..." \
"https://core-api.hel1.prod.hz.spreadfighter.cloud/api/hftActivities?symbol=BTCUSDT&timeFrame=1m&limit=10"
| Host | Datos |
|---|---|
https://core-api.hel1.prod.hz.spreadfighter.cloud | Señales, indicadores, screeners |
https://depth-api.hel1.prod.hz.spreadfighter.cloud | Order book |
https://funding-api.hel1.prod.hz.spreadfighter.cloud | Funding |
La lista completa de endpoints con sus parámetros está en el Swagger del servicio de señales. Los otros dos servicios no tienen Swagger.
NATS
NATS transmite datos en tiempo real. La conexión se hace por websocket a wss://nats-ws.hel1.prod.hz.spreadfighter.cloud, y la misma clave se pasa como token. Su biblioteca cliente debe admitir la autenticación por token: en @nats-io/nats-core es el campo token, en nats.go la opción nats.Token.
import { wsconnect } from "@nats-io/nats-core";
const nc = await wsconnect({
servers: ["wss://nats-ws.hel1.prod.hz.spreadfighter.cloud"],
token: "sf_live_...",
});
const sub = nc.subscribe("sf.core.scripts.screener.marketPower.1m.all.dict");
for await (const m of sub) {
console.log(m.json());
}
Hay un ejemplo en Go en la página de documentación.
Subjects
Los nombres de los subjects siguen esta forma:
| Patrón | Qué es |
|---|---|
sf.core.scripts.screener.<nombre>.> | Cálculos de los screeners |
binance.futures.<flujo>.> | Flujos de los exchanges |
private.<su-uid>.> | Sus propios eventos |
- El signo
>cubre todo el resto del subject;*cubre exactamente un segmento. - Suscribirse a un subject fuera de su plan no da error: simplemente no llegan datos.
- Solo puede publicar en su propio espacio
private.<su-uid>. No está permitido escribir en los flujos compartidos.
La sección Subjects & plans de la página de documentación muestra qué subjects abre cada plan. La lista viene del servidor, del mismo lugar que concede los permisos de conexión. Los subjects que su plan no incluye aparecen atenuados.
Límites
| Qué | Límite |
|---|---|
| Claves | Hasta 10 claves activas por cuenta. Las revocadas no cuentan |
| Revocación de una clave | Surte efecto en aproximadamente un minuto: la verificación de la clave se guarda en caché. Si una clave está comprometida, cuente con que sigue funcionando hasta un minuto |
| Cambio de plan | Llega a la verificación de la clave en aproximadamente un minuto |
| Lectura lenta de NATS | Si un suscriptor se queda atrás, el servidor acumula hasta 64 MB de datos y corta la conexión |
| Reconexiones a NATS | Las conexiones frecuentes de un mismo usuario están limitadas: 12 por minuto de media, hasta 30 seguidas |
Para no chocar con el límite de lectura, suscríbase de forma puntual en lugar de a todo a la vez, y no haga trabajo pesado dentro del manejador de mensajes: ponga los mensajes en una cola y procéselos por separado.
Artículos relacionados
- Cuenta personal — perfil, plan y la tarjeta de claves API.
- Cómo elegir un plan — qué incluyen Pro y Max.