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 (npm run dev or npm start)
Open the Based Terminal
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

Solution: Ensure you're running inside the Based Terminal iframe context.

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

Issue: Permission Denied

Solution: Request permissions explicitly:

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

Issue: Market Data Not Updating

Solution: Check subscription and event listeners:

// 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 1 month 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

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