API

Complete API documentation for the Based Terminal MiniApp SDK.

Table of Contents

• Installation

• Core SDK

• React Integration

• Types

• Permissions

• Events

• Error Handling

Installation

npm install @basedone/miniapp-sdk

Core SDK

MiniAppSDK Class

The main client for interacting with the Based Terminal.

Constructor

import { MiniAppSDK } from '@basedone/miniapp-sdk';

const client = new MiniAppSDK(config: MiniAppConfig);

MiniAppConfig:

interface MiniAppConfig {
  appId: string;                    // Required: Unique app identifier
  name?: string;                    // App display name
  url?: string;                     // App URL
  targetOrigin?: string;            // PostMessage target (default: '*')
  permissions?: AppPermission[];    // Initial permissions to request
  autoConnect?: boolean;            // Auto-connect on init (default: true)
  version?: string;                 // App version
  debug?: boolean;                  // Enable debug logging
  appSecret?: string;               // Optional HMAC signing secret
  sessionId?: string;               // Session ID (managed internally)
  tenantId?: string;                // Tenant ID for theming
}

Example:

const client = new MiniAppSDK({
  appId: 'my-trading-bot',
  name: 'Trading Bot',
  permissions: ['read_market_data', 'place_orders'],
  debug: true,
  autoConnect: true
});

Connection Methods

connect()

Establishes connection to the terminal.

async connect(): Promise<void>

Example:

await client.connect();

disconnect()

Closes the connection.

disconnect(): void

Example:

client.disconnect();

getConnectionState()

Returns current connection state.

getConnectionState(): ConnectionState

Returns:

interface ConnectionState {
  connected: boolean;
  sessionId?: string;
  permissions: Set<AppPermission>;
  lastHeartbeat?: number;
}

Permission Methods

requestPermissions()

Requests multiple permissions from the user.

async requestPermissions(permissions: AppPermission[]): Promise<AppPermission[]>

Example:

const granted = await client.requestPermissions([
  'read_market_data',
  'place_orders',
  'read_positions'
]);
console.log('Granted permissions:', granted);

hasPermission()

Checks if a specific permission is granted.

hasPermission(permission: AppPermission): boolean

Example:

if (client.hasPermission('place_orders')) {
  await client.placeOrder(orderData);
}

Trading Methods

placeOrder()

Places a single order.

async placeOrder(order: SubmitOrderCommand): Promise<CommandResponse<"order.submit">>

SubmitOrderCommand:

interface SubmitOrderCommand {
  symbol: string;                                // Trading symbol (e.g., 'ETH')
  side: 'buy' | 'sell';                          // Order side
  orderType: 'market' | 'limit' | 'stop' | 'stop_limit';
  size?: number;                                 // Order size
  price?: number;                                // Limit price (required for limit orders)
  stopPrice?: number;                            // Stop price (required for stop orders)
  reduceOnly?: boolean;                          // Reduce-only flag
  postOnly?: boolean;                            // Post-only flag
  tpsl?: {                                       // Take profit / Stop loss
    tpPrice?: number | null;                     // Take profit price
    tpGainPercent?: number | null;               // TP as percentage gain
    slPrice?: number | null;                     // Stop loss price
    slLossPercent?: number | null;               // SL as percentage loss
  };
  tif?: 'Gtc' | 'Ioc' | 'Alo';                   // Time in force
}

Example:

// Market order
const response = await client.placeOrder({
  symbol: 'ETH',
  side: 'buy',
  orderType: 'market',
  size: 0.1
});

// Limit order with TP/SL
const response = await client.placeOrder({
  symbol: 'ETH',
  side: 'buy',
  orderType: 'limit',
  price: 2500,
  size: 0.1,
  tpsl: {
    tpPrice: 3000,    // Take profit at $3000
    slPrice: 2400     // Stop loss at $2400
  }
});

placeOrders()

Places multiple orders in a batch (up to 50).

async placeOrders(orders: SubmitOrderCommand[]): Promise<CommandResponse<"order.submitMultiple">>

Example:

const orders = [
  { symbol: 'ETH', side: 'buy', orderType: 'market', size: 0.1 },
  { symbol: 'BTC', side: 'buy', orderType: 'limit', price: 50000, size: 0.01 },
  { symbol: 'SOL', side: 'buy', orderType: 'market', size: 5 }
];

const response = await client.placeOrders(orders);

if (response.success && response.data) {
  const { successCount, failureCount, results } = response.data;
  console.log(`Batch: ${successCount} succeeded, ${failureCount} failed`);

  results.forEach((result, idx) => {
    if (result.success) {
      console.log(`Order ${idx}: Success`);
    } else {
      console.error(`Order ${idx}: Failed - ${result.status.error}`);
    }
  });
}

cancelOrder()

Cancels a single order.

async cancelOrder(orderId: string, symbol?: string): Promise<CommandResponse<"order.cancel">>

Example:

await client.cancelOrder('order-123', 'ETH');

cancelOrders()

Cancels multiple orders in a batch (up to 50).

async cancelOrders(orders: CancelOrderCommand[]): Promise<CommandResponse<"order.cancelMultiple">>

Example:

const ordersToCancel = [
  { orderId: 'order-123', symbol: 'ETH' },
  { orderId: 'order-456', symbol: 'BTC' }
];

const response = await client.cancelOrders(ordersToCancel);
console.log(`${response.data?.successCount} orders cancelled`);

getOrders()

Queries orders with optional filtering.

async getOrders(
  symbol?: string,
  status?: 'open' | 'filled' | 'cancelled' | 'partial' | 'all'
): Promise<CommandResponse<"orders.query">>

Example:

// Get all open orders
const openOrders = await client.getOrders(undefined, 'open');

// Get filled orders for ETH
const ethFilled = await client.getOrders('ETH', 'filled');

// Process results
if (openOrders.success && openOrders.data) {
  const { orders, totalCount } = openOrders.data;
  console.log(`Found ${totalCount} open orders`);

  orders.forEach(order => {
    console.log(`${order.symbol}: ${order.side} ${order.size} @ ${order.price || 'market'}`);
  });
}

getPositions()

Retrieves current positions.

async getPositions(symbol?: string): Promise<CommandResponse<"position.query">>

Example:

// Get all positions
const positions = await client.getPositions();

// Get positions for specific symbol
const ethPositions = await client.getPositions('ETH');

if (positions.success && positions.data) {
  positions.data.positions.forEach(pos => {
    console.log(`${pos.symbol}: ${pos.size} units, PnL: $${pos.unrealizedPnl}`);
  });
}

getAccount()

Retrieves account balance information.

async getAccount(): Promise<CommandResponse<"wallet.balance">>

Example:

const account = await client.getAccount();
if (account.success && account.data) {
  console.log('Total USD Value:', account.data.totalUsdValue);
}

getWalletAddress()

Retrieves the connected wallet address.

async getWalletAddress(): Promise<string>

Example:

const address = await client.getWalletAddress();
console.log('Connected wallet:', address);

Market Data Methods

subscribeToMarkets()

Subscribes to market data for specified symbols.

async subscribeToMarkets(symbols: string[]): Promise<{
  subscriptionId: string;
  unsubscribe: () => Promise<void>;
}>

Example:

const subscription = await client.subscribeToMarkets(['ETH', 'BTC', 'SOL']);

// Unsubscribe later
await subscription.unsubscribe();

subscribe()

Generic subscription method for various data types.

async subscribe(
  dataType: MiniAppSubscriptionType,
  payload?: SubscriptionPayload
): Promise<{ subscriptionId: string; unsubscribe: () => Promise<void> }>

MiniAppSubscriptionType:

enum MiniAppSubscriptionType {
  MARKET_PRICES = 'market.prices',
  BEST_BID_OFFER = 'market.bbo',
  ORDER_UPDATES = 'order.update',
  POSITION_UPDATES = 'position.update',
  TRADE_UPDATES = 'trade.update',
  ACCOUNT_UPDATES = 'account.update',
  USER_SETTINGS = 'user.settings',
  NAVIGATION_UPDATES = 'navigation.update'
}

