Redes

Cómo selecciona una red cada interfaz de Nexus Exchange, ya sea testnet, mainnet, local o un destino personalizado que describes tú mismo.

Cada interfaz de Nexus Exchange se comunica con exactamente una red, que se elige al construir el cliente. Una red no es un canal de versiones. Decide de quién es el dinero que está en juego. Testnet usa fondos de prueba sintéticos, mainnet usará fondos reales y local es para desarrollo. Seleccionar una agrupa todo lo que difiere entre ellas: los destinos REST y WebSocket, si existe un faucet y el dominio de firma al que se limitan tus solicitudes. Eliges una red en lugar de armar una URL. Para las URL base actuales, consulta APIs y límites de solicitudes.

Esas tres son las redes publicadas. Un despliegue que ejecutas tú mismo es una red Custom. Lleva el mismo conjunto, pero lo describes tú en lugar de que lo resuelva el cliente.

Las tres redes publicadas

Red	Fondos	Faucet	Disponibilidad
testnet	USDX sintético sin valor en el mundo real	Sí	En vivo hoy. La predeterminada en todas las interfaces.
mainnet	Fondos reales, como USDX transferido por el puente desde Ethereum Mainnet	No	Se lanzará con el Exchange de fondos reales. Todavía no es accesible; ver más abajo.
local	Sintéticos, contra un indexador que ejecutas tú mismo	Sí	Para desarrollo local. No es una red pública.

Testnet es la predeterminada en todas partes a propósito, porque usar fondos reales de forma predeterminada no sería seguro.

Mainnet todavía no es accesible. Su host público no está activo, así que ninguna interfaz resuelve un destino de mainnet por ti. En lugar de enviar tus solicitudes a algún lugar plausible pero incorrecto, cada una falla cerrada. Los clientes de Python y TypeScript lanzan un error al construirse, y el servidor MCP se niega a arrancar. El cliente de Rust (y por lo tanto la CLI) se construye sin problemas, pero rechaza cada solicitud localmente, antes de que salga ningún byte del proceso. La única forma de pasar es nombrar tú mismo el destino. Python, TypeScript y el servidor MCP aceptan mainnet cuando viene con una URL base explícita (consulta Cómo apuntar a un host sin describirlo), que es la forma de llegar a un despliegue con fondos reales antes de que el host definitivo esté activo. En Rust, la anulación es un constructor aparte que no lleva ninguna red, así que apunta a una URL en lugar de a mainnet. Ninguna interfaz adivina un destino con fondos reales por ti, porque esa falla no se puede ensayar. Cuando se lance mainnet, esta página y las notas de versión de cada interfaz lo dirán.

Cómo seleccionar una red

Interfaz	Seleccionar una red	Predeterminada
Python	Client(network=Network.TESTNET)	testnet
TypeScript	new Client({ network: Network.Testnet })	testnet
Rust	Config::new(Network::Testnet)	testnet
CLI	--network <mainnet|testnet|local|LABEL>, o NEXUS_NETWORK	testnet
Servidor MCP	NEXUS_EXCHANGE_NETWORK	testnet

El --network de la CLI también acepta la etiqueta de un destino personalizado declarado en su archivo de configuración, y el servidor MCP acepta NEXUS_EXCHANGE_NETWORK=custom junto con un conjunto descrito. Consulta Cómo describir un destino personalizado.

Un nombre de red no reconocido siempre es un error. Ninguna interfaz recurre a un valor predeterminado, y ninguna recurre a local. Las interfaces tratan un identificador desconocido como fondos reales hasta que se demuestre lo contrario, así que debes corregirlo. Los nombres de canales de versiones retirados se rechazan con una indicación de su reemplazo. stable nombraba un host que sirve testnet, así que testnet es su equivalente directo.

Ejemplo

from nexus_exchange import Client, Network

client = Client(network=Network.TESTNET, api_key=..., api_secret=...)

import { Client, Network } from "@nexus-xyz/exchange-ts";

const client = new Client({ network: Network.Testnet, apiKey: "…", apiSecret: "…" });

use nexus_exchange::{Config, Network};

let config = Config::new(Network::Testnet);

nexus --network local markets

La red Custom

