De la primera llamada al estado finalizado.

NexusSDK es la interfaz para desarrolladores de ORBITRA ONE™. Expone primitivas de mercado, identidad, activos y agentes como servicios tipados, respaldados por los mismos módulos nativos que ejecutan Orbitra Prime y liquidan en Orbitra L1.

Servicios

• API de mercado — órdenes, libros, RFQ y variaciones de compensación en ApexMatch, con prerriesgo de Aegis en cada orden.
• Asset Studio — emisión y administración de activos tokenizados con permisos del emisor, eventos del ciclo de vida y control de elegibilidad.
• Identidad de agentes — agentes de IA y bots registrados como identidades responsables, cada uno vinculado a una política de Cortex.
• Intercambio de datos — publicación y licencia de conjuntos de datos y señales con procedencia verificable.
• VaultID — comprobaciones de credenciales para la elegibilidad y los permisos, sin gestionar documentos de identidad.
• Pagos — solicitudes de pago y liquidación con la misma finalidad determinista que las operaciones.

Reglas de diseño

• Cada llamada la realiza una identidad con permisos explícitos y delimitados.
• Cada cambio de estado devuelve un recibo firmado que se puede verificar de forma independiente.
• Los límites que usted establece en el cliente se aplican de nuevo en el protocolo.
• Las credenciales y los puntos de conexión proceden del entorno, nunca del código fuente.

Los nombres de paquetes y crates en estos ejemplos siguen un patrón ilustrativo. Los nombres de paquetes publicados, las credenciales de entorno aislado (sandbox) y los puntos de conexión se emiten con el acceso al SDK — registrar interés como desarrollador.

Instalación

# TypeScript and JavaScript
npm install @orbitra/nexus-sdk

# Python
pip install orbitra-nexus

# Rust
cargo add orbitra-nexus

Configurar las credenciales

El SDK lee dos variables de entorno. Mantenga ambas fuera del control de versiones y cárguelas desde un gestor de secretos o su entorno de despliegue. Empiece con credenciales de entorno aislado (sandbox): el entorno aislado está separado de los activos y mercados reales.

• ORBITRA_API_KEY — la credencial delimitada emitida con el acceso al SDK.
• ORBITRA_ENDPOINT — el punto de conexión del entorno emitido con esa credencial.

# Both values are issued with SDK access. Never commit them to a repository.
export ORBITRA_API_KEY="<issued-with-sdk-access>"
export ORBITRA_ENDPOINT="<issued-with-sdk-access>"

Primera llamada

import { NexusClient } from '@orbitra/nexus-sdk';

const apiKey = process.env.ORBITRA_API_KEY;
const endpoint = process.env.ORBITRA_ENDPOINT;

if (!apiKey || !endpoint) {
  throw new Error('Set ORBITRA_API_KEY and ORBITRA_ENDPOINT before running this example.');
}

const nexus = new NexusClient({ apiKey, endpoint });

const account = await nexus.accounts.current();
console.log(account.id, account.permissions);

La respuesta describe la cuenta que hay detrás de la credencial: sus credenciales VaultID, los permisos concedidos a esta clave y los mercados a los que puede acceder. Un error de permisos significa que la clave es válida, pero no está delimitada para esa acción. Los ejemplos posteriores usan el atajo NexusClient.fromEnv(), que lee las mismas dos variables.

VaultID es la capa de identidad, elegibilidad y permisos. Cada solicitante —una persona, una institución, una aplicación o un agente— actúa a través de una identidad que posee credenciales. Las aplicaciones comprueban las credenciales; nunca reciben los documentos que hay detrás de ellas.

Tipos de identidad

• Persona física — una persona que posee credenciales de elegibilidad emitidas durante el alta.
• Institución — una organización con subcuentas, funciones y reglas de aprobación de doble control.
• Aplicación — un servicio registrado por un desarrollador, que posee únicamente los permisos que declara.
• Agente — un agente de IA o bot vinculado a una política de Cortex y revocable por su propietario.

Claves delimitadas

Las claves de API se emiten a una identidad con un ámbito: qué servicios, qué mercados, qué acciones y durante cuánto tiempo. Use una clave distinta para cada entorno y cada aplicación, y revoque las claves que ya no necesite.

import { NexusClient } from '@orbitra/nexus-sdk';

const nexus = NexusClient.fromEnv();

