Extended TypeScript Trading SDK

⚠️ Unofficial SDK: This is an unofficial TypeScript SDK for Extended Exchange, built and maintained by the community. It is not officially supported by Extended.

TypeScript client for Extended Exchange API.

About Extended Exchange

Extended is a perpetual DEX (Decentralized Exchange), built by an ex-Revolut team. As of now, Extended offers perpetual contracts on both crypto and TradFi assets, with USDC as collateral and leverage of up to 100x.

This SDK provides full type safety and modern async/await patterns for interacting with the Extended Exchange API.

Installation

npm install extended-typescript-sdk

Prerequisites

• Node.js 18+ or TypeScript 5.3+
• No Rust required - The SDK ships with pre-built WASM signer

Quick Start

1. Initialize the SDK

The SDK ships with pre-built WASM signer - no build step required!

import {
  initWasm,
  TESTNET_CONFIG,
  StarkPerpetualAccount,
  PerpetualTradingClient,
} from 'extended-typescript-sdk';
import Decimal from 'decimal.js';

// Initialize WASM module (MUST be called before using any crypto functions)
// Automatically loads the correct WASM for Node.js or browser
await initWasm();

// Create a Stark account
const starkAccount = new StarkPerpetualAccount(
  vaultId,           // number
  privateKey,        // Hex string (e.g., "0x123...")
  publicKey,         // Hex string
  apiKey             // string
);

// Create trading client
const tradingClient = new PerpetualTradingClient(TESTNET_CONFIG, starkAccount);

2. Place an Order

import { OrderSide } from 'extended-typescript-sdk';
import Decimal from 'decimal.js';

const placedOrder = await tradingClient.placeOrder({
  marketName: 'BTC-USD',
  amountOfSynthetic: new Decimal('1'),
  price: new Decimal('63000.1'),
  side: OrderSide.SELL,
});

console.log('Placed order:', placedOrder);

// Cancel the order
await tradingClient.orders.cancelOrder(placedOrder.id);

3. Get Account Information

// Get balance
const balance = await tradingClient.account.getBalance();
console.log('Balance:', balance.toPrettyJson());

// Get positions
const positions = await tradingClient.account.getPositions();
console.log('Positions:', positions.toPrettyJson());

// Get open orders
const openOrders = await tradingClient.account.getOpenOrders();
console.log('Open orders:', openOrders.toPrettyJson());

4. Onboarding (User Client)

import { UserClient, TESTNET_CONFIG } from 'extended-typescript-sdk';

// Create user client
const userClient = new UserClient(TESTNET_CONFIG, () => ethPrivateKey);

// Onboard new account
const account = await userClient.onboard();

// Get API key
const apiKey = await userClient.createAccountApiKey(account.account, 'My trading key');

// Use the account
const starkAccount = new StarkPerpetualAccount(
  account.account.l2Vault,
  account.l2KeyPair.privateHex,
  account.l2KeyPair.publicHex,
  apiKey
);

const client = new PerpetualTradingClient(TESTNET_CONFIG, starkAccount);

5. Stream Data

import { PerpetualStreamClient, TESTNET_CONFIG } from 'extended-typescript-sdk';

const streamClient = new PerpetualStreamClient({
  apiUrl: TESTNET_CONFIG.streamUrl,
});

// Subscribe to orderbooks
const orderbookStream = streamClient.subscribeToOrderbooks({ marketName: 'BTC-USD' });
await orderbookStream.connect();

for await (const update of orderbookStream) {
  console.log('Orderbook update:', update);
}

// Subscribe to account updates
const accountStream = streamClient.subscribeToAccountUpdates(apiKey);
await accountStream.connect();

for await (const update of accountStream) {
  console.log('Account update:', update);
}

WASM Signer

The SDK includes a pre-built WASM signer that works in both Node.js and browser environments. No Rust installation is required to use the SDK.

Using the Pre-built Signer

The SDK ships with pre-built WASM files. Simply use the SDK:

import { initWasm, sign } from 'extended-typescript-sdk';

await initWasm(); // Automatically loads the correct WASM for your environment
const [r, s] = sign(privateKey, msgHash);

The signer automatically detects your environment (Node.js or browser) and loads the appropriate WASM module.

Building Your Own WASM Signer

If you want to build your own WASM signer (requires Rust and wasm-pack):

npm run build:signer:custom

Prerequisites:

1. Install Rust: https://www.rust-lang.org/tools/install
2. Install wasm-pack: cargo install wasm-pack

This will build both Node.js and browser targets and replace the shipped WASM signer.

Implementation

The WASM signer uses starknet-crypto crate for cryptographic operations. It's production-ready and tested for compatibility with Extended Exchange API.

API Documentation

Trading Client

import { PerpetualTradingClient, TESTNET_CONFIG } from 'extended-typescript-sdk';

const client = new PerpetualTradingClient(config, account);

// Place order
await client.placeOrder({
  marketName: 'BTC-USD',
  amountOfSynthetic: new Decimal('1'),
  price: new Decimal('63000'),
  side: OrderSide.BUY,
});

// Account module
await client.account.getBalance();
await client.account.getPositions();
await client.account.getOpenOrders();
await client.account.updateLeverage('BTC-USD', new Decimal('10'));

// Orders module
await client.orders.cancelOrder(orderId);
await client.orders.cancelOrderByExternalId(externalId);
await client.orders.massCancel({ markets: ['BTC-USD'] });

