Conecta cuentas de MT5 con login, contraseña y servidor

Conectar una cuenta de MT5 requiere tres datos de su dueño —el login, la contraseña de trading y el nombre del servidor— y una llamada a la API. Tener bien esos tres datos, y manejar la contraseña con cuidado en el camino, es la mayor parte de lo que hace funcionar una pantalla de conexión. Esta guía cubre ambas cosas. fxapis funciona con cualquier broker o prop firm de MT5, demo o real; lo que cambia entre brokers está en Compatibilidad con brokers.

curl -sS -X POST "https://api.fxapis.com/v1/accounts" \
  -H "Authorization: Bearer $FXAPIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "login": "81234567",
    "server": "VantageMarkets-Live",
    "password": "the-trading-password",
    "mode": "warm_on_demand",
    "label": "member_4821"
  }'

201 devuelve la cuenta con su id y state: "created". Todavía no inicia sesión: eso ocurre cuando la cuenta se pone en línea por primera vez, y por eso conviene comprobar las credenciales de inmediato. Referencia: Connect an MT5 account.

Los tres datos que necesitasCopiar el enlace

LoginCopiar el enlace

El número de cuenta de MT5, solo dígitos, enviado como string: "81234567". Un login con cualquier cosa que no sean dígitos se rechaza con 400 INVALID_REQUEST. No es una dirección de correo ni el nombre de usuario en el portal de clientes del broker: muchos brokers tienen ambos, y la gente los confunde.

Contraseña: de trading, no de inversorCopiar el enlace

Cada cuenta de MT5 tiene dos contraseñas:

La contraseña de inversor es el error clásico, porque al principio nada falla. La cuenta llega a ready y su primera orden se rechaza. Pide la contraseña de trading con ese nombre en tu pantalla de conexión, y explica por qué.

Servidor: exactamente como lo muestra MetaTraderCopiar el enlace

El nombre del servidor identifica el servidor de trading del broker donde vive la cuenta: VantageMarkets-Demo, VantageMarkets-Live, ICMarkets-Live02. Debe coincidir exactamente, incluidas mayúsculas, guiones y cualquier número al final.

Dónde puede encontrarlo el dueño de la cuenta:

• MetaTrader 5 en el escritorio: la ventana Navigator lista cada cuenta con su servidor; el diálogo de inicio de sesión (File → Login to Trade Account) también lo muestra.
• MetaTrader 5 en el móvil: la pantalla de la cuenta, en la configuración de la app, muestra el servidor debajo del número de cuenta.
• El correo de la cuenta del broker: los brokers envían el login y el servidor cuando se abre una cuenta.

Consejos sobre los nombres que vale la pena poner en tu pantalla de conexión:

• Real y demo son servidores distintos. Las cuentas …-Demo y …-Live no se pueden intercambiar.
• Los servidores numerados son servidores distintos. …-Live02 no es …-Live, y una cuenta existe exactamente en uno de ellos.
• Un broker puede tener varias marcas y regiones, cada una con sus propios servidores. El servidor de la cuenta es aquel en el que se abrió, no el de la página principal del broker.
• Recorta lo que escribe el usuario. Un espacio al final, por copiar y pegar, es otro nombre de servidor. Guardamos el valor exactamente como se envía.
• Ofrece sugerencias, pero acepta lo que se escribió. GET /v1/brokers/servers?q= busca en el catálogo de servidores de brokers mientras el usuario escribe —primero vienen los servidores en los que ya inician sesión cuentas en fxapis—, así que un autocompletado atrapa la mayoría de los errores de escritura. Aun así, los brokers agregan y renombran servidores, así que nunca obligues a elegir de la lista: un servidor que no aparece se puede conectar igual. Consulta Cuentas para la búsqueda.
• Un servidor equivocado se puede corregir sobre la marcha. Cuando un inicio de sesión falla en el servidor indicado, problem.otherServers de la cuenta sugiere alternativas probables, y POST /v1/accounts/{id}/server mueve la cuenta al correcto, probando ahí la contraseña guardada: no se vuelve a enviar.

Elegir un modoCopiar el enlace

mode decide cuándo está en línea la cuenta. El valor predeterminado es cold, así que defínelo:

Puedes cambiarlo después con POST /v1/accounts/{id}/mode. Consulta Cuentas → Modos.

Manejar las credenciales en tu appCopiar el enlace