export async function canTradeOptions(subjectId: string): Promise<boolean> {
  // Returns whether the credential is present and valid, never the data behind it.
  const result = await nexus.vaultid.verify({
    subject: subjectId,
    credential: 'eligibility.options',
  });

  return result.valid;
}

No recopile documentos de identidad en su aplicación para recrear las comprobaciones de elegibilidad. Solicite la credencial en su lugar: VaultID confirma si está presente y es válida, y nada más.

Cada llamada que cambia el estado devuelve un recibo: un registro firmado de lo que la red hizo con su solicitud —cuándo se recibió, dónde se secuenció, qué decidió Aegis y qué cambió como resultado.

Contenido del recibo

• Recibida — la marca temporal de entrada y la firma de la pasarela que aceptó la solicitud.
• Secuencia — la posición canónica asignada por la secuenciación justa.
• Veredicto de riesgo — la decisión de Aegis y, en caso de rechazo, el límite que se habría superado.
• Resultado — ejecuciones, variaciones de compensación, eventos de contrato o transferencias producidos por la transición.
• Finalidad — una referencia al certificado de cuórum de QSE una vez que la transición es final.

Una transición es final cuando un certificado de cuórum de QSE la cubre. No hay una profundidad de confirmación que esperar: una vez certificado, el estado no se reorganiza bajo el modelo de fallos declarado.

import { NexusClient } from '@orbitra/nexus-sdk';

const nexus = NexusClient.fromEnv();

export async function confirmFinal(transitionId: string): Promise<boolean> {
  // Resolves once a QSE quorum certificate covers the transition.
  const finality = await nexus.finality.wait(transitionId);

  // Checks the certificate signatures locally against the validator set it names.
  const verified = await nexus.finality.verify(finality.certificate);

  return finality.status === 'final' && verified;
}

Las API de mercado exponen ApexMatch directamente. Las órdenes son intenciones firmadas: el SDK las firma con su clave, la pasarela verifica la firma, la secuenciación justa asigna una posición y el prerriesgo de Aegis se ejecuta antes de que la orden pueda llegar al libro.

Una política del lado del cliente añade una segunda salvaguarda. El SDK la evalúa antes de firmar, de modo que una orden fuera de sus propios límites nunca sale de su proceso. Aegis sigue aplicando los límites a nivel de cuenta en la puerta del protocolo.

import { NexusClient, definePolicy } from '@orbitra/nexus-sdk';

// fromEnv() reads ORBITRA_API_KEY and ORBITRA_ENDPOINT.
const nexus = NexusClient.fromEnv();

// Evaluated locally before the order is signed.
// Aegis enforces account-level limits again at the protocol gate.
const policy = definePolicy({
  markets: { allow: ['EURUSD'] },
  maxOrderNotional: '50000',
  maxLeverage: 2,
  requirePostOnly: true,
});

const receipt = await nexus.orders.place(
  {
    market: 'EURUSD',
    side: 'buy',
    type: 'limit',
    price: '1.0850',
    size: '10000',
    postOnly: true,
    clientOrderId: 'docs-example-001',
  },
  { policy },
);

console.log(receipt.status, receipt.sequence, receipt.riskVerdict);

Tipos de orden

Los tipos básicos —de mercado, límite, stop, stop-limit, post-only y reduce-only— son nativos. Los tipos avanzados, algorítmicos e institucionales componen las mismas primitivas; el lenguaje completo de órdenes se describe en Ejecución.

Los identificadores de mercado, los precios y los tamaños de estos ejemplos son ilustrativos. El acceso a los mercados a través de la API sigue las mismas reglas de elegibilidad y jurisdicción que la interfaz.

Aegis expone la misma simulación que ejecuta en la puerta de prerriesgo. Envíe las órdenes propuestas y, opcionalmente, escenarios de estrés; Aegis devuelve el estado proyectado de la cartera y cualquier política que las órdenes incumplirían, sin enviar nada realmente al mercado.

import { NexusClient } from '@orbitra/nexus-sdk';

const nexus = NexusClient.fromEnv();

// Nothing is submitted: Aegis returns the projected post-trade state.
const simulation = await nexus.risk.simulate({
  orders: [
    { market: 'EURUSD', side: 'buy', type: 'limit', price: '1.0850', size: '10000' },
  ],
  scenarios: ['volatility-shock', 'liquidity-drain'],
});

