From first call to finalized state.

NexusSDK is the developer interface to ORBITRA ONE™. It exposes market, identity, asset and agent primitives as typed services, backed by the same native modules that run Orbitra Prime and settle on Orbitra L1.

Services

• Market APIs — orders, books, RFQ and clearing deltas on ApexMatch, with Aegis pre-risk on every order.
• Asset Studio — issuance and administration of tokenized assets with issuer permissions, lifecycle events and eligibility enforcement.
• Agent identity — AI agents and bots registered as accountable identities, each bound to a Cortex policy.
• Data exchange — publication and licensing of datasets and signals with verifiable provenance.
• VaultID — credential checks for eligibility and permissions, without handling identity documents.
• Payments — payment requests and settlement on the same deterministic finality as trades.

Design rules

• Every call is made by an identity with explicit, scoped permissions.
• Every state change returns a signed receipt that can be verified independently.
• Limits you set on the client are enforced again by the protocol.
• Credentials and endpoints come from the environment, never from source code.

Package and crate names in these samples follow an illustrative pattern. Published package names, sandbox credentials and endpoints are issued with SDK access — register developer interest.

Install

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

# Python
pip install orbitra-nexus

# Rust
cargo add orbitra-nexus

Configure credentials

The SDK reads two environment variables. Keep both out of source control and load them from a secret manager or your deployment environment. Start with sandbox credentials: the sandbox is isolated from real assets and markets.

• ORBITRA_API_KEY — the scoped credential issued with SDK access.
• ORBITRA_ENDPOINT — the environment endpoint issued with that credential.

# 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>"

First call

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

The response describes the account behind the credential: its VaultID credentials, the permissions granted to this key and the markets it may access. A permission error means the key is valid but not scoped for that action. Later samples use the shorthand NexusClient.fromEnv(), which reads the same two variables.

VaultID is the identity, eligibility and permission layer. Every caller — a person, an institution, an application or an agent — acts through an identity that holds credentials. Applications check credentials; they never receive the documents behind them.

Identity types

• Individual — a person holding eligibility credentials issued during onboarding.
• Institution — an organization with subaccounts, roles and four-eyes approval rules.
• Application — a service registered by a developer, holding only the permissions it declares.
• Agent — an AI agent or bot bound to a Cortex policy and revocable by its owner.

Scoped keys

API keys are issued to an identity with a scope: which services, which markets, which actions and for how long. Use a separate key for each environment and each application, and revoke keys you no longer need.

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

Do not collect identity documents in your application to recreate eligibility checks. Request the credential instead: VaultID confirms whether it is present and valid, and nothing more.

Every state-changing call returns a receipt: a signed record of what the network did with your request — when it was received, where it was sequenced, what Aegis decided and what changed as a result.

Receipt contents

• Received — the ingress timestamp and the signature of the gateway that accepted the request.
• Sequence — the canonical position assigned by fair sequencing.
• Risk verdict — the Aegis decision and, for a rejection, the limit that would have been breached.
• Result — fills, clearing deltas, contract events or transfers produced by the transition.
• Finality — a reference to the QSE quorum certificate once the transition is final.

A transition is final when a QSE quorum certificate covers it. There is no confirmation depth to wait for: once certified, the state does not reorganize under the stated fault model.

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

Market APIs expose ApexMatch directly. Orders are signed intents: the SDK signs them with your key, the gateway verifies the signature, fair sequencing assigns a position and Aegis pre-risk runs before the order can reach the book.

A client-side policy adds a second guard. The SDK evaluates it before signing, so an order outside your own limits never leaves your process. Aegis still enforces account-level limits at the protocol gate.

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

Order types

Core types — market, limit, stop, stop-limit, post-only and reduce-only — are native. Advanced, algorithmic and institutional types compose the same primitives; the full order language is described under execution.

Market identifiers, prices and sizes in these samples are illustrative. Access to markets through the API follows the same eligibility and jurisdiction rules as the interface.

Aegis exposes the same simulation it runs at the pre-risk gate. Send proposed orders and optional stress scenarios; Aegis returns the projected portfolio state and any policy the orders would breach, without submitting anything.

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

What a simulation returns

• Projected margin use and free collateral after the proposed orders.
• Liquidation distance for every position the orders would affect.
• A result for each requested stress scenario.
• Each policy breach, with the limit and the projected value.

A simulation describes the portfolio at the moment of the request. Markets move, so a simulation does not guarantee that an order will be accepted or filled at the same values.

An agent is an identity of its own. It may observe markets broadly, but it acts only inside a Cortex policy: the capital it may allocate, the losses it may incur, the leverage, markets and hours it may use, when a human must confirm and which data sources it may rely on.

Every intent an agent proposes passes through the Cortex loop — observe, reason, propose, simulate, authorize, execute. The policy engine authorizes or rejects each one, and every action produces a receipt attributed to the agent.

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

Stopping an agent

The kill control revokes every permission the agent holds in one command. Open orders are cancelled as the policy specifies, and the agent’s key can no longer sign.

Automation, including AI-assisted automation, can fail or behave unexpectedly. Policies bound the damage; they do not remove the risk. See automated and AI-assisted trading.

NexusWASM contracts compile to WebAssembly and run in a metered sandbox. A contract declares its capabilities — the primitives it may call and the state it may touch — and the runtime rejects any call outside that declaration.

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

Build

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

• Compute and storage are priced explicitly, so a contract’s cost follows from what it does.
• Declared state access lets independent contracts run in parallel on VectorLanes.
• Market calls from a contract pass Aegis pre-risk for the contract’s own account, like any other order.
• Deployment submits the module with its capability list; a module that calls an undeclared primitive is rejected.

The EVM Capsule is an isolated compatibility domain for Ethereum bytecode and tooling. It has its own gas and resource ceilings, reaches core assets only through a rate-limited gateway and can be halted by circuit breakers without affecting the core runtime.

The capsule is a compatibility boundary, not the core execution environment. Native market primitives are called from NexusWASM; the capsule connects to core assets only through its governed gateway.

Migration steps

• Deploy unchanged. Existing contracts and familiar tooling run inside the capsule, metered against its own ceilings.
• Bridge deliberately. Move assets through the rate-limited gateway, with route caps sized to your exposure.
• Measure. Identify where native performance or market access matters most — typically order handling, settlement and risk logic.
• Port. Re-implement those paths as NexusWASM contracts that call ApexMatch and Aegis directly, keeping the capsule version as a reference.
• Verify and retire. Replay the same inputs against both versions, move users to the native contracts once results match and wind down the capsule deployment.

Operators run the node client to replay finalized state, serve applications or, once admitted as validators, take proposer and committee duties under QSE. One client serves each role: configuration comes from the environment, and signing keys stay in an HSM or MPC signer.

# 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

The command names shown are illustrative. The operator client, its release-signing keys and network identifiers are issued with operator access — see validators.

Operating rules

• Verify every release signature before installation or upgrade.
• Reference keys by signer, never by file: validator keys do not belong on the node host.
• Export duty and service measurements to your own monitoring and alerting.
• Rotate signature suites through Q-Switch commands rather than ad-hoc re-keying.

Release notes accompany each NexusSDK version and are published in this gateway beside the documentation for that version. The version selector shows which edition you are reading.

Every release note records

• New, changed and removed interfaces, with an example of each new form.
• Deprecations, the replacement for each and the steps to migrate.
• Changes to signature suites or credential formats introduced through Q-Switch.
• Protocol parameters that affect node operators and validators.
• Security fixes, once disclosure has been coordinated.

You are reading the preview edition. Its interfaces are documented as engineered and may change before general availability; each change is recorded in the release notes of the version that introduces it.