Quick Start Guide

Build your first Based Terminal MiniApp in 5 minutes! This guide will walk you through creating a simple trading bot that monitors ETH prices and places orders.

Prerequisites

Node.js 16+ installed
Basic knowledge of JavaScript/TypeScript
Text editor or IDE

Step 1: Create Your Project

Option A: Vanilla JavaScript/TypeScript

# Create a new directory
mkdir my-first-miniapp
cd my-first-miniapp

# Initialize project
npm init -y

# Install the MiniApp SDK
npm install @basedone/miniapp-sdk

# Install development dependencies
npm install --save-dev vite typescript

Create index.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My First MiniApp</title>
</head>
<body>
  <div id="app">
    <h1>ETH Price Monitor</h1>
    <div id="status">Connecting...</div>
    <div id="price">--</div>
    <button id="buyButton" disabled>Buy 0.01 ETH</button>
  </div>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>

Create src/main.ts:

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

// Initialize the SDK
const client = new MiniAppSDK({
  appId: 'my-first-miniapp',
  debug: true,
  autoConnect: true
});

// Get DOM elements
const statusEl = document.getElementById('status')!;
const priceEl = document.getElementById('price')!;
const buyButton = document.getElementById('buyButton') as HTMLButtonElement;

// Handle connection
client.on('connected', async ({ sessionId }) => {
  statusEl.textContent = `Connected (${sessionId})`;

  // Request permissions
  await client.requestPermissions(['read_market_data', 'place_orders']);

  // Subscribe to ETH price
  await client.subscribeToMarkets(['ETH']);

  buyButton.disabled = false;
});

// Handle market data
client.on('market.bbo', (data) => {
  if (data.symbol === 'ETH') {
    priceEl.textContent = `ETH: $${data.price.toFixed(2)}`;
  }
});

// Handle buy button
buyButton.addEventListener('click', async () => {
  buyButton.disabled = true;
  try {
    const response = await client.placeOrder({
      symbol: 'ETH',
      side: 'buy',
      orderType: 'market',
      size: 0.01
    });

    if (response.success) {
      alert('Order placed successfully!');
    }
  } catch (error) {
    alert(`Order failed: ${error.message}`);
  } finally {
    buyButton.disabled = false;
  }
});

Add to package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

Run the dev server:

npm run dev

Option B: React Application

# Create React app with TypeScript
npx create-react-app my-first-miniapp --template typescript
cd my-first-miniapp

# Install MiniApp SDK
npm install @basedone/miniapp-sdk

Replace src/App.tsx:

import React from 'react';
import {
  MiniAppProvider,
  useMiniApp,
  useMarketData,
  useCommand
} from '@basedone/miniapp-sdk/react';

function App() {
  return (
    <MiniAppProvider config={{
      appId: 'my-first-miniapp',
      permissions: ['read_market_data', 'place_orders'],
      debug: true,
      autoConnect: true
    }}>
      <TradingWidget />
    </MiniAppProvider>
  );
}

function TradingWidget() {
  const { client, connected, sessionId } = useMiniApp();
  const marketData = useMarketData(['ETH', 'BTC']);
  const { execute: placeOrder, loading } = useCommand('order.submit');

  const handleQuickBuy = async (symbol: string) => {
    try {
      const result = await placeOrder({
        symbol,
        side: 'buy',
        orderType: 'market',
        size: 0.01
      });
      alert(`Order placed successfully!`);
    } catch (err: any) {
      alert(`Order failed: ${err.message}`);
    }
  };

  if (!connected) {
    return <div>Connecting to Based Terminal...</div>;
  }

  return (
    <div style={{ padding: '20px', fontFamily: 'monospace' }}>
      <h1>My First MiniApp</h1>
      <p>Session: {sessionId}</p>

      <div style={{ marginTop: '20px' }}>
        <h2>Market Data</h2>
        {Object.entries(marketData).map(([symbol, data]) => (
          <div key={symbol} style={{
            padding: '10px',
            margin: '10px 0',
            border: '1px solid #ccc',
            borderRadius: '4px'
          }}>
            <div style={{ fontSize: '18px', fontWeight: 'bold' }}>
              {symbol}
            </div>
            <div style={{ fontSize: '24px', color: '#00ff88' }}>
              ${data.price?.toFixed(2) || 'Loading...'}
            </div>
            <button
              onClick={() => handleQuickBuy(symbol)}
              disabled={loading}
              style={{
                marginTop: '10px',
                padding: '8px 16px',
                background: '#00ff88',
                border: 'none',
                borderRadius: '4px',
                cursor: loading ? 'not-allowed' : 'pointer'
              }}
            >
              {loading ? 'Placing...' : `Buy 0.01 ${symbol}`}
            </button>
          </div>
        ))}
      </div>
    </div>
  );
}