Las tres redes de arriba son las publicadas. Un despliegue que ejecutas tú mismo, como un entorno privado de staging, un entorno de vista previa o un indexador en tu propia infraestructura, es una red Custom. Es un cuarto tipo de destino que describes tú, no una URL agregada a una de las tres.

Es una red y no una dirección porque un despliegue privado sigue necesitando todo lo que agrupa una red con nombre, y una URL no aporta nada de eso. Custom lleva el mismo conjunto, aportado por ti:

Parte del conjunto	Quién la aporta
Base REST	Tú. Obligatoria.
Base directa /api/v1	Tú, cuando el despliegue la separa de la base REST. Por defecto es la base REST, que es donde la sirve un despliegue de un solo host.
Origen de WebSocket	Tú, en las interfaces que permiten que un despliegue lo separe. El SDK de Rust y la CLI nunca derivan uno, porque derivarlo emparejaría un token de stream con un origen que no lo generó. Consulta la nota sobre los conjuntos de campos.
Fondos	Tú. Obligatorio, sin valor predeterminado. Ver más abajo.
Faucet	Tú. Se supone ausente hasta que se declare, para que una llamada de fondeo no pueda dirigirse a un faucet que no existe.
Dominio de firma	Se lee del GET /metadata de este despliegue, o lo aportas tú. Nunca se adivina.
Etiqueta	Tú. Obligatoria, porque es el espacio de nombres de las credenciales.

Los fondos son un valor obligatorio de tres estados

funds es real, play o unknown, y no tiene valor predeterminado. No es seguro suponer ninguna de las dos respuestas booleanas. Un despliegue de staging del Exchange de fondos reales se comporta como fondos reales, y un entorno de vista previa con datos de producción detrás no es dinero de prueba solo porque no sea el host publicado. Solo el operador lo sabe.

unknown falla cerrado. Es una respuesta legítima, ya que puede que no lo sepas, y decirlo es mejor que adivinar. En ese caso, las interfaces rechazan las operaciones protegidas por fondos reales en lugar de dejarlas pasar. Si un comando o una herramienta que mueve valor se niega en un destino personalizado, un funds sin declarar es lo primero que hay que revisar.

La etiqueta es obligatoria, y es un espacio de nombres de credenciales

Cada destino Custom lleva una etiqueta que elige quien llama, limitada a [A-Za-z0-9._-] con un máximo de 64 caracteres. . y .. se rechazan directamente. También los nombres a los que ya responden las redes integradas (mainnet, testnet, local y el propio custom), que son válidos según ese conjunto de caracteres, pero que al nombrarlos direccionarían las credenciales de otro destino.

La etiqueta es la clave bajo la que se organizan tus credenciales guardadas, así que llega al sistema de archivos en los clientes que guardan configuración. Una etiqueta sin validar que contenga / o .. es un path traversal, y la credencial a la que apuntaría pertenece a otro destino. El conjunto de caracteres y el tope de longitud se aplican en todas las interfaces, y cada una los aplica por su cuenta en lugar de heredarlos. El servidor MCP no está construido sobre el SDK de Rust y tiene su propia copia de la regla. Los nombres reservados son la única parte que todavía no es uniforme. El SDK de Rust y la CLI rechazan el nombre de una red integrada, y el servidor MCP no. Elige una etiqueta que no coincida con ninguno de ellos en lugar de confiar en que el rechazo lo detecte.

Tú eliges las etiquetas en tu propia configuración. dev, preview y example están bien.

El dominio de firma nunca se adivina

Un destino Custom no hereda un dominio de firma de ningún lado. El cliente lee el chain id de EIP-712 del propio GET /metadata del despliegue, o toma el que le aportes. Si no tiene ninguno de los dos, se niega a firmar en lugar de reutilizar un valor de otra red.

Entiende esta regla antes de toparte con ella, porque la falla opuesta es silenciosa. Una firma hecha con el dominio incorrecto puede ser válida en otra red. Negarse es la única respuesta segura.

Cómo apuntar a un host sin describirlo

Todas las interfaces siguen aceptando una URL base simple:

Interfaz	URL base simple
Python	base_url=, más direct_base_url= para la base directa
TypeScript	baseUrl
Rust	Config::with_base_url(…), más .with_direct_base_url(…)
CLI	--base-url <URL>, o NEXUS_BASE_URL
Servidor MCP	NEXUS_EXCHANGE_API_URL