Example:

const sub = await client.subscribe(
  MiniAppSubscriptionType.MARKET_PRICES,
  'ETH'
);

unsubscribe()

Unsubscribes from a data stream.

async unsubscribe(subscriptionId: string): Promise<void>

Command Execution

sendCommand()

Generic method to send any command.

async sendCommand<T extends CommandType>(
  commandName: T,
  data: CommandPayload<T>
): Promise<CommandResponse<T>>

Available Commands:

type CommandType =
  // Order commands
  | 'order.populate'         // Populate order form
  | 'order.submit'           // Submit order
  | 'order.submitMultiple'   // Submit multiple orders
  | 'order.cancel'           // Cancel order
  | 'order.cancelMultiple'   // Cancel multiple orders
  | 'order.modify'           // Modify order
  | 'orders.query'           // Query orders

  // Leverage commands
  | 'leverage.query'         // Query leverage settings
  | 'leverage.update'        // Update leverage

  // Position commands
  | 'position.query'         // Query positions
  | 'position.close'         // Close position

  // Wallet commands
  | 'wallet.balance'         // Get balance
  | 'wallet.address'         // Get wallet address

  // Notification commands
  | 'notification.success'   // Show success notification
  | 'notification.error'     // Show error notification
  | 'notification.warning'   // Show warning notification
  | 'notification.info'      // Show info notification

  // Navigation commands
  | 'navigation.navigate'    // Navigate to symbol
  | 'navigation.status'      // Get current navigation

  // Chart commands
  | 'chart.draw'             // Draw on chart

  // Analytics commands
  | 'analytics.query';       // Query analytics data

Example:

// Populate order form
await client.sendCommand('order.populate', {
  symbol: 'ETH',
  side: 'buy',
  orderType: 'limit',
  price: 2500,
  size: 0.1
});

// Show notification
await client.sendCommand('notification.success', {
  message: 'Order placed successfully!'
});

Event Methods

on()

Registers an event listener.

on(event: ExtendedEventType, handler: Function): void

Event Types:

type ExtendedEventType =
  // Connection events
  | 'connected'              // Connection established
  | 'disconnected'           // Connection lost
  | 'error'                  // Error occurred

  // Market events
  | 'market.ticker'          // Market ticker update
  | 'market.bbo'             // Best bid/offer update
  | 'market.prices'          // Price updates for multiple symbols
  | 'market.trades'          // Trade executed

  // Order & Position events
  | 'order.status'           // Order status change
  | 'order.update'           // Order update
  | 'position.update'        // Position changed

  // Wallet events
  | 'wallet.update'          // Balance changed
  | 'wallet.switch'          // Wallet switched

  // UI events
  | 'navigation.update'      // Navigation/symbol changed
  | 'theme.change'           // Theme changed

  // Auth & Permission events
  | 'auth.status'            // Auth status changed
  | 'permission.change'      // Permissions changed
  | 'permission.granted'     // New permission granted

  // System events
  | 'connection.status'      // Connection status changed
  | 'notification';          // Notification received

Example:

// Connection events
client.on('connected', ({ sessionId, permissions }) => {
  console.log('Connected:', sessionId);
});

client.on('disconnected', () => {
  console.log('Disconnected');
});

// Market data
client.on('market.bbo', (data) => {
  console.log(`${data.symbol}: $${data.price}`);
});

// Order updates
client.on('order.update', (order) => {
  console.log(`Order ${order.orderId} updated: ${order.status}`);
});

// Position updates
client.on('position.update', (position) => {
  console.log(`Position ${position.symbol} updated`);
});

// Wallet events
client.on('wallet.switch', (event) => {
  console.log('Wallet switched to:', event.address);
});

off()

Removes an event listener.

off(event: ExtendedEventType, handler: Function): void

Example:

const handler = (data) => console.log(data);
client.on('market.bbo', handler);

// Remove listener
client.off('market.bbo', handler);

emit()

Emits an event (internal use).

emit(event: ExtendedEventType, data: any): void

Theme Management

applyTheme()

Applies the terminal's theme to your MiniApp.

