Da primeira chamada ao estado finalizado.

O NexusSDK é a interface de desenvolvedor do ORBITRA ONE™. Ele expõe primitivas de mercado, identidade, ativos e agentes como serviços tipados, apoiados pelos mesmos módulos nativos que executam o Orbitra Prime e liquidam no Orbitra L1.

Serviços

• APIs de mercado — ordens, livros de ofertas, RFQ e deltas de compensação no ApexMatch, com pré-risco do Aegis em cada ordem.
• Asset Studio — emissão e administração de ativos tokenizados, com permissões do emissor, eventos do ciclo de vida e verificação de elegibilidade.
• Identidade de agentes — agentes de IA e bots registrados como identidades responsáveis, cada um vinculado a uma política do Cortex.
• Troca de dados — publicação e licenciamento de conjuntos de dados e sinais com proveniência verificável.
• VaultID — verificação de credenciais de elegibilidade e permissões, sem manipular documentos de identidade.
• Pagamentos — solicitações de pagamento e liquidação com a mesma finalidade determinística das negociações.

Regras de design

• Toda chamada é feita por uma identidade com permissões explícitas e delimitadas.
• Toda mudança de estado retorna um recibo assinado que pode ser verificado de forma independente.
• Os limites definidos no cliente são aplicados novamente pelo protocolo.
• Credenciais e endpoints vêm do ambiente, nunca do código-fonte.

Os nomes de pacotes e crates usados nestes exemplos seguem um padrão ilustrativo. Os nomes de pacotes publicados, as credenciais de sandbox e os endpoints são fornecidos com o acesso ao SDK — registre seu interesse como desenvolvedor.

Instalar

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

# Python
pip install orbitra-nexus

# Rust
cargo add orbitra-nexus

Configurar as credenciais

O SDK lê duas variáveis de ambiente. Mantenha ambas fora do controle de versão e carregue-as a partir de um gerenciador de segredos ou do seu ambiente de implantação. Comece com credenciais de sandbox: o sandbox é isolado dos ativos e mercados reais.

• ORBITRA_API_KEY — a credencial delimitada fornecida com o acesso ao SDK.
• ORBITRA_ENDPOINT — o endpoint do ambiente fornecido com essa 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>"

Primeira chamada

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);

A resposta descreve a conta associada à credencial: suas credenciais VaultID, as permissões concedidas a essa chave e os mercados aos quais ela pode ter acesso. Um erro de permissão significa que a chave é válida, mas não está delimitada para essa ação. Os exemplos seguintes usam o atalho NexusClient.fromEnv(), que lê as mesmas duas variáveis.

VaultID é a camada de identidade, elegibilidade e permissão. Todo chamador — uma pessoa, uma instituição, uma aplicação ou um agente — atua por meio de uma identidade que possui credenciais. As aplicações verificam credenciais; elas nunca recebem os documentos por trás delas.

Tipos de identidade

• Pessoa física — uma pessoa que possui credenciais de elegibilidade emitidas durante o onboarding.
• Instituição — uma organização com subcontas, funções e regras de aprovação por duas pessoas.
• Aplicação — um serviço registrado por um desenvolvedor, com apenas as permissões que declara.
• Agente — um agente de IA ou bot vinculado a uma política do Cortex e revogável por seu proprietário.

Chaves delimitadas

As chaves de API são emitidas para uma identidade com um escopo: quais serviços, quais mercados, quais ações e por quanto tempo. Use uma chave separada para cada ambiente e cada aplicação, e revogue as chaves que já não forem necessárias.

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;
}

Não colete documentos de identidade na sua aplicação para recriar verificações de elegibilidade. Em vez disso, solicite a credencial: o VaultID confirma apenas se ela está presente e válida, nada mais.

Toda chamada que altera o estado retorna um recibo: um registro assinado do que a rede fez com sua solicitação — quando ela foi recebida, onde foi sequenciada, o que o Aegis decidiu e o que mudou como resultado.

Conteúdo do recibo

• Recebido — o registro de data e hora de entrada e a assinatura do gateway que aceitou a solicitação.
• Sequência — a posição canônica atribuída pelo sequenciamento justo.
• Veredito de risco — a decisão do Aegis e, em caso de rejeição, o limite que teria sido violado.
• Resultado — execuções, deltas de compensação, eventos de contrato ou transferências produzidos pela transição.
• Finalidade — uma referência ao certificado de quórum QSE quando a transição se torna final.

Uma transição é final quando um certificado de quórum QSE a cobre. Não há profundidade de confirmação a aguardar: uma vez certificado, o estado não se reorganiza sob o modelo de falhas 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;
}

As APIs de mercado expõem o ApexMatch diretamente. As ordens são intenções assinadas: o SDK as assina com sua chave, o gateway verifica a assinatura, o sequenciamento justo atribui uma posição e o pré-risco do Aegis é executado antes que a ordem possa chegar ao livro.

Uma política do lado do cliente adiciona uma segunda proteção. O SDK a avalia antes de assinar, de modo que uma ordem fora dos seus próprios limites nunca sai do seu processo. O Aegis ainda aplica os limites no nível da conta na barreira do 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 ordem

Os tipos principais — market, limit, stop, stop-limit, post-only e reduce-only — são nativos. Os tipos avançados, algorítmicos e institucionais compõem as mesmas primitivas; a linguagem completa de ordens está descrita em execução.

Os identificadores de mercado, preços e tamanhos usados nestes exemplos são ilustrativos. O acesso aos mercados pela API segue as mesmas regras de elegibilidade e jurisdição da interface.

O Aegis expõe a mesma simulação que executa na barreira de pré-risco. Envie ordens propostas e, opcionalmente, cenários de estresse; o Aegis retorna o estado projetado da carteira e qualquer política que as ordens violariam, sem submeter nada de fato.

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);
}

O que uma simulação retorna

• Uso projetado de margem e garantia livre após as ordens propostas.
• Distância da liquidação para cada posição que as ordens afetariam.
• Um resultado para cada cenário de estresse solicitado.
• Cada violação de política, com o limite e o valor projetado.

Uma simulação descreve a carteira no momento da solicitação. Os mercados se movem, portanto uma simulação não garante que uma ordem será aceita ou executada nos mesmos valores.

Um agente é uma identidade própria. Ele pode observar os mercados amplamente, mas atua apenas dentro de uma política do Cortex: o capital que pode alocar, as perdas que pode incorrer, a alavancagem, os mercados e os horários que pode usar, quando uma pessoa deve confirmar e quais fontes de dados pode utilizar.

Toda intenção que um agente propõe passa pelo ciclo do Cortex — observar, raciocinar, propor, simular, autorizar, executar. O motor de políticas autoriza ou rejeita cada uma, e toda ação produz um recibo atribuído ao 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);

Parar um agente

O controle de parada revoga, com um único comando, todas as permissões do agente. As ordens abertas são canceladas conforme especificado na política, e a chave do agente deixa de poder assinar.

A automação, incluindo a automação assistida por IA, pode falhar ou se comportar de forma inesperada. As políticas limitam o dano; elas não eliminam o risco. Veja IA e negociação automatizada.

Os contratos NexusWASM compilam para WebAssembly e são executados em um sandbox medido. Um contrato declara suas capacidades — as primitivas que pode chamar e o estado que pode tocar — e o runtime rejeita qualquer chamada fora dessa declaração.

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)
    }
}

Compilar

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

• O processamento e o armazenamento têm preços explícitos, portanto o custo de um contrato decorre do que ele faz.
• O acesso declarado ao estado permite que contratos independentes sejam executados em paralelo no VectorLanes.
• As chamadas de mercado feitas por um contrato passam pelo pré-risco do Aegis para a própria conta do contrato, como qualquer outra ordem.
• A implantação submete o módulo com sua lista de capacidades; um módulo que chama uma primitiva não declarada é rejeitado.

O EVM Capsule é um domínio de compatibilidade isolado para bytecode e ferramentas Ethereum. Ele tem seus próprios tetos de gas e de recursos, alcança os ativos do núcleo apenas por um gateway com limite de taxa e pode ser interrompido por mecanismos de interrupção sem afetar o runtime principal.

A capsule é um limite de compatibilidade, não o ambiente de execução principal. As primitivas nativas de mercado são chamadas a partir do NexusWASM; a capsule se conecta aos ativos do núcleo apenas por meio do seu gateway governado.

Etapas de migração

• Implante sem alterações. Contratos existentes e ferramentas já conhecidas são executados dentro da capsule, medidos em relação aos próprios tetos.
• Faça a ponte de forma deliberada. Movimente ativos pelo gateway com limite de taxa, com tetos de rota dimensionados para sua exposição.
• Meça. Identifique onde o desempenho nativo ou o acesso ao mercado mais importa — normalmente no tratamento de ordens, na liquidação e na lógica de risco.
• Porte. Reimplemente esses caminhos como contratos NexusWASM que chamam o ApexMatch e o Aegis diretamente, mantendo a versão da capsule como referência.
• Verifique e desative. Reproduza as mesmas entradas nas duas versões, migre os usuários para os contratos nativos quando os resultados coincidirem e encerre a implantação na capsule.

Os operadores executam o cliente de nó para reproduzir o estado finalizado, atender aplicações ou, uma vez admitidos como validadores, assumir funções de proponente e de comitê sob o QSE. Um único cliente atende a cada função: a configuração vem do ambiente, e as chaves de assinatura permanecem em um HSM ou em um signatário 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

Os nomes de comando exibidos são ilustrativos. O cliente do operador, suas chaves de assinatura de versão e os identificadores de rede são fornecidos com o acesso de operador — veja validadores.

Regras de operação

• Verifique a assinatura de cada versão antes da instalação ou da atualização.
• Referencie as chaves pelo signatário, nunca por arquivo: as chaves de validador não devem estar na máquina do nó.
• Exporte as medições de funções e de serviço para seu próprio monitoramento e alertas.
• Rotacione as suítes de assinatura por meio de comandos do Q-Switch, em vez de trocas de chave ad-hoc.

As notas de versão acompanham cada versão do NexusSDK e são publicadas neste gateway ao lado da documentação daquela versão. O seletor de versões mostra qual edição você está lendo.

Toda nota de versão registra

• Interfaces novas, alteradas e removidas, com um exemplo de cada nova forma.
• Descontinuações, o substituto de cada uma e os passos para migrar.
• Mudanças em suítes de assinatura ou em formatos de credencial introduzidas pelo Q-Switch.
• Parâmetros de protocolo que afetam operadores de nó e validadores.
• Correções de segurança, uma vez coordenada a divulgação.

Você está lendo a edição de prévia. Suas interfaces são documentadas conforme projetadas e podem mudar antes da disponibilidade geral; cada mudança é registrada nas notas de versão da versão que a introduz.