# Inteligencia y simulaciones de MarketLabs

URL: https://docs.fxapis.com/es/guides/marketlabs

> Lee una instantánea compartida del mercado y encola una simulación privada con la misma clave de fxapis. Las simulaciones se consultan. No envían una orden.



> **MarketLabs llegará pronto.** Todavía no está disponible para los
> workspaces: hasta entonces sus endpoints responden `404 NOT_FOUND` y no
> aparece en la consola. Esta guía describe cómo funcionará.

MarketLabs es parte de fxapis. Usas el mismo panel, la misma sesión y la misma clave. Un plan que no incluye MarketLabs se rechaza con `402 FEATURE_NOT_IN_PLAN`. Una clave sin el alcance se rechaza con `403 MISSING_SCOPE`.

| Alcance           | Permite                                                                       |
| ----------------- | ----------------------------------------------------------------------------- |
| `marketlabs:read` | Inteligencia, eventos, pronósticos, desempeño, uso y tus propias simulaciones |
| `marketlabs:run`  | Encolar y cancelar tus propias simulaciones                                   |

`marketlabs:manage` no se puede conceder a una clave. Pertenece al dueño del espacio.

Leer inteligencia no inicia una simulación y no gasta la cuota de lectura en vivo de una cuenta conectada. Una simulación es privada del espacio que la creó. El id de otro espacio es `404`.

## Leer una instantánea [#leer-una-instantánea]

```bash
curl "https://api.fxapis.com/v1/marketlabs/markets/EURUSD/intelligence" \
  -H "Authorization: Bearer $FXAPIS_KEY"
```

El cuerpo está bajo `data`, con `asOf`, `freshness` (`fresh` o `stale`) y `baseline` como texto decimal. Las horas son UTC.

## Encolar una simulación [#encolar-una-simulación]

Envía `Idempotency-Key`. La misma clave y el mismo cuerpo devuelven la primera simulación. La misma clave y un cuerpo distinto es `409 IDEMPOTENCY_KEY_REUSED`.

```bash
curl -X POST "https://api.fxapis.com/v1/marketlabs/simulations" \
  -H "Authorization: Bearer $FXAPIS_KEY" \
  -H "Idempotency-Key: research-20261104-eurusd-01" \
  -H "Content-Type: application/json" \
  -d '{"instrument":"EURUSD","horizon":"4h","configuration":{"personas":20,"repetitions":3}}'
```

La respuesta es `202`, con `data.id` y `data.pollUrl`. Consulta `GET /v1/marketlabs/simulations/{id}` hasta que `status` sea `succeeded`, `failed` o `cancelled`. `DELETE` cancela una simulación en cola y libera su crédito. Una simulación ya terminada es `409 SIMULATION_NOT_CANCELLABLE`.

`GET /v1/marketlabs/usage` informa `included`, `reserved` y `used` del mes UTC en curso. Pasado el incluido, crear una es `402 QUOTA_EXCEEDED`. Si MarketLabs no puede aceptar la solicitud, la respuesta es `503 MARKETLABS_UNAVAILABLE`. Las rutas de trading no se ven afectadas.

Una simulación nunca envía una orden. Cerrar una posición es una llamada aparte, con un alcance de trading, sobre una cuenta que elijas.