async applyTheme(): Promise<void>

Example:

await client.applyTheme();

getThemeManager()

Gets the theme manager instance.

getThemeManager(): ThemeManager

Example:

const themeManager = client.getThemeManager();
const currentTheme = themeManager.getTheme();
console.log('Current theme:', currentTheme);

Cleanup

destroy()

Cleans up the SDK instance and removes all listeners.

destroy(): void

Example:

client.destroy();

React Integration

MiniAppProvider

Context provider for React applications.

import { MiniAppProvider } from '@basedone/miniapp-sdk/react';

<MiniAppProvider config={config}>
  {children}
</MiniAppProvider>

Props:

interface MiniAppProviderProps {
  config: MiniAppConfig;
  children: ReactNode;
  autoConnect?: boolean;               // Default: true
  autoRequestPermissions?: boolean;    // Default: true
  defaultMarketSubscriptions?: string[]; // Default: []
}

Example:

function App() {
  return (
    <MiniAppProvider
      config={{
        appId: 'my-app',
        permissions: ['read_market_data', 'place_orders'],
        debug: true
      }}
      autoConnect={true}
      autoRequestPermissions={true}
      defaultMarketSubscriptions={['ETH', 'BTC']}
    >
      <TradingApp />
    </MiniAppProvider>
  );
}

Hooks

useMiniApp()

Main hook for accessing the SDK client and state.

function useMiniApp(): {
  client: MiniAppSDK | null;
  connected: boolean;
  sessionId?: string;
  connecting: boolean;
  permissions: AppPermission[];
  hasPermission: (permission: AppPermission) => boolean;
  requestPermission: (permission: AppPermission) => Promise<boolean>;
  requestTradingPermissions: () => Promise<AppPermission[]>;
  marketData: Record<string, any>;
  positions: any[];
  balances: Record<string, any>;
  orders: Order[];
  userAddress: string | null;
  loading: boolean;
  error: Error | null;
  // ... and more
}

Example:

function TradingWidget() {
  const {
    client,
    connected,
    sessionId,
    marketData,
    placeOrder,
    loading
  } = useMiniApp();

  if (!connected) return <div>Connecting...</div>;

  return (
    <div>
      <p>Session: {sessionId}</p>
      <div>ETH: ${marketData.ETH?.price}</div>
    </div>
  );
}

useCommand()

Hook for executing commands with loading state.

function useCommand<T extends CommandType>(commandType: T): {
  execute: (data: CommandPayload<T>) => Promise<CommandResponse<T>>;
  loading: boolean;
  error: Error | null;
  response: CommandResponse | null;
}

Example:

function OrderForm() {
  const { execute: placeOrder, loading, error } = useCommand('order.submit');

  const handleSubmit = async () => {
    const result = await placeOrder({
      symbol: 'ETH',
      side: 'buy',
      orderType: 'market',
      size: 0.1
    });

    if (result.success) {
      alert('Order placed!');
    }
  };

  return (
    <button onClick={handleSubmit} disabled={loading}>
      {loading ? 'Placing...' : 'Place Order'}
    </button>
  );
}

useMarketData()

Hook for subscribing to market data.

function useMarketData(symbols: string[]): Record<string, any>

Example:

function PriceDisplay() {
  const marketData = useMarketData(['ETH', 'BTC', 'SOL']);

  return (
    <div>
      {Object.entries(marketData).map(([symbol, data]) => (
        <div key={symbol}>
          {symbol}: ${data.price?.toFixed(2)}
        </div>
      ))}
    </div>
  );
}

usePositions()

Hook for tracking positions.

function usePositions(sdk: MiniAppSDK | null): {
  positions: any[];
  refresh: () => Promise<void>;
  loading: boolean;
}

Example:

function PositionsList() {
  const { client } = useMiniApp();
  const { positions, refresh, loading } = usePositions(client);

  return (
    <div>
      {positions.map(pos => (
        <div key={pos.symbol}>
          {pos.symbol}: {pos.size} units
        </div>
      ))}
      <button onClick={refresh}>Refresh</button>
    </div>
  );
}

