Documentación de la API de CoinScanX

Introducción

Bienvenido a la API de CoinScanX. Esta interfaz te permite acceder a los datos de nuestro scanner de análisis de criptomonedas, incluyendo el Top 10 y el período de gracia.

También puedes conectar el scanner directamente con Claude, ChatGPT y otras IAs vía nuestro servidor MCP en mcp.coinscanx.com.

Autenticación

Todas las solicitudes a endpoints de datos requieren una clave de API (apikey). Puedes usar la siguiente clave para realizar pruebas con datos de demostración.

Clave de API para pruebas: H7jK8mN9pQ0rS1tU2vW3xY4z

La clave puede enviarse de tres formas equivalentes:

Query string: ?apikey=TU_KEY
Header: X-API-Key: TU_KEY
Header: Authorization: Bearer TU_KEY

Límites de Uso

Tráfico autenticado (con apikey): máximo 30 solicitudes por minuto por clave, sin importar desde cuántas IPs.

Tráfico anónimo (sin apikey, ej: /health): máximo 5 solicitudes por minuto por IP.

El cupo es por clave, así que si usas la misma key desde varios dispositivos o desde Claude/ChatGPT vía MCP, todas las llamadas suman al mismo cubo. Si excedes el límite, recibirás un error 429 Too Many Requests.

Recomendación: cachea las respuestas en tu cliente al menos 10-15 segundos. Los datos del scanner no cambian más rápido que eso.

Endpoints

GET /v3/top10

Devuelve la lista de las criptomonedas con mayor probabilidad de subida.

Parámetros

Parámetro	Descripción	Default
`apikey`	Tu clave de API. (Requerido)	-
`original`	Poner en `on` para obtener el orden original del top.	(off)
`sort`	Orden por fecha (si `original` no se usa): `asc` o `desc`.	desc
`limit`	Número de resultados (1-10).	10
`format`	Formato de respuesta: `json` o `xml`.	json

Ejemplo de Solicitud (Orden Original)

https://api.coinscanx.com/v3/top10?apikey=H7jK8mN9pQ0rS1tU2vW3xY4z&original=on

GET /v3/periodo-gracia

Devuelve las monedas que han salido del Top 10 en las últimas 24 horas.

Parámetros

Parámetro	Descripción	Default
`apikey`	Tu clave de API. (Requerido)	-
`sort`	Orden por fecha de salida: `asc` o `desc`.	desc
`limit`	Número de resultados (Máx: 200).	10
`format`	Formato de respuesta: `json` o `xml`.	json

Ejemplo de Solicitud

https://api.coinscanx.com/v3/periodo-gracia?apikey=H7jK8mN9pQ0rS1tU2vW3xY4z

GET /v3/health

Verifica que la API esté operativa. La clave es opcional.

Comportamiento del rate limit

Sin clave: aplica el límite por IP (5/min). Útil para uptime monitors externos.
Con clave válida: aplica el límite por clave (30/min). Útil cuando un servicio (ej: nuestro MCP server) llama /health en nombre de muchos usuarios desde un solo IP.

Ejemplo de Solicitud

https://api.coinscanx.com/v3/health

Estructura de la Respuesta

A continuación un ejemplo de la estructura de un objeto de moneda en /top10.

{
    "rank": 1,
    "symbol": "SNX",
    "name": "Synthetix Network",
    "initial_price_usd": 0.928,
    "current_price_usd": 1.084,
    "max_price_usd": 1.25,
    "max_increase_percentage": 34.69,
    "current_increase_percentage": 16.81,
    "in_top_since": "2026-04-04T02:00:11+00:00",
    "in_top": true,
    "volumen24h": 15000000.50,
    "last_updated": "2026-05-09T17:42:00+00:00"
}

Y un ejemplo de un objeto en /periodo-gracia.

{
    "symbol": "PEPE",
    "name": "Pepe",
    "initial_price_usd": 0.0000087,
    "current_price_usd": 0.0000094,
    "max_price_usd": 0.0000110,
    "max_increase_percentage": 26.43,
    "current_increase_percentage": 8.05,
    "in_top_since": "2026-05-01T10:15:00+00:00",
    "exit_date": "2026-05-09T08:30:00+00:00",
    "in_top": false,
    "volumen24h": 320000000.00,
    "last_updated": "2026-05-09T17:42:00+00:00"
}

Campo	Descripción
`rank`	Posición en el Top (solo en `/top10`).
`symbol`	Símbolo de la criptomoneda (ej: BTC).
`name`	Nombre completo de la criptomoneda.
`initial_price_usd`	Precio en USD al entrar al Top.
`current_price_usd`	Nuevo en v3.9.1. Precio actual en USD según la última actualización del scanner. Puede ser `null` en monedas muy antiguas registradas antes de v3.9.
`max_price_usd`	Precio máximo en USD alcanzado desde la entrada al Top.
`max_increase_percentage`	Máximo % de subida desde el precio inicial.
`current_increase_percentage`	Nuevo en v3.9.1. % calculado de subida actual desde el precio inicial: `(current - initial) / initial × 100`. Puede ser negativo si el precio bajó. Puede ser `null` si falta `current_price_usd`.
`in_top_since`	Fecha (UTC) de entrada al Top.
`exit_date`	Fecha (UTC) de salida del Top (solo en `/periodo-gracia`).
`in_top`	Booleano (`true`/`false`) indicando si está actualmente en el Top.
`volumen24h`	Volumen de trading en USD de las últimas 24h. Se actualiza con cada barrido del scanner tanto en `/top10` como en `/periodo-gracia` (campo añadido a `/periodo-gracia` en v3.9.1).
`last_updated`	Nuevo en v3.9.1. Fecha (UTC) de la última vez que el scanner refrescó los datos de esta moneda.

Errores Comunes

Código HTTP	Descripción
`401 Unauthorized`	La clave de API es inválida, está inactiva (membresía vencida) o no fue proporcionada.
`404 Not Found`	El endpoint solicitado no existe.
`429 Too Many Requests`	Has excedido el límite de solicitudes.
`500 Internal Server Error`	Ocurrió un error en nuestro servidor.