> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/es-419/guides/networks.md). # 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](https://docs.nexus.xyz/exchange/apis-and-rates). Esas tres son las redes publicadas. Un despliegue que ejecutas tú mismo es una [red `Custom`](#the-custom-network). 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](#pointing-at-a-host-without-describing-it)), 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 `, 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](#describing-a-custom-target). 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 ```python from nexus_exchange import Client, Network client = Client(network=Network.TESTNET, api_key=..., api_secret=...) ``` ```typescript import { Client, Network } from "@nexus-xyz/exchange-ts"; const client = new Client({ network: Network.Testnet, apiKey: "…", apiSecret: "…" }); ``` ```rust use nexus_exchange::{Config, Network}; let config = Config::new(Network::Testnet); ``` ```bash 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](#the-two-field-sets-differ-deliberately). | | **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 `, 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: ```json { "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 } } } ``` ```bash 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: ```json { "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](https://docs.nexus.xyz/exchange/trading/quickstart). ### Relacionado * [APIs y límites de solicitudes](https://docs.nexus.xyz/exchange/apis-and-rates): URL base y límites de solicitudes actuales * [Descripción general de las interfaces](/api-reference/es-419/readme.md) * [Portafolio y estado de la cuenta](/api-reference/es-419/guides/portfolio.md) * [Inicio rápido](https://docs.nexus.xyz/exchange/trading/quickstart) > **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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nexus.xyz/api-reference/es-419/guides/networks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.