useWalletAddress()

Hook for accessing wallet address.

function useWalletAddress(): {
  address: string | null;
}

Example:

function WalletDisplay() {
  const { address } = useWalletAddress();

  return <div>Wallet: {address || 'Not connected'}</div>;
}

useTheme()

Hook for theme management.

function useTheme(): {
  theme: Theme | null;
  applyTheme: () => Promise<void>;
  loading: boolean;
}

Example:

function ThemeSync() {
  const { theme, applyTheme } = useTheme();

  useEffect(() => {
    applyTheme();
  }, []);

  return <div>Theme: {theme?.mode}</div>;
}

useEvent()

Hook for subscribing to events.

function useEvent<T = any>(
  sdk: MiniAppSDK | null,
  eventType: ExtendedEventType,
  handler: (data: T) => void
): void

Example:

function OrderMonitor() {
  const { client } = useMiniApp();

  useEvent(client, 'order.update', (order) => {
    console.log('Order updated:', order);
  });

  return <div>Monitoring orders...</div>;
}

Types

Order Types

interface Order {
  orderId: string;
  clientOrderId?: string;
  symbol: string;
  side: 'buy' | 'sell';
  orderType: 'market' | 'limit' | 'stop' | 'stop_limit';
  price?: number;
  stopPrice?: number;
  size: number;
  filledSize: number;
  remainingSize: number;
  status: 'open' | 'partial' | 'cancelled' | 'filled';
  createdAt: number;
  updatedAt: number;
  tpsl?: {
    tpPrice?: number;
    slPrice?: number;
  };
}

Response Types

interface CommandResponse<T extends CommandType> {
  success: boolean;
  data?: CommandResponsePayload<T>;
  error?: string;
  timestamp?: number;
}

Order Status Types (Discriminated Union)

type OrderStatus =
  | { resting: { oid: string } }
  | { filled: { oid: string; totalSz: string; avgPx: string } }
  | { error: string };

// Type guards
function isRestingStatus(status: OrderStatus): status is { resting: { oid: string } };
function isFilledStatus(status: OrderStatus): status is { filled: { oid: string; totalSz: string; avgPx: string } };
function isErrorStatus(status: OrderStatus): status is { error: string };

Permissions

Permission Types

type AppPermission =
  // Market data permissions
  | 'read_market_data'
  | 'read_orderbook'
  | 'read_candles'

  // Account permissions
  | 'read_account'
  | 'read_positions'
  | 'read_orders'
  | 'read_balance'
  | 'read_trades'

  // Trading permissions
  | 'place_orders'
  | 'cancel_orders'
  | 'modify_orders'
  | 'populate_orders'

  // UI permissions
  | 'read_navigation'
  | 'write_navigation'
  | 'write_chart'
  | 'send_notifications'

  // User settings
  | 'read_user_settings'
  | 'modify_user_settings'

  // Advanced permissions
  | 'execute_strategies'
  | 'access_analytics';

Events

See the Event Methods section for complete event documentation.

Error Handling

Error Types

enum MiniAppErrorCode {
  PERMISSION_DENIED = 'PERMISSION_DENIED',
  INVALID_MESSAGE = 'INVALID_MESSAGE',
  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
  VALIDATION_ERROR = 'VALIDATION_ERROR',
  ORDER_FAILED = 'ORDER_FAILED',
  SUBSCRIPTION_FAILED = 'SUBSCRIPTION_FAILED',
  AUTHENTICATION_FAILED = 'AUTHENTICATION_FAILED',
  CONNECTION_ERROR = 'CONNECTION_ERROR',
  INVALID_CONFIGURATION = 'INVALID_CONFIGURATION'
}

Error Handling Pattern

try {
  await client.placeOrder(orderData);
} catch (error) {
  if (error.code === 'PERMISSION_DENIED') {
    // Request permission
    await client.requestPermissions(['place_orders']);
  } else if (error.code === 'VALIDATION_ERROR') {
    // Fix validation error
    console.error('Invalid order data:', error.message);
  } else {
    // Handle other errors
    console.error('Order failed:', error);
  }
}