Portafolio y estado de la cuenta
Estado consolidado de la cuenta, saldo disponible para retirar, tabla de comisiones, posiciones enriquecidas y la serie de tiempo del portafolio, en los SDK y la CLI.
Los endpoints del portafolio responden cuatro preguntas sobre una cuenta: cuánto vale ahora mismo, qué se puede retirar, qué se le cobra y cómo ha rendido a lo largo del tiempo. Son un pequeño conjunto de endpoints REST autenticados más campos de riesgo enriquecidos por posición. Todas las interfaces (los SDK de Rust, TypeScript y Python y la CLI) llegan a las mismas rutas del gateway documentado en APIs y límites de solicitudes.
Si estás construyendo una vista de portafolio, lee Cómo leer estos valores de forma segura antes de mostrar nada. Varios campos admiten null a propósito, una convención de signo es fácil de invertir, y una implementación ingenua con dos llamadas tendrá una condición de carrera en producción.
Cómo obtenerlo
npm install @nexus-xyz/exchange-ts # TypeScript
cargo add nexus-exchange # Rust
pip install nexus-exchange # PythonLa CLI se distribuye a través de las versiones de nexus-exchange-cli. Consulta SDK y herramientas para ver todos los clientes.
Autenticación
Cada ruta de esta página es de alcance de cuenta y requiere una clave de API HMAC. No hay ninguna variante pública o sin autenticación. Las solicitudes llevan X-API-Key, X-Timestamp y X-Signature, y la marca de tiempo debe estar dentro de 30 segundos respecto a la hora del servidor. Los SDK y la CLI firman por ti. El flujo completo, con cURL ejecutable, está en el Inicio rápido.
Mantén el secreto de la API fuera del código fuente y del historial del shell. Se muestra una sola vez al crearlo y no se puede recuperar después. Los ejemplos de abajo lo leen del entorno.
Cómo elegir una red
Hoy el Exchange funciona en Nexus Testnet, y después llegará mainnet. Selecciona la red al construir el cliente. Consulta Redes para ver cómo lo hace cada interfaz y cómo se vinculan las claves de API a una red, y APIs y límites de solicitudes para la URL base actual. La clave HMAC que requieren estas rutas está limitada a la red en la que se creó.
Referencia
GET
/account/state
HMAC
Resumen del portafolio y todas las posiciones abiertas, en una sola lectura coherente
GET
/account/summary
HMAC
Solo el resumen del portafolio, el mismo objeto que incluye /account/state
GET
/account/fees
HMAC
Tabla efectiva de comisiones de la cuenta
GET
/account/portfolio-history?window=&limit=
HMAC
Series de tiempo de patrimonio, PnL acumulado y volumen acumulado
Puntos de entrada por SDK:
Rust
fetch_account_state()
fetch_account_fees()
fetch_portfolio_history(window, limit)
Python
fetch_account_state()
fetch_account_fees()
fetch_portfolio_history(window, limit)
TypeScript
getAccountState()
getAccountFees()
getPortfolioHistory({ window, limit })
CLI
nexus account state
nexus account fees
nexus account portfolio-history --window --limit
Estado consolidado de la cuenta
GET /account/state devuelve los agregados del portafolio y todas las posiciones abiertas construidos a partir de una sola lectura del lado del servidor. Como ambas mitades provienen de la misma instantánea, summary.open_positions_count siempre es igual a la longitud de positions.
El resumen incluye collateral, total_equity, total_unrealized_pnl, total_realized_pnl_24h, total_volume_24h, open_positions_count, open_orders_count, margin_used, available_margin y withdrawable.
withdrawable es el saldo que puede salir de la cuenta: el margen libre según el motor, que es la fuente de referencia, con un piso de cero, max(0, available_margin). El margen libre ya descuenta del patrimonio el margen inicial de cada posición y cada reserva de órdenes previa a la operación, así que este es el monto del que puede disponer un retiro. No es total_equity ni collateral. Una cuenta en pérdida se acota a "0" y nunca se informa negativa. El valor proviene de la vista de margen de referencia del motor, así que cuando esa vista no está disponible, el endpoint falla cerrado con 502 en lugar de devolver un número estimado localmente.
Tabla de comisiones
GET /account/fees informa lo que la plataforma le cobra hoy a la cuenta. Es la tasa vigente de la tabla, que aplica de aquí en adelante, no un promedio realizado sobre ejecuciones pasadas.
maker_fee_bps
Puntos básicos principales. Puede ser negativo; cero es un centinela cuando schedule=unknown
taker_fee_bps
Puntos básicos principales; cero es un centinela cuando schedule=unknown
tier
Actualmente siempre base; todavía no hay niveles por cuenta
schedule
per_market, reference o unknown; trátalo como una cadena abierta
markets
Tasas de los mercados del búfer de ejecuciones retenido; ordenadas por market_id
volume_30d
Nocional operado móvil de 30 días, cadena decimal. Aproximado, consulta el indicador de abajo
volume_30d_estimated
true cuando volume_30d puede quedarse corto (el búfer de ejecuciones de origen estaba lleno)
discounts
Descuentos activos. Actualmente siempre vacío
Cuando schedule es per_market, usa las filas markets devueltas como las tasas de referencia. El par de nivel superior es solo su resumen modal determinista. El búfer de ejecuciones en memoria, que tiene un tope, puede reiniciarse o expulsar mercados antiguos, así que una fila ausente no es evidencia de que la cuenta nunca operó ese mercado. reference significa que el búfer retenido no tiene ningún mercado con una tabla replicada y que el par de nivel superior es la tasa modal determinista de todos los mercados replicados de la plataforma. En ambos cálculos modales gana el par con más ocurrencias, y los empates se resuelven a favor del par (maker_fee_bps, taker_fee_bps) lexicográficamente menor. unknown significa que los parámetros de mercado no están disponibles. markets está vacío y ambos valores principales en bps son centinelas de cero, no una tabla sin comisiones. Hoy no existe ningún nivel ni programa de descuentos por cuenta. Trata schedule como abierto, y no ramifiques tu lógica según una forma de descuento que no existe.
Serie de tiempo del portafolio
GET /account/portfolio-history devuelve el patrimonio, el PnL de trading acumulado y el nocional operado acumulado a lo largo de una ventana, con submuestreo del lado del servidor. Los puntos van del más antiguo al más reciente.
window
Cadencia
Máx. de puntos
Rango
day
5 min
288
24 h
week
1 h
168
7 d
month
6 h
120
30 d
all
1 d
366
~1 año
Omitir window da day. Un valor fuera de ese conjunto se rechaza con 400 (invalid_window). Si el parámetro se repite, se usa el primer valor. limit debe estar entre 1 y 366. Dentro de ese rango, acota el resultado y se ajusta a la capacidad de la ventana en lugar de rechazarse, así que pedir 366 puntos de day devuelve 288 en lugar de un error. Fuera de ese rango, la solicitud se rechaza con 400.
La respuesta devuelve la window y el cadence_ms que se sirvieron. Léelos de vuelta en lugar de suponer los valores que enviaste, para que los ejes de tu gráfico usen los valores servidos.
Cada punto lleva timestamp_ms, equity, pnl y volume. pnl y volume son acumulados hasta esa muestra, no por intervalo. Para graficar la actividad por intervalo, calcula tú mismo la diferencia entre puntos adyacentes.
Campos enriquecidos de posición
Las posiciones que devuelve /account/state (y /positions) llevan detalle de riesgo por posición junto con symbol, side, size, entryPrice, unrealizedPnl y realizedPnl:
notional
abs(size) × mark price
initialMargin
Margen inicial mantenido contra la posición, según el modelo de margen cruzado
roe
Rendimiento sobre el margen inicial: unrealizedPnl / initialMargin
max_leverage
Apalancamiento máximo que permite el mercado, según sus parámetros de riesgo
leverage
El multiplicador de apalancamiento de la cuenta para esta posición
funding_paid
Financiamiento acumulado de la posición. Consulta la convención de signo más abajo
Los nombres son el vocabulario unificado de CCXT, así que un cliente ccxt.nexus() lee esta forma directamente. Los campos sin equivalente en CCXT conservan la escritura propia de la plataforma: size, roe, max_leverage, funding_paid. GET /account no tiene esta forma. Se retransmite desde el motor de emparejamiento y responde un objeto más acotado con los nombres propios del motor.
El servidor calcula estos valores en la ruta de lectura de baja latencia en lugar de consultar al motor de emparejamiento, lo que mantiene el endpoint rápido. La contrapartida es que, cuando uno de sus datos no está disponible en esa ruta, el campo es null y un <field>_error acompañante lleva un motivo legible por máquina en lugar de un número inventado.
leverage actualmente siempre es null, con leverage_error definido como margin_state_not_mirrored. Derivarlo requiere la configuración de apalancamiento de la cuenta o su margen asignado, y ninguno de los dos está disponible en la ruta de lectura. No lo reconstruyas a partir de initialMargin. Esa expresión se reduce a 1 / initial_margin_rate, que es una constante por mercado y no el apalancamiento real de la posición, así que sería incorrecta para todas las posiciones del mercado.
funding_paid es positivo cuando se paga. Un valor positivo significa que la posición pagó financiamiento, y un valor negativo significa que recibió financiamiento. Siempre está presente, es "0" antes de que se acumule cualquier financiamiento y está limitado por el historial de financiamiento que retiene la plataforma. Invertir este signo convierte un costo en un ingreso en una pantalla de PnL, así que escribe una prueba para esto.
Cómo leer estos valores de forma segura
Los valores monetarios son cadenas decimales, no números. equity, pnl, volume, withdrawable, notional y los demás son decimales de precisión arbitraria serializados como cadenas para que no haya pérdida. Analízalos con un tipo decimal. Pasarlos por un float (parseFloat, float(), as f64) vuelve a introducir el error de redondeo que la codificación como cadena existe para evitar. Los campos de apalancamiento (leverage, max_leverage) son números JSON genuinos.
Los campos derivados tienen tres estados, no dos. Cada uno de los cinco campos calculados de la posición (notional, initialMargin, roe, leverage y max_leverage) puede ser:
un valor: calculado y definitivo;
null: informado, pero no calculable, y el<field>_errorasociado dice por qué;ausente: el servidor es anterior al campo.
Reducir cualquiera de estos a 0 inventa datos. "No informado", "no calculable" y "cero" son tres respuestas distintas para un usuario que pregunta cuánto vale su posición, y solo una de ellas es un número. Muestra los casos faltantes como un vacío explícito (la CLI imprime -) y muestra el <field>_error cuando lo tengas. Lo mismo se aplica a withdrawable. Es opcional en el esquema, así que un despliegue anterior puede omitirlo, y usar "0" como valor predeterminado le diría a alguien que no tiene nada disponible cuando el servidor nunca informó el valor.
Esos cinco son exactamente los campos que llevan un <field>_error acompañante. funding_paid no es uno de ellos. Siempre está presente, así que no hay un funding_paid_error según el cual ramificar.
Prefiere /account/state a dos llamadas. Obtener /account/summary y /positions por separado son dos solicitudes independientes contra una cuenta en vivo. Una ejecución que llega entre ellas devuelve un agregado que no coincide con la lista de posiciones (open_positions_count dice tres, el arreglo tiene cuatro), y esto ocurre con cualquier carga real. El endpoint consolidado respalda ambas mitades con una sola lectura coherente.
Maneja los códigos de falla por separado. 401 es un problema de credenciales o de reloj. Verifica que X-Timestamp esté dentro de 30 segundos respecto a la hora del servidor antes de suponer que la clave es incorrecta. 429 significa que superaste el presupuesto de solicitudes; consulta Límites de solicitudes y aplica un backoff en lugar de reintentar de inmediato. Tres rutas de esta página (/account/summary, /fills y /account/portfolio-history) cuestan cinco unidades de ese presupuesto cada una en lugar de una, así que consultarlas en un ciclo cerrado agota la asignación de 20/s de quien llama con nivel Pro cinco veces más rápido de lo que sugiere un conteo de solicitudes. /account/state cuesta una y devuelve juntos el resumen y las posiciones, que es la forma más barata de leer ambos. Un 502 en /account/state y /account/summary significa que la vista de margen de referencia del motor no estaba accesible y el servidor se negó a adivinar. Reintenta, y no recurras a un withdrawable calculado localmente.
Ejemplo
Los números de arriba son coherentes entre sí. Con un precio de marca de 86000, notional es 0.25 × 86000, unrealizedPnl es 0.25 × (86000 − 84000), initialMargin es notional × 1/max_leverage, roe es unrealizedPnl / initialMargin, y withdrawable es igual a total_equity − margin_used del resumen porque no hay órdenes abiertas que reserven margen. Observa las dos escrituras en esa última frase. margin_used en el objeto SUMMARY es el agregado de la cuenta y conserva su nombre. initialMargin en una posición es el requisito por posición.
Los ejemplos ejecutables de punta a punta están en los repositorios de los SDK: examples/portfolio.ts y examples/portfolio.rs.
Relacionado
Estado: versión preliminar de desarrollo en testnet. Estas rutas se incluyen en la especificación OpenAPI v0.7.2 y están vigentes en v0.9.90. Fija una versión de la especificación en producción y revisa las notas de versión de cada SDK antes de actualizar.
/account/feesno tiene hoy ningún nivel ni programa de descuentos por cuenta, yleverageinformanullhasta que se replique el estado de margen que necesita. Las credenciales y los saldos de testnet no tienen valor en el mundo real.
Última actualización