Este es el atajo, no la vía documentada. En el servidor MCP está formalmente deprecado. Sigue funcionando sin cambios, pero muestra un aviso que remite al conjunto. Una URL simple construye un destino Custom con fondos sin declarar y sin dominio de firma, así que las operaciones protegidas por fondos reales se rechazan y el cliente no firmará. Eso alcanza para echar un vistazo de solo lectura a un host, y a propósito no alcanza para operar contra él.

Para hacer algo más que leer, describe el destino en lugar de nombrar una dirección.

Cómo describir un destino personalizado

Dos interfaces toman un conjunto completo desde la configuración en lugar de desde los argumentos del constructor.

Servidor MCP. Define NEXUS_EXCHANGE_NETWORK=custom y luego:

Variable	Significado
NEXUS_EXCHANGE_API_URL	Base REST. Obligatoria.
NEXUS_EXCHANGE_NETWORK_LABEL	La etiqueta. Obligatoria.
NEXUS_EXCHANGE_FUNDS	real, play o unknown. Obligatoria.
NEXUS_EXCHANGE_FAUCET	Si existe un faucet aquí. Si falta, significa que no.
NEXUS_EXCHANGE_GATEWAY_PATH	Dónde está la ruta del gateway bajo el origen: /api/exchange (predeterminada) o / para un indexador simple.

Definir cualquiera de estas sin NEXUS_EXCHANGE_NETWORK=custom es un error, no algo que se ignora en silencio. Medio conjunto aplicado sin avisar te haría creer que configuraste una propiedad de seguridad que no está en vigor.

CLI. Declara el destino en custom_networks en su archivo de configuración ($XDG_CONFIG_HOME/nexus/config.json, con ~/.config/nexus/config.json como alternativa) y selecciónalo por su etiqueta:

{
  "custom_networks": {
    "dev": {
      "base_url": "https://exchange.example.com/api/exchange",
      "direct_base_url": "https://api.example.com",
      "funds": "play",
      "ws_url": "wss://stream.example.com",
      "faucet": true
    }
  }
}

nexus --network dev markets

Un chain_id también va en esa entrada, una vez que lo hayas leído del propio GET /metadata de este despliegue. El ejemplo lo omite a propósito en lugar de mostrar un valor de ejemplo. No hay ningún centinela que signifique desconocido. La CLI toma cualquier número que escribas como el dominio EIP-712, así que uno inventado produce una firma con el dominio incorrecto, mientras que omitirlo produce un rechazo.

Una etiqueta no declarada es un error. La CLI valida una etiqueta declarada cuando la seleccionas, no cuando lee el archivo, así que un error en un entorno que no estás usando no rompe todos los demás comandos.

Los dos conjuntos de campos difieren, deliberadamente

Ninguna de las dos listas es un subconjunto de la otra. Hay tres diferencias:

• chain_id es solo de la CLI. El servidor MCP nunca produce una firma EIP-712 (se autentica con HMAC), así que no necesita un dominio de firma, y llevar uno sería un segundo lugar donde podría quedar desactualizado.
• gateway_path es solo del MCP. Es la misma configuración que el direct_base_url de la CLI, vista desde el otro lado. El servidor MCP toma la ruta y deriva la base directa, y la CLI toma la base directa y no necesita ninguna ruta.
• ws_url es solo de la CLI. El servidor MCP deriva su origen de WebSocket de la base del gateway, lo que el contrato de la API admite porque las rutas de stream no llevan un host aparte. La CLI acepta uno explícito porque un despliegue puede poner su stream en otro host. Así que puedes describirle a la CLI un destino personalizado con un origen de WebSocket separado, pero todavía no al servidor MCP.

Qué lleva una red

Seleccionar una red resuelve todo lo siguiente a la vez, y por eso es una sola elección y no varias:

• Base REST para los endpoints de trading y de cuenta.
• Bases de WebSocket para los datos de mercado públicos y para el stream autenticado, cuando la interfaz ofrece streams. El SDK de Python no incluye ningún cliente de WebSocket. El SDK de Rust se niega a conectarse en testnet hasta que el host de stream publicado esté activo, en lugar de emparejar un token de stream con un origen que no lo generó, así que allí aporta una URL de WebSocket explícita.
• Si existe un faucet. Entre las redes publicadas, el fondeo sintético es solo de testnet y local, y mainnet no tiene ninguno. Un destino personalizado declara el suyo, y se supone que no tiene ninguno hasta que lo haga.
• Si los saldos son dinero real. Un solo indicador según el cual ramificar antes de cualquier cosa irreversible, en lugar de reconocer patrones en un nombre de host.
• El dominio de firma EIP-712, que limita el registro de agentes a esta red. El servidor es la fuente de referencia de su chain id, así que léelo de GET /metadata para la red a la que estás conectado. Un cliente que no puede obtener uno se niega a firmar en lugar de reutilizar un valor de otro lado.

Credenciales y aislamiento de redes

Los tokens de sesión, las claves de API HMAC y los registros de agentes se generan por red y no son válidos en ninguna otra. Una clave configurada para una red no se autenticará contra otra, así que una credencial expuesta en testnet no puede firmar operaciones con fondos reales.

Un cliente queda vinculado a su red durante toda su vida útil, y no hay ningún setter. Cambiar de red significa construir un cliente nuevo con las credenciales propias de esa red, y nunca llevar una firma, un nonce o un registro de agente de una a otra.

La CLI guarda las credenciales por red, indexadas por el nombre de la red. Para un destino personalizado las indexa por etiqueta y no por URL, así que dos entornos en el mismo host mantienen credenciales separadas. Por lo tanto, --network selecciona el destino y el conjunto de credenciales a la vez. No puede generar una credencial. Cambiar a una red que todavía no configuraste te deja sin ninguna clave guardada para ella, así que ejecuta nexus setup para esa red, o pasa sus credenciales junto con --network en la línea de comandos.

Qué vincula una clave a una red

El host contra el que la generas. La creación de claves no tiene ningún parámetro de red. POST /keys registra la red de la instancia que atendió la solicitud, y a partir de ahí la clave solo es válida allí. Así que la URL base a la que apuntas cuando creas una clave es la decisión de vinculación. No hay nada que definir ni nada que confirmar.

Planifica en función de dos consecuencias:

• Crear una clave mientras apuntas a una red y luego operar contra otra no puede funcionar, sin importar cómo configures el cliente después.
• Necesitas una clave separada para cada red que pienses usar, generada por separado contra cada una.

Cómo se ve una clave de la red equivocada

Se ve exactamente igual que una clave que no existe: HTTP 401 Unauthorized con este cuerpo:

{
  "code": "unauthorized"
}

Esa respuesta es indistinguible, a propósito, de una firma incorrecta, un id de clave desconocido o un encabezado faltante. Una clave rechazada no debe poder identificarse como "real, pero registrada en otro lado", porque eso permitiría a alguien confirmar que un id de clave adivinado está activo en otra red. Por eso la API no te dice nada más allá de "esta solicitud no está autenticada".

Si la autenticación falla después de cambiar la red a la que apuntas, es mucho más probable que la causa sea la red que una clave revocada. Verifica qué host generó la clave antes de suponer que se eliminó o que se perdió el secreto. Nada en la respuesta te va a llevar hasta ahí.

Claves generadas antes de la vinculación por red

Las claves creadas antes de que existiera la vinculación por red no tienen una red propia. Siguen funcionando en testnet y local, que adoptan esas claves como propias y registran la red en ellas. Mainnet no las aceptará cuando se lance, porque una clave sin marca no demuestra nada sobre su origen. Genera una clave nueva contra mainnet en lugar de esperar que una existente se traslade.

Para ver el recorrido completo de autenticación, desde el inicio de sesión con la billetera hasta una solicitud firmada, consulta el Inicio rápido.

Relacionado

• APIs y límites de solicitudes: URL base y límites de solicitudes actuales
• SDK y herramientas
• Portafolio y estado de la cuenta
• Inicio rápido

Estado: versión preliminar de desarrollo en testnet. Mainnet no se ha lanzado y todavía no es accesible. El selector de red reemplazó al selector anterior de canales de versiones {stable, beta, local}. Fija una versión publicada en producción y revisa las notas de versión de cada interfaz antes de actualizar. Las credenciales y los saldos de testnet no tienen valor en el mundo real.