console.log('margin used', simulation.marginUsed);
console.log('liquidation distance', simulation.liquidationDistance);

for (const breach of simulation.policyBreaches) {
  console.warn(breach.policy, breach.limit, breach.projected);
}

Qué devuelve una simulación

• El uso proyectado de margen y la garantía libre después de las órdenes propuestas.
• La distancia a la liquidación forzosa de cada posición que las órdenes afectarían.
• Un resultado para cada escenario de estrés solicitado.
• Cada incumplimiento de política, con el límite y el valor proyectado.

Una simulación describe la cartera en el momento de la solicitud. Los mercados se mueven, por lo que una simulación no garantiza que una orden vaya a aceptarse o ejecutarse a los mismos valores.

Un agente es una identidad propia. Puede observar los mercados de forma amplia, pero solo actúa dentro de una política de Cortex: el capital que puede asignar, las pérdidas que puede asumir, el apalancamiento, los mercados y las horas que puede usar, cuándo debe confirmar un humano y en qué fuentes de datos puede basarse.

Cada intención que propone un agente pasa por el bucle de Cortex: observar, razonar, proponer, simular, autorizar, ejecutar. El motor de políticas autoriza o rechaza cada una, y cada acción produce un recibo atribuido al agente.

{
  "policyVersion": "1",
  "capital": { "maxAllocation": "100000", "asset": "USD" },
  "loss": { "dailyLimit": "2000", "lifetimeLimit": "10000" },
  "leverage": { "ceiling": 3 },
  "markets": { "allow": ["EURUSD", "GBPUSD"], "deny": [] },
  "session": { "hours": "Mon-Fri 07:00-17:00 UTC", "expiresAfter": "P30D" },
  "confirmation": { "requiredAboveNotional": "25000" },
  "dataSources": ["prism:fx-majors", "account:portfolio"],
  "kill": { "onBreach": "revoke-all", "cancelOpenOrders": true }
}

import { readFile } from 'node:fs/promises';
import { NexusClient } from '@orbitra/nexus-sdk';

const nexus = NexusClient.fromEnv();

const policy = JSON.parse(await readFile('./policies/fx-hedger.json', 'utf8'));

const agent = await nexus.agents.register({ name: 'fx-hedger', policy });

// At any time, one command revokes every permission the agent holds.
await nexus.agents.kill(agent.id);

Detener un agente

El control de detención revoca, con un solo comando, todos los permisos que posee el agente. Las órdenes abiertas se cancelan según lo que especifique la política, y la clave del agente ya no puede firmar.

La automatización, incluida la automatización asistida por IA, puede fallar o comportarse de forma inesperada. Las políticas acotan el daño; no eliminan el riesgo. Consulte IA y negociación automatizada.

Los contratos de NexusWASM compilan a WebAssembly y se ejecutan en un entorno aislado (sandbox) medido. Un contrato declara sus capacidades —las primitivas que puede invocar y el estado que puede tocar— y el entorno de ejecución rechaza cualquier llamada fuera de esa declaración.

use orbitra_nexus_wasm::prelude::*;
use orbitra_nexus_wasm::market::{LimitOrder, MarketId, OrderReceipt, Side};

/// Rebalances a treasury position with post-only limit orders on one market.
/// The capability list is checked at deployment; any other call is rejected at runtime.
#[contract(capabilities = [market::place_order, market::cancel_order, storage::read_write])]
pub struct TreasuryRebalancer {
    market: MarketId,
    max_order_size: Decimal,
}

#[contract_impl]
impl TreasuryRebalancer {
    #[call(owner_only)]
    pub fn rebalance(
        &mut self,
        ctx: &mut Context,
        side: Side,
        price: Decimal,
        size: Decimal,
    ) -> Result<OrderReceipt> {
        ensure!(size <= self.max_order_size, ContractError::SizeAboveLimit);

        let order = LimitOrder::new(self.market.clone(), side, price, size).post_only(true);

        // Native call into ApexMatch. Aegis pre-risk applies to the contract's own account.
        ctx.market().place_order(order)
    }
}

Compilación

rustup target add wasm32-unknown-unknown
cargo build --release --target wasm32-unknown-unknown