La contraseña de MT5 es la llave del dinero de alguien. fxapis la cifra al recibirla con una clave única para esa cuenta, nunca la devuelve en ningún endpoint y la borra cuando la cuenta se desconecta; consulta Seguridad. Tu parte del trabajo es asegurarte de que pase por tus sistemas sin dejar rastro:

• Envíala desde tu backend, directo a fxapis, en la misma solicitud que la recibió. Tu API key nunca debe estar en un navegador ni en una app móvil, así que el formulario envía a tu servidor y tu servidor llama a POST /v1/accounts.
• Nunca la guardes: ni en tu base de datos, ni en una caché, ni en un trabajo de una cola, ni en un evento de analítica, ni en un ticket de soporte. Guarda en su lugar el id de la cuenta de fxapis; es todo lo que necesitas a partir de ahí.
• Nunca la registres en logs. Desactiva el registro del cuerpo de las solicitudes en la ruta de conexión, y asegúrate de que las herramientas de reporte de errores no capturen el cuerpo cuando la llamada falla.
• Solo por HTTPS, y nunca en una URL ni en un query string, donde los proxies y los navegadores guardan copias.
• No reintentes la llamada de conexión desde un trabajo en segundo plano. Eso significaría guardar la contraseña para reintentar después. Si fxapis responde 503 SECRET_STORE_UNAVAILABLE, no se creó nada: reintenta un par de veces en la misma solicitud y luego pide al usuario que lo intente de nuevo.

# fxapis = httpx.Client(base_url="https://api.fxapis.com", headers={"Authorization": f"Bearer {KEY}"})
@app.post("/connect-mt5")
def connect_mt5(form: ConnectForm, user: User):
    response = fxapis.post("/v1/accounts", json={
        "login": form.login.strip(),
        "server": form.server.strip(),
        "password": form.password,          # used once, here, and never kept
        "mode": "warm_on_demand",
        "label": f"user_{user.id}",
    }, timeout=30)
    if response.status_code == 409:         # ACCOUNT_EXISTS: already connected in your workspace
        return {"error": "This account is already connected."}
    response.raise_for_status()
    account = response.json()["data"]
    user.fxapis_account_id = account["id"]  # the id, not the password
    fxapis.post(f"/v1/accounts/{account['id']}/warm")
    return {"accountId": account["id"]}

Un login y un servidor se pueden conectar una vez por workspace. Un segundo intento devuelve 409 ACCOUNT_EXISTS: dos conexiones significarían dos lugares capaces de operar el mismo dinero. Si dos de tus usuarios reclaman la misma cuenta de MT5, es un asunto para tu equipo de soporte, no para un reintento.

Conectar más cuentas de las que permite tu plan devuelve 402 QUOTA_EXCEEDED. Otros tres 402 vienen del plan, antes de que la contraseña vaya a ningún lado: FEATURE_NOT_IN_PLAN para always_on en un plan que no lo incluye y, en una prueba, DEMO_ONLY para una cuenta real y TRIAL_ACCOUNT_USED para un login demo que otra prueba ya usó.

Comprueba las credenciales de inmediatoCopiar el enlace

Una cuenta nueva todavía no ha iniciado sesión. Si esperas a su primera operación para descubrir que la contraseña está mal, el fallo llega en el peor momento. Ponla en línea mientras el usuario todavía está en la pantalla de conexión:

1. POST /v1/accounts/{id}/warm: responde 202 de inmediato.
2. Consulta GET /v1/accounts/{id}/status cada dos segundos hasta que state sea ready o un estado que requiere atención. Unos 10 segundos según nuestra medición; deja hasta dos minutos.
3. Muestra el resultado.

const NEEDS_ATTENTION = ["invalid_credentials", "trading_disabled", "needs_2fa", "needs_certificate"];

async function checkCredentials(accountId: string): Promise<string> {
  const deadline = Date.now() + 120_000;
  while (Date.now() < deadline) {
    const res = await fetch(`${API}/v1/accounts/${accountId}/status`, { headers: { Authorization: `Bearer ${KEY}` } });
    const { data } = await res.json();
    if (data.state === "ready" || NEEDS_ATTENTION.includes(data.state)) return data.state;
    await new Promise((r) => setTimeout(r, 2000));
  }
  return "timeout";
}