export default App;

Run the app:

npm start

Step 2: Understanding the Code

Core Concepts

1. SDK Initialization

const client = new MiniAppSDK({
  appId: 'my-first-miniapp',    // Unique identifier
  debug: true,                   // Enable console logging
  autoConnect: true              // Auto-connect on initialization
});

2. Connection Handling

client.on('connected', ({ sessionId, permissions }) => {
  console.log('Connected with session:', sessionId);
  console.log('Granted permissions:', permissions);
});

3. Permissions

// Request permissions
await client.requestPermissions([
  'read_market_data',
  'place_orders',
  'read_positions'
]);

// Check permissions
if (client.hasPermission('place_orders')) {
  // Can place orders
}

4. Market Data Subscription

// Subscribe to markets
await client.subscribeToMarkets(['ETH', 'BTC', 'SOL']);

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

5. Placing Orders

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

if (response.success) {
  console.log('Order placed!');
}

Step 3: Adding More Features

Add Price Alerts

let alertPrice = 2500;

client.on('market.bbo', (data) => {
  if (data.symbol === 'ETH' && data.price < alertPrice) {
    alert(`ETH dropped below $${alertPrice}!`);
  }
});

Add Stop Loss

await client.placeOrder({
  symbol: 'ETH',
  side: 'buy',
  orderType: 'market',
  size: 0.1,
  tpsl: {
    tpPrice: 3000,  // Take profit at $3000
    slPrice: 2400   // Stop loss at $2400
  }
});

Add Position Tracking

const positions = await client.getPositions();
positions.data?.positions.forEach(pos => {
  console.log(`${pos.symbol}: ${pos.size} units`);
});

Add Order History

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

// Get filled orders
const filledOrders = await client.getOrders(undefined, 'filled');

console.log(`Open: ${openOrders.data?.totalCount}`);
console.log(`Filled: ${filledOrders.data?.totalCount}`);

Step 4: Testing Your MiniApp

Development Testing

Run your development server

Start the dev server with npm run dev or npm start.

Open the Based Terminal

Navigate to the Based Terminal in your browser.

Load your MiniApp

Load your MiniApp from http://localhost:3000 (or your dev URL).

Testing Checklist

Connection established successfully
Permissions requested and granted
Market data updates in real-time
Orders can be placed
Error handling works correctly
Reconnection works after disconnect

Common Issues and Solutions

Issue: Not Connecting

Ensure you are running inside the Based Terminal iframe context.

if (window.parent === window) {
  console.error('Not running in iframe context');
}

Issue: Permission Denied

Request permissions explicitly before attempting restricted operations.

try {
  await client.requestPermissions(['place_orders']);
} catch (error) {
  console.error('Permission denied:', error);
}

Issue: Market Data Not Updating

Verify that the subscription succeeded and that event listeners are registered.

// Verify subscription
const result = await client.subscribeToMarkets(['ETH']);
console.log('Subscribed:', result);

// Check event listener
client.on('market.bbo', (data) => {
  console.log('Received:', data);
});

Next Steps

Now that you have a working MiniApp, explore more advanced features:

Batch Operations

// Place multiple orders at once
const orders = [
  { symbol: 'ETH', side: 'buy', orderType: 'market', size: 0.01 },
  { symbol: 'BTC', side: 'buy', orderType: 'market', size: 0.001 }
];

const response = await client.placeOrders(orders);
console.log(`${response.data?.successCount} orders placed`);

Real-time Position Updates

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

Wallet Address

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

Resources

Architecture Guide - Deep dive into how MiniApps work at a high level
API Reference - Complete SDK documentation
Sample App - Working code examples

PreviousIntro NextArchitecture

Last updated 27 minutes ago

hashtagPrerequisites

hashtagStep 1: Create Your Project

hashtagOption A: Vanilla JavaScript/TypeScript

hashtagOption B: React Application

hashtagStep 2: Understanding the Code

hashtagCore Concepts

hashtagStep 3: Adding More Features

hashtagAdd Price Alerts

hashtagAdd Stop Loss

hashtagAdd Position Tracking

hashtagAdd Order History

hashtagStep 4: Testing Your MiniApp

hashtagDevelopment Testing

hashtagRun your development server

hashtagOpen the Based Terminal

hashtagLoad your MiniApp

hashtagTesting Checklist

hashtagCommon Issues and Solutions

hashtagIssue: Not Connecting

hashtagIssue: Permission Denied

hashtagIssue: Market Data Not Updating

hashtagNext Steps

hashtagBatch Operations

hashtagReal-time Position Updates

hashtagWallet Address

hashtagResources