• El cómputo y el almacenamiento tienen un precio explícito, de modo que el coste de un contrato depende de lo que hace.
• El acceso declarado al estado permite que contratos independientes se ejecuten en paralelo en VectorLanes.
• Las llamadas de mercado de un contrato pasan por el prerriesgo de Aegis para la propia cuenta del contrato, como cualquier otra orden.
• El despliegue envía el módulo junto con su lista de capacidades; un módulo que invoca una primitiva no declarada se rechaza.

El EVM Capsule es un dominio de compatibilidad aislado para el bytecode y las herramientas de Ethereum. Tiene sus propios techos de gas y de recursos, solo alcanza los activos del núcleo a través de una pasarela con límite de tasa y puede detenerse mediante disyuntores sin afectar al entorno de ejecución del núcleo.

La cápsula es un límite de compatibilidad, no el entorno de ejecución del núcleo. Las primitivas de mercado nativas se invocan desde NexusWASM; la cápsula se conecta con los activos del núcleo únicamente a través de su pasarela gobernada.

Pasos de la migración

• Desplegar sin cambios. Los contratos existentes y las herramientas habituales se ejecutan dentro de la cápsula, medidos contra sus propios techos.
• Conectar de forma deliberada. Traslade los activos a través de la pasarela con límite de tasa, con topes de ruta ajustados a su exposición.
• Medir. Identifique dónde importa más el rendimiento nativo o el acceso al mercado, normalmente en la gestión de órdenes, la liquidación y la lógica de riesgo.
• Portar. Reimplemente esas rutas como contratos de NexusWASM que invoquen directamente a ApexMatch y Aegis, conservando la versión de la cápsula como referencia.
• Verificar y retirar. Reproduzca las mismas entradas en ambas versiones, traslade a los usuarios a los contratos nativos cuando los resultados coincidan y desactive el despliegue de la cápsula.

Los operadores ejecutan el cliente de nodo para reproducir el estado finalizado, dar servicio a aplicaciones o, una vez admitidos como validadores, asumir funciones de proponente y comité bajo QSE. Un mismo cliente cumple cada función: la configuración procede del entorno, y las claves de firma permanecen en un HSM o un firmante MPC.

# Verify the release before installing it. Release-signing keys are published with operator access.
orbitra-node verify-release ./orbitra-node.tar.gz --signature ./orbitra-node.tar.gz.sig

# Configuration comes from the environment. Keys stay in the HSM or MPC signer.
export ORBITRA_NETWORK="<issued-with-operator-access>"
export ORBITRA_ENDPOINT="<issued-with-operator-access>"
export ORBITRA_SIGNER="hsm"   # or "mpc"

orbitra-node init --network "$ORBITRA_NETWORK" --signer "$ORBITRA_SIGNER"
orbitra-node start

# Inspect assigned duties, quorum participation and service measurements.
orbitra-node status --duties --service

# Rehearse a Q-Switch signature-suite rotation without applying it.
orbitra-node keys rotate --suite next --dry-run

Los nombres de los comandos mostrados son ilustrativos. El cliente del operador, sus claves de firma de versión y los identificadores de red se emiten con el acceso de operador — consulte validadores.

Reglas de operación

• Verifique la firma de cada versión antes de instalarla o actualizarla.
• Haga referencia a las claves por firmante, nunca por archivo: las claves de validador no deben residir en el host del nodo.
• Exporte las mediciones de funciones y servicio a su propio sistema de monitorización y alertas.
• Rote las suites de firma mediante comandos de Q-Switch, en lugar de una renovación de claves improvisada.

Las notas de la versión acompañan a cada versión de NexusSDK y se publican en esta pasarela junto a la documentación de esa versión. El selector de versiones muestra qué edición está leyendo.

Cada nota de la versión registra

• Las interfaces nuevas, modificadas y eliminadas, con un ejemplo de cada forma nueva.
• Las funciones obsoletas, su reemplazo correspondiente y los pasos para migrar.
• Los cambios en las suites de firma o los formatos de credenciales introducidos mediante Q-Switch.
• Los parámetros del protocolo que afectan a los operadores de nodo y a los validadores.
• Las correcciones de seguridad, una vez coordinada su divulgación.

Está leyendo la edición preliminar. Sus interfaces se documentan tal como se diseñaron y pueden cambiar antes de la disponibilidad general; cada cambio se registra en las notas de la versión que lo introduce.