En tu interfaz, consulta tu propio backend desde el navegador, y deja que el backend llame a fxapis. Una vez hecha la comprobación, una cuenta warm_on_demand se vuelve a desconectar sola tras 15 minutos; no hace falta nada más.

Los estados que requieren atenciónCopiar el enlace

Los cuatro primeros no se arreglan solos, y los inicios de sesión fallidos repetidos son la forma en que un broker bloquea una cuenta. Por eso fxapis deja de intentarlo: poner en línea una cuenta así devuelve 409 NEEDS_OPERATOR, y prepare lo informa como needs_operator, sin contactar al broker. No metas estos estados en un bucle de reintentos. Todos los estados están en Cuentas → Estados.

Corregir las credencialesCopiar el enlace

Cuando una contraseña estaba mal, o el miembro la cambió en el broker, reemplázala en la cuenta existente: su id, su historial y su configuración se conservan:

curl -sS -X POST "https://api.fxapis.com/v1/accounts/$ACCOUNT_ID/password" \
  -H "Authorization: Bearer $FXAPIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "the-members-corrected-password" }'

Agrega "server" para corregir el nombre del servidor al mismo tiempo. Cualquier terminal en marcha se detiene primero y se espera a que termine (se rechaza con 409 ACCOUNT_EXECUTING mientras hay una orden en curso), se guarda la contraseña nueva y solo entonces se borra la anterior. Funciona en cualquier estado de la cuenta, incluso mientras está en línea. La cuenta queda en created: ponla en línea de inmediato y consulta su estado, exactamente como en la pantalla de conexión, para que el miembro sepa enseguida si la nueva contraseña funciona.

Un login que se desconectó también se puede volver a conectar sin más con POST /v1/accounts: vuelve la misma cuenta con la contraseña nueva, y la respuesta es 200 en lugar de 201.

DesconectarCopiar el enlace

curl -sS -X POST "https://api.fxapis.com/v1/accounts/$ACCOUNT_ID/disconnect" \
  -H "Authorization: Bearer $FXAPIS_KEY"

disconnect desconecta la cuenta y borra la contraseña guardada de inmediato; la respuesta dice "credentialsRemoved": true. El registro de la cuenta y todo su historial de trading se conservan, en estado offline, para tus registros y para cualquier disputa. Llámalo cuando un usuario quita su cuenta o deja tu producto: una contraseña que ya no necesitas es una que nadie debería seguir guardando.

Si solo quieres la cuenta fuera de línea por ahora, usa POST /v1/accounts/{id}/cool en su lugar: conserva la contraseña para que la cuenta pueda volver. Las posiciones abiertas no se tocan en ninguno de los dos casos; los stop loss y take profit viven en el broker y siguen funcionando.

EliminarCopiar el enlace

curl -sS -X DELETE "https://api.fxapis.com/v1/accounts/$ACCOUNT_ID" \
  -H "Authorization: Bearer $FXAPIS_KEY"

Eliminar quita la cuenta y su historial para siempre: para un usuario que pidió ser olvidado, o para un registro creado con el nombre de servidor equivocado. La respuesta lista cuántas órdenes, deals y posiciones se fueron con ella. Se rechaza mientras hay una orden en curso (ACCOUNT_EXECUTING), mientras una orden multicuenta que la incluye no ha terminado (ACCOUNT_IN_WAVE), y mientras nuestra última revisión encontró posiciones abiertas (ACCOUNT_HAS_POSITIONS): ciérralas primero, o agrega ?force=true para eliminarla con ellas todavía abiertas en el broker. El mismo login y servidor se pueden volver a conectar después, como una cuenta nueva.

Conectar muchas cuentasCopiar el enlace

• Conecta las cuentas con una llamada cada una, a medida que los usuarios se registran.
• Pon en línea hasta 200 en una llamada con POST /v1/accounts/prepare; cada una recibe su propio resultado (starting, already_running, needs_operator…).
• GET /v1/accounts lista cada cuenta con su state, así que un trabajo nocturno puede encontrar las que requieren atención y avisar a sus dueños.

RelacionadoCopiar el enlace

• Señales y click-to-trade: una integración completa de cara a los miembros.
• Compatibilidad con brokers: cualquier broker de MT5, y lo que cambia entre ellos.
• Cuentas: modos, estados y cada endpoint del ciclo de vida.
• Seguridad: cómo se guardan y se borran las contraseñas.
• Guías por lenguaje: Python, Node.js, PHP, C#, Go, Java, Ruby.