// Markets module
await client.marketsInfo.getMarkets();
await client.marketsInfo.getMarketStatistics('BTC-USD');
await client.marketsInfo.getOrderbookSnapshot('BTC-USD');

User Client (Onboarding)

import { UserClient } from 'extended-typescript-sdk';

const userClient = new UserClient(config, () => ethPrivateKey);

// Onboard new account
const account = await userClient.onboard();

// Onboard subaccount
const subaccount = await userClient.onboardSubaccount(1, 'My subaccount');

// Get all accounts
const accounts = await userClient.getAccounts();

// Create API key
const apiKey = await userClient.createAccountApiKey(account.account, 'description');

Stream Client

import { PerpetualStreamClient } from 'extended-typescript-sdk';

const streamClient = new PerpetualStreamClient({ apiUrl: config.streamUrl });

// Subscribe to orderbooks
const orderbookStream = streamClient.subscribeToOrderbooks({
  marketName: 'BTC-USD',
  depth: 10,
});

// Subscribe to public trades
const tradesStream = streamClient.subscribeToPublicTrades('BTC-USD');

// Subscribe to funding rates
const fundingStream = streamClient.subscribeToFundingRates('BTC-USD');

// Subscribe to account updates (requires API key)
const accountStream = streamClient.subscribeToAccountUpdates(apiKey);

Environment Configuration

The SDK supports different environments:

import { TESTNET_CONFIG, MAINNET_CONFIG } from 'extended-typescript-sdk';

// Use testnet
const client = new PerpetualTradingClient(TESTNET_CONFIG, account);

// Use mainnet
const client = new PerpetualTradingClient(MAINNET_CONFIG, account);

TypeScript Support

This SDK is written in TypeScript and provides full type definitions. All types are exported:

import {
  OrderSide,
  OrderType,
  OrderStatus,
  TimeInForce,
  StarkPerpetualAccount,
  PerpetualTradingClient,
  UserClient,
  PerpetualStreamClient,
  // ... and more
} from 'extended-typescript-sdk';

Error Handling

The SDK provides specific error types:

import {
  X10Error,
  RateLimitException,
  NotAuthorizedException,
  SubAccountExists,
} from 'extended-typescript-sdk';

try {
  await client.placeOrder({ ... });
} catch (error) {
  if (error instanceof RateLimitException) {
    // Handle rate limit
  } else if (error instanceof NotAuthorizedException) {
    // Handle authentication error
  }
}

Examples

See examples/ directory for complete examples:

• Basic order placement
• Onboarding flow
• Stream subscriptions
• Market data access
• Account management

WASM Performance

The WASM signer provides ~90-95% of native Rust performance:

Native Rust:          ~50μs per signature
WASM (Rust):          ~55μs per signature  (10% slower)
Pure JavaScript:      ~500μs per signature (10x slower)

The performance difference is negligible in real-world applications.

Building the SDK

For Users (No Build Required)

The SDK ships with pre-built WASM signer - just install and use:

npm install extended-typescript-sdk

For Developers

If you're developing the SDK or want to build your own WASM signer:

# Install dependencies
npm install

# Build WASM signer (requires Rust and wasm-pack)
npm run build:signer

# Build TypeScript
npm run build:ts

# Build everything
npm run build  # Builds both WASM signer and TypeScript

# Build custom WASM signer (for users who want to replace shipped WASM)
npm run build:signer:custom

Build Commands

• npm run build - Builds WASM signer and TypeScript (full build)
• npm run build:signer - Builds WASM signer for both Node.js and browser
• npm run build:signer:custom - Build your own WASM signer (requires Rust)
• npm run build:ts - Build TypeScript only
• npm run clean - Clean all build artifacts

Development Commands

# Run tests
npm test

# Lint
npm run lint

# Format code
npm run format

Contributing

1. Clone the repository
2. Install dependencies: npm install
3. Install Rust and wasm-pack (only if building WASM signer)
4. Build: npm run build
5. Run tests: npm test

License

MIT

Support

For issues and questions:

• GitHub: https://github.com/Bvvvp009/Extended-TS-SDK
• Documentation: https://api.docs.extended.exchange/
• Extended Exchange: https://extended.exchange/

Note: This is an unofficial, community-maintained SDK. For official support, please contact Extended Exchange directly.

API Coverage

See API_COVERAGE.md for complete API endpoint coverage analysis.

Standalone Signer Functions

The cryptographic signer functions are exported from the main SDK package for standalone use:

import { 
  initWasm, 
  sign, 
  pedersenHash,
  getOrderMsgHash,
  getTransferMsgHash,
  getWithdrawalMsgHash,
  generateKeypairFromEthSignature
} from 'extended-typescript-sdk';

// Initialize WASM module (required first!)
await initWasm();

// Sign a message hash
const privateKey = BigInt('0x...');
const msgHash = BigInt('0x...');
const [r, s] = sign(privateKey, msgHash);

// Compute Pedersen hash
const hash = pedersenHash(BigInt('0x123'), BigInt('0x456'));

// Generate order message hash (for custom order signing)
const orderHash = getOrderMsgHash({
  positionId: 12345,
  baseAssetId: '0x...',
  baseAmount: '1000000',
  // ... other order parameters
});

// Generate keypair from Ethereum signature (for onboarding)
const [privateKey, publicKey] = generateKeypairFromEthSignature(ethSignature);

All signer functions are documented with JSDoc comments. See the signer source code for detailed documentation.