TypeScript SDK

npm install @nexus/sdk

import { NexusClient, Wallet } from '@nexus/sdk';

const client = new NexusClient(config: NexusConfig, wallet?: Wallet | string);

interface NexusConfig {
  rpcUrl: string;              // Primary RPC URL
  rpcUrls?: string[];          // Fallback URLs for failover
  wsUrl?: string;              // WebSocket URL for events
  network?: 'mainnet' | 'testnet' | 'regtest';
  timeout?: number;            // Request timeout (ms)
  retries?: number;            // Retry attempts
  maxRequestsPerSecond?: number; // Rate limiting
}

const height = await client.getBlockHeight();
// Returns: number

const balance = await client.getBalance('bcrt1p...');
// Returns: string (hex)

const { balance, balanceDecimal } = await client.getTokenBalance(
  '0x1234...', // token contract ID
  'bcrt1p...'  // address (optional, uses wallet if not provided)
);

const result = await client.deployContract(
  wasmBytes,      // Uint8Array
  ['arg1', 100],  // init arguments
  2000000         // gas limit
);

// Returns: DeploymentResult
interface DeploymentResult {
  contractId: string;
  txHash: string;
  gasUsed: number;
  blockHeight: number;
}

const result = await client.callContract(
  '0x1234...',    // contract ID
  'transfer',     // function name
  ['0xabcd...', '1000'], // arguments
  100000          // gas limit
);

// Returns: ContractCallResult
interface ContractCallResult<T> {
  success: boolean;
  result?: T;
  error?: string;
  gasUsed: number;
  events: ContractEvent[];
  logs: string[];
}

const balance = await client.queryContract(
  '0x1234...',
  'balanceOf',
  ['0xabcd...']
);

const vaultInfo = await client.getVaultAddress(2016); // 2 week timelock

// Returns:
interface VaultInfo {
  vaultAddress: string;   // Bitcoin address for deposits
  l2Address: string;      // Your L2 address
  protocolKey: string;    // Protocol public key
  timelock: number;       // CSV timelock blocks
}

const pubkey = await client.resolveAddress('bcrt1p...');
// Returns: string (64 char hex, no 0x prefix)

const txHash = await client.sendTransaction(signedTx);

const tx = await client.waitForTransaction(
  '0x1234...',
  1,      // confirmations
  60000   // timeout ms
);

const events = await client.getEvents({
  contractId: '0x1234...',
  eventName: 'Transfer',
  fromBlock: 100,
  toBlock: 200,
}, 100, 0);

const subscriptionId = client.subscribeToEvents(
  { contractId: '0x1234...' },
  (event) => {
    console.log('Event:', event);
  }
);

// Unsubscribe
client.unsubscribeFromEvents(subscriptionId);

import { Wallet } from '@nexus/sdk';

// Generate new wallet
const wallet = new Wallet(undefined, 'regtest');

// From WIF
const wallet = new Wallet('cVt4o7BGAig1UXywgGSmARhxMdzP5qvQsxKkSsc1XEkw3tDTQFpy', 'regtest');

// From private key bytes
const wallet = new Wallet(privateKeyBytes, 'regtest');

const keyPair = Wallet.generate('regtest');
// Returns: WalletKeyPair

const wallet = Wallet.fromWIF('cVt4o7...', 'regtest');

const wallet = Wallet.fromMnemonic(
  'abandon abandon abandon...',
  'regtest',
  "m/86'/0'/0'/0/0"  // BIP86 Taproot path
);

const mnemonic = Wallet.generateMnemonic(128); // 12 words
const mnemonic = Wallet.generateMnemonic(256); // 24 words

const address = wallet.getAddress();
// Returns: 'bcrt1p...' (regtest) or 'bc1p...' (mainnet)

const pubkey = wallet.getXOnlyPubkey();
// Returns: Uint8Array (32 bytes)

const pubkeyHex = wallet.getXOnlyPubkeyHex();
// Returns: string (64 chars)

const vaultAddress = wallet.deriveVaultAddress({
  protocolKey: protocolKeyBytes,  // 32-byte Uint8Array
  timelock: 2016,                 // CSV timelock
});

const signature = await wallet.sign(messageBytes);
// Returns: Uint8Array (65 bytes: 64 sig + 1 recovery)

const wif = wallet.exportWIF();

import { TokenContract } from '@nexus/sdk';

const token = new TokenContract(client, '0x1234...');

// Get balance
const { balance, balanceDecimal } = await token.balanceOf('bcrt1p...');

// Transfer tokens
await token.transfer('bcrt1p...', '1000000');

// Approve spender
await token.approve('0xspender...', '1000000');

// Transfer from (requires approval)
await token.transferFrom('0xfrom...', '0xto...', '1000000');

// Query metadata
const name = await token.name();
const symbol = await token.symbol();
const decimals = await token.decimals();
const totalSupply = await token.totalSupply();

import { ContractCallBuilder } from '@nexus/sdk';

const builder = new ContractCallBuilder(contractId, 'transfer', wallet)
  .withArgs('0xto...', '1000')
  .gas(100000)
  .value(0);

const signedTx = await builder.buildAndSign();
const txHash = await client.sendTransaction(signedTx);

import { DeploymentBuilder } from '@nexus/sdk';

const builder = new DeploymentBuilder(wallet)
  .code(wasmBytes)
  .initArgs('TokenName', 'TKN', 18, 1000000)
  .gas(2000000);

const signedTx = await builder.buildAndSign();

import { EventListener } from '@nexus/sdk';

const listener = new EventListener('ws://localhost:8546');
listener.connect();

const subId = listener.subscribe(
  { contractId: '0x1234...' },
  (event) => console.log(event)
);

// Cleanup
listener.unsubscribe(subId);
listener.disconnect();

import { PollingEventListener } from '@nexus/sdk';

const listener = new PollingEventListener(
  (filter) => client.getEvents(filter),
  5000  // poll interval ms
);

listener.start();
const subId = listener.subscribe(filter, callback);

// Cleanup
listener.stop();

interface ContractEvent {
  contractId: string;
  eventName: string;
  data: any;
  blockHeight: number;
  txHash: string;
  logIndex: number;
}

interface EventFilter {
  contractId?: string;
  eventName?: string;
  fromBlock?: number;
  toBlock?: number;
}

interface SignedTransaction {
  tx_id: string;
  from: string;
  tx_type: TransactionType;
  gas_limit: number;
  gas_price: number;
  nonce: number;
  signature: string;
}