alpha-cli-toolkit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linkxee-Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# 🧠 Alpha CLI — Autonomous Agent Onchain Toolkit
+
+> A terminal-first autonomous agent for crypto & TradFi markets.  
+> Powered by **Nansen** (on-chain analytics) + **Yahoo Finance** (traditional markets) with **Phantom Wallet** authentication.
+
+Built for the [Nansen CLI Build Challenge](https://nansen.ai).
+
+---
+
+## Architecture
+
+```
+alpha-cli/
+├── backend/          Express + MongoDB API server
+│   ├── src/
+│   │   ├── controllers/   Route handlers (auth, market, triggers)
+│   │   ├── middleware/     JWT authentication guard
+│   │   ├── models/         Mongoose schemas (User, Trigger, Position)
+│   │   ├── routes/         Express route definitions
+│   │   └── services/       Nansen API, Yahoo Finance, Trigger Engine
+│   └── index.js           Server entrypoint
+├── cli/              Command-line interface
+│   ├── bin/alpha.js       CLI entrypoint (Commander.js)
+│   └── utils/auth.js      Phantom wallet auth flow via browser
+└── (alpha-cli-ui/)   Next.js Phantom Wallet authentication UI
+```
+
+### Data Flow
+
+```
+CLI (alpha login) → opens browser → Next.js UI → Phantom wallet sign
+  → Backend verifies signature → returns JWT → CLI stores JWT locally
+  → all subsequent CLI commands send JWT in Authorization header
+```
+
+---
+
+## Setup
+
+### Prerequisites
+
+- **Node.js** ≥ 18
+- **MongoDB** running locally (or a remote URI)
+- **Phantom Wallet** browser extension
+
+### 1. Backend
+
+```bash
+cd backend
+cp .env.example .env     # Edit with your MongoDB URI & secrets
+npm install
+npm run dev              # Starts on http://localhost:4000
+```
+
+### 2. Auth UI
+
+```bash
+cd ../alpha-cli-ui       # Separate repo
+npm install
+npm run dev              # Starts on http://localhost:3000
+```
+
+### 3. CLI
+
+```bash
+cd ../cli
+npm install
+npm link                 # Makes `alpha` available globally
+```
+
+---
+
+## CLI Commands
+
+### Authentication
+
+| Command         | Description                               |
+|-----------------|-------------------------------------------|
+| `alpha login`   | Open browser → Phantom sign → store JWT   |
+| `alpha logout`  | Clear stored authentication session       |
+| `alpha status`  | Check auth status & backend health        |
+
+### Market Data
+
+| Command                | Description                                       |
+|------------------------|---------------------------------------------------|
+| `alpha market`         | Trending crypto via Nansen smart-money data        |
+| `alpha market --sp500` | Trending S&P 500 stocks via Yahoo Finance          |
+| `alpha market --nsd`   | Trending NASDAQ stocks via Yahoo Finance           |
+| `alpha lookup <id>`    | Deep dive into an asset (crypto or stock ticker)   |
+| `alpha watch <asset>`  | Live-poll asset price every 30s (Ctrl+C to stop)   |
+
+### Paper Trading & Triggers
+
+| Command                                              | Description                              |
+|------------------------------------------------------|------------------------------------------|
+| `alpha positions`                                    | View simulated portfolio & open positions |
+| `alpha trigger buy <id> <condition> <target> <amt> <market>`  | Set a BUY trigger                |
+| `alpha trigger sell <id> <condition> <target> <amt> <market>` | Set a SELL trigger               |
+| `alpha trigger list`                                 | List all your triggers                    |
+| `alpha trigger cancel <id>`                          | Cancel an active trigger                  |
+
+**Condition types:** `PRICE_ABOVE`, `PRICE_BELOW`, `SMART_MONEY_INFLOW`, `EXCHANGE_OUTFLOW`  
+**Market types:** `CRYPTO`, `SP500`, `NASDAQ`
+
+#### Example
+
+```bash
+# Buy 10 units of SOL when price drops below $140
+alpha trigger buy SOL PRICE_BELOW 140 10 CRYPTO
+
+# Sell 5 shares of AAPL when price goes above $200
+alpha trigger sell AAPL PRICE_ABOVE 200 5 SP500
+```
+
+---
+
+## Nansen API Integration
+
+The backend integrates with **10 Nansen API endpoints** for on-chain analytics:
+
+1. `GET /trending/tokens` — Hot contracts & trending tokens
+2. `GET /smart-money/token-flows` — Smart money inflows/outflows
+3. `GET /wallet/:address/balances` — Token balances for a wallet
+4. `GET /token/:id/exchange-flows` — Exchange flow data
+5. `GET /token/:id/holders` — Token holder distribution
+6. `GET /smart-money/holdings` — Cross-chain smart money holdings
+7. `GET /wallet/:address/profiler` — Wallet profiler
+8. `GET /nft/indexes` — NFT market indexes
+9. `GET /entities/:name/flows` — Entity-level token flow
+10. `GET /token/:id/macro-signals` — Token God Mode macro signals
+
+> **Note:** If `NANSEN_API_KEY` is not set in `.env`, the backend will return mock data so the CLI can be demonstrated without API access.
+
+---
+
+## Autonomous Trigger Engine
+
+The backend runs a **cron job every 60 seconds** that:
+
+1. Fetches all `ACTIVE` triggers from MongoDB
+2. For each trigger, fetches the live price/flow data from Nansen or Yahoo Finance
+3. Evaluates the trigger condition (`PRICE_ABOVE`, `PRICE_BELOW`, etc.)
+4. If the condition is met, executes a **simulated paper trade**:
+   - **BUY:** Deducts cost from `User.simulatedBalance`, creates/updates a `Position`
+   - **SELL:** Adds proceeds to `User.simulatedBalance`, reduces/removes a `Position`
+5. Marks the trigger as `EXECUTED`
+
+Each new user starts with a **$100,000 simulated paper-trading balance**.
+
+---
+
+## Tech Stack
+
+| Component     | Technology                                     |
+|---------------|------------------------------------------------|
+| CLI           | Node.js, Commander.js, Chalk, cli-table3       |
+| Backend       | Express 5, MongoDB/Mongoose, JWT               |
+| Auth UI       | Next.js 15, Solana wallet-adapter, Tailwind CSS |
+| Market Data   | Nansen API, Yahoo Finance (yahoo-finance2)     |
+| Auth          | Phantom Wallet (Ed25519 signature + tweetnacl) |
+| Scheduler     | node-cron                                      |
+
+---
+
+## License
+
+MIT

package/bin/alpha.js

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+const { Command } = require('commander');
+const chalk = require('chalk');
+const gradient = require('gradient-string');
+const Table = require('cli-table3');
+const { authenticateViaBrowser, getToken, clearToken } = require('../utils/auth');
+
+const program = new Command();
+const BACKEND_URL = process.env.ALPHA_BACKEND_URL || 'http://localhost:4000/api';
+
+program
+    .name('alpha')
+    .description('Alpha CLI – Autonomous Agent Onchain Toolkit (Powered by Nansen)')
+    .version('1.0.0');
+
+const checkAuth = () => {
+    const token = getToken();
+    if (!token) {
+        console.log(chalk.red('❌ Not authenticated. Please run `alpha login` first.'));
+        process.exit(1);
+    }
+    return token;
+};
+
+const authHeaders = (token) => ({ Authorization: `Bearer ${token}` });
+
+const buildMarketTable = (items, cType) => {
+    const table = new Table({
+        head: [
+            chalk.bold.white('Asset'),
+            chalk.bold.white('Price'),
+            chalk.bold.white('Trend / Conviction'),
+        ],
+        colWidths: [22, 16, 32],
+        style: { border: ['grey'] },
+    });
+
+    items.forEach((asset) => {
+        const name = asset.name || asset.symbol;
+        const score = asset.trendScore ?? 0;
+        let colorizer = chalk.blue;
+        if (score >= 90) colorizer = chalk.green;
+        else if (score < 50) colorizer = chalk.yellow;
+
+        table.push([
+            colorizer(name),
+            chalk.white(`$${asset.price ?? '—'}`),
+            colorizer(`Score: ${score}`),
+        ]);
+    });
+
+    console.log(gradient.atlas(`\n─── Trending ${cType} Assets ───────────────────`));
+    console.log(table.toString());
+};
+
+program
+    .command('status')
+    .description('Check authentication status and backend health')
+    .action(async () => {
+        const axios = require('axios');
+        const token = getToken();
+
+        console.log(gradient.pastel('\n  Alpha CLI – System Status\n'));
+
+        // Auth status
+        if (token) {
+            console.log(chalk.green('  ✅ Authenticated') + chalk.grey('  (JWT stored locally)'));
+        } else {
+            console.log(chalk.yellow('  ⚠️  Not authenticated') + chalk.grey('  — run `alpha login`'));
+        }
+
+        // Backend health
+        try {
+            const { data } = await axios.get(`http://localhost:4000/health`, { timeout: 3000 });
+            console.log(chalk.green('  ✅ Backend online') + chalk.grey(`  (${data.timestamp})`));
+        } catch {
+            console.log(chalk.red('  ❌ Backend offline') + chalk.grey('  — start it with `npm run dev` in /backend'));
+        }
+
+        console.log('');
+    });
+
+program
+    .command('login')
+    .description('Authenticate via Phantom Wallet through the browser')
+    .action(async () => {
+        try {
+            console.log(gradient.pastel.multiline('\nWelcome to Alpha CLI\nPreparing Web3 Authentication...\n'));
+            await authenticateViaBrowser();
+            console.log(chalk.green('\n✅ Successfully authenticated! Your session is stored securely.\n'));
+        } catch (err) {
+            console.error(chalk.red('\n❌ Authentication Failed:'), err.message);
+        }
+    });
+
+program
+    .command('logout')
+    .description('Clear the stored authentication session')
+    .action(() => {
+        clearToken();
+        console.log(chalk.yellow('\n👋 Logged out. Your JWT has been cleared.\n'));
+    });
+
+program
+    .command('market')
+    .description('Show trending assets powered by Nansen smart-money data')
+    .option('-c, --crypto', 'Trending crypto from Nansen (default)')
+    .option('-s, --sp500', 'Trending S&P 500 assets via Yahoo Finance')
+    .option('-n, --nsd', 'Trending NASDAQ assets via Yahoo Finance')
+    .action(async (options) => {
+        const token = checkAuth();
+        const axios = require('axios');
+
+        let url = `${BACKEND_URL}/market/crypto/trending`;
+        let cType = 'CRYPTO';
+
+        if (options.sp500) { url = `${BACKEND_URL}/market/tradfi/sp500`; cType = 'S&P 500'; }
+        else if (options.nsd) { url = `${BACKEND_URL}/market/tradfi/nsd`; cType = 'NASDAQ'; }
+
+        console.log(chalk.cyan(`\n🔍 Fetching ${cType} market data...`));
+
+        try {
+            const { data } = await axios.get(url, { headers: authHeaders(token) });
+            const items = data.data || data.assets || [];
+
+            if (!items.length) {
+                console.log(chalk.yellow('No data returned.'));
+                return;
+            }
+
+            buildMarketTable(items, cType);
+        } catch (err) {
+            console.error(chalk.red('Failed to fetch market data:'), err.response?.data?.error || err.message);
+        }
+    });
+
+program
+    .command('lookup <id>')
+    .description('Deep dive into an asset via Nansen or Yahoo Finance')
+    .action(async (id) => {
+        const token = checkAuth();
+        const axios = require('axios');
+
+        console.log(chalk.cyan(`\n🔍 Fetching deep insights for ${chalk.bold(id)}...`));
+
+        try {
+            const { data } = await axios.get(`${BACKEND_URL}/market/lookup/${id}`, { headers: authHeaders(token) });
+
+            if (data.type === 'tradfi') {
+                const q = data.data;
+                const table = new Table({ style: { border: ['grey'] } });
+                table.push(
+                    [chalk.grey('Symbol'), chalk.white(q.symbol)],
+                    [chalk.grey('Name'), chalk.white(q.longName || q.shortName || '—')],
+                    [chalk.grey('Price'), chalk.green(`$${q.regularMarketPrice}`)],
+                    [chalk.grey('Change %'), (q.regularMarketChangePercent >= 0 ? chalk.green : chalk.red)(`${q.regularMarketChangePercent?.toFixed(2)}%`)],
+                    [chalk.grey('52W High'), chalk.white(`$${q.fiftyTwoWeekHigh}`)],
+                    [chalk.grey('52W Low'), chalk.white(`$${q.fiftyTwoWeekLow}`)],
+                    [chalk.grey('Market Cap'), chalk.white(q.marketCap ? `$${(q.marketCap / 1e9).toFixed(2)}B` : '—')],
+                );
+                console.log(gradient.atlas(`\n─── TradFi Insight: ${id.toUpperCase()} ─────────────`));
+                console.log(table.toString());
+            } else {
+                console.log(gradient.atlas(`\n─── Nansen Crypto Insight: ${id.toUpperCase()} ──────`));
+                console.log(JSON.stringify(data.nansenInsights, null, 2));
+            }
+        } catch (err) {
+            console.error(chalk.red('Lookup failed:'), err.response?.data?.error || err.message);
+        }
+    });
+
+program
+    .command('positions')
+    .description('View your simulated portfolio and open positions')
+    .action(async () => {
+        const token = checkAuth();
+        const axios = require('axios');
+
+        try {
+            const { data } = await axios.get(`${BACKEND_URL}/triggers/portfolio`, { headers: authHeaders(token) });
+
+            console.log(gradient.pastel(`\n  💰 Simulated Balance: ${chalk.bold.green('$' + data.simulatedBalance?.toLocaleString())}\n`));
+
+            if (!data.positions?.length) {
+                console.log(chalk.grey('  No open positions. Use `alpha trigger buy` to start paper trading.\n'));
+                return;
+            }
+
+            const table = new Table({
+                head: [chalk.bold.white('Asset'), chalk.bold.white('Market'), chalk.bold.white('Amount'), chalk.bold.white('Avg Buy Price')],
+                colWidths: [18, 12, 14, 18],
+                style: { border: ['grey'] },
+            });
+
+            data.positions.forEach((pos) => {
+                table.push([
+                    chalk.cyan(pos.assetId),
+                    chalk.white(pos.market),
+                    chalk.white(pos.amount),
+                    chalk.green(`$${pos.averageBuyPrice}`),
+                ]);
+            });
+
+            console.log(chalk.bold('  📊 Open Positions:'));
+            console.log(table.toString());
+        } catch (err) {
+            console.error(chalk.red('Failed to fetch portfolio:'), err.response?.data?.error || err.message);
+        }
+    });
+
+program
+    .command('watch <asset>')
+    .description('Live-poll an asset every 30s (Ctrl+C to stop)')
+    .option('-i, --interval <seconds>', 'Polling interval in seconds', '30')
+    .action(async (asset, options) => {
+        const token = checkAuth();
+        const axios = require('axios');
+        const intervalMs = parseInt(options.interval, 10) * 1000;
+
+        console.log(gradient.atlas(`\n👁  Watching ${chalk.bold(asset)} every ${options.interval}s — Press Ctrl+C to stop\n`));
+
+        const fetch = async () => {
+            const ts = new Date().toLocaleTimeString();
+            try {
+                const { data } = await axios.get(`${BACKEND_URL}/market/lookup/${asset}`, { headers: authHeaders(token) });
+
+                if (data.type === 'tradfi') {
+                    const q = data.data;
+                    const change = q.regularMarketChangePercent?.toFixed(2);
+                    const arrow = change >= 0 ? '▲' : '▼';
+                    const colorizer = change >= 0 ? chalk.green : chalk.red;
+                    console.log(
+                        chalk.grey(`[${ts}]`) +
+                        chalk.white(` ${q.symbol}`) +
+                        `  $${q.regularMarketPrice}` +
+                        `  ` + colorizer(`${arrow} ${change}%`)
+                    );
+                } else {
+                    const flows = data.nansenInsights?.flows;
+                    console.log(chalk.grey(`[${ts}]`), chalk.white(asset.toUpperCase()), '—', chalk.cyan('Nansen data:'), JSON.stringify(flows ?? data.nansenInsights, null, 0));
+                }
+            } catch (err) {
+                console.log(chalk.grey(`[${ts}]`), chalk.red('Error:'), err.response?.data?.error || err.message);
+            }
+        };
+
+        await fetch(); // Immediate first tick
+        setInterval(fetch, intervalMs);
+    });
+
+const triggerCmd = program
+    .command('trigger')
+    .description('Manage autonomous smart-money paper-trading triggers');
+
+// trigger buy
+triggerCmd
+    .command('buy <id> <condition> <target> <amount> <market>')
+    .description('Set a BUY trigger. Example: alpha trigger buy SOL PRICE_BELOW 140 10 CRYPTO')
+    .action(async (id, condition, target, amount, market) => {
+        const token = checkAuth();
+        const axios = require('axios');
+        try {
+            const { data } = await axios.post(
+                `${BACKEND_URL}/triggers`,
+                { assetId: id, type: 'BUY', conditionType: condition, targetValue: Number(target), amount: Number(amount), market: market.toUpperCase() },
+                { headers: authHeaders(token) }
+            );
+            console.log(chalk.green(`\n✅ BUY trigger set! Agent will buy ${amount} ${id} when ${condition} reaches ${target}`));
+            console.log(chalk.grey(`   Trigger ID: ${data.trigger._id}\n`));
+        } catch (err) {
+            console.error(chalk.red('Failed to set trigger:'), err.response?.data?.error || err.message);
+        }
+    });
+
+// trigger sell
+triggerCmd
+    .command('sell <id> <condition> <target> <amount> <market>')
+    .description('Set a SELL trigger. Example: alpha trigger sell SOL PRICE_ABOVE 200 10 CRYPTO')
+    .action(async (id, condition, target, amount, market) => {
+        const token = checkAuth();
+        const axios = require('axios');
+        try {
+            const { data } = await axios.post(
+                `${BACKEND_URL}/triggers`,
+                { assetId: id, type: 'SELL', conditionType: condition, targetValue: Number(target), amount: Number(amount), market: market.toUpperCase() },
+                { headers: authHeaders(token) }
+            );
+            console.log(chalk.green(`\n✅ SELL trigger set! Agent will sell ${amount} ${id} when ${condition} reaches ${target}`));
+            console.log(chalk.grey(`   Trigger ID: ${data.trigger._id}\n`));
+        } catch (err) {
+            console.error(chalk.red('Failed to set trigger:'), err.response?.data?.error || err.message);
+        }
+    });
+
+// trigger list
+triggerCmd
+    .command('list')
+    .description('List all your active and past triggers')
+    .action(async () => {
+        const token = checkAuth();
+        const axios = require('axios');
+        try {
+            const { data } = await axios.get(`${BACKEND_URL}/triggers`, { headers: authHeaders(token) });
+
+            if (!data.triggers?.length) {
+                console.log(chalk.yellow('\n  No triggers found. Use `alpha trigger buy` or `alpha trigger sell` to create one.\n'));
+                return;
+            }
+
+            const table = new Table({
+                head: [
+                    chalk.bold.white('ID'),
+                    chalk.bold.white('Asset'),
+                    chalk.bold.white('Type'),
+                    chalk.bold.white('Condition'),
+                    chalk.bold.white('Target'),
+                    chalk.bold.white('Amount'),
+                    chalk.bold.white('Market'),
+                    chalk.bold.white('Status'),
+                ],
+                colWidths: [28, 12, 8, 22, 12, 10, 10, 12],
+                style: { border: ['grey'] },
+            });
+
+            data.triggers.forEach((t) => {
+                const statusColor =
+                    t.status === 'ACTIVE' ? chalk.green :
+                        t.status === 'EXECUTED' ? chalk.blue : chalk.red;
+
+                table.push([
+                    chalk.grey(t._id),
+                    chalk.cyan(t.assetId),
+                    t.type === 'BUY' ? chalk.green(t.type) : chalk.red(t.type),
+                    chalk.white(t.conditionType),
+                    chalk.white(t.targetValue),
+                    chalk.white(t.amount),
+                    chalk.white(t.market),
+                    statusColor(t.status),
+                ]);
+            });
+
+            console.log(gradient.atlas('\n─── Triggers ──────────────────────────────'));
+            console.log(table.toString());
+            console.log('');
+        } catch (err) {
+            console.error(chalk.red('Failed to fetch triggers:'), err.response?.data?.error || err.message);
+        }
+    });
+
+// trigger cancel
+triggerCmd
+    .command('cancel <id>')
+    .description('Cancel an active trigger by its ID')
+    .action(async (id) => {
+        const token = checkAuth();
+        const axios = require('axios');
+        try {
+            await axios.delete(`${BACKEND_URL}/triggers/${id}`, { headers: authHeaders(token) });
+            console.log(chalk.yellow(`\n⛔ Trigger ${chalk.bold(id)} has been cancelled.\n`));
+        } catch (err) {
+            console.error(chalk.red('Failed to cancel trigger:'), err.response?.data?.error || err.message);
+        }
+    });
+
+program.parse();

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "alpha-cli-toolkit",
+  "version": "1.0.0",
+  "description": "Autonomous Agent Toolkit for Crypto & TradFi market data powered by Nansen.",
+  "main": "index.js",
+  "scripts": {
+    "start": "node bin/alpha.js",
+    "dev": "node bin/alpha.js --help",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "bin": {
+    "alpha": "bin/alpha.js"
+  },
+  "files": [
+    "bin",
+    "utils",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "crypto",
+    "nansen",
+    "tradfi",
+    "autonomous-agent",
+    "cli-toolkit"
+  ],
+  "author": "Linkxee-Tech",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Linkxee-Tech/alpha-cli.git"
+  },
+  "type": "commonjs",
+  "dependencies": {
+    "axios": "^1.14.0",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1",
+    "gradient-string": "^2.0.2",
+    "inquirer": "^13.3.2",
+    "node-cron": "^4.2.1",
+    "open": "^11.0.0",
+    "ora": "^5.4.1"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.14"
+  }
+}

package/utils/auth.js

@@ -0,0 +1,108 @@
+const http = require('http');
+const url = require('url');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ─── Simple config store (replaces `conf` to avoid ESM issues) ───────────────
+const CONFIG_DIR = path.join(os.homedir(), '.alpha-cli');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+function readConfig() {
+    try {
+        if (!fs.existsSync(CONFIG_FILE)) return {};
+        return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+    } catch {
+        return {};
+    }
+}
+
+function writeConfig(data) {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
+}
+
+// ─── Token management ────────────────────────────────────────────────────────
+
+function getToken() {
+    return readConfig().jwt || null;
+}
+
+function clearToken() {
+    const config = readConfig();
+    delete config.jwt;
+    writeConfig(config);
+}
+
+function setToken(token) {
+    const config = readConfig();
+    config.jwt = token;
+    writeConfig(config);
+}
+
+// ─── Browser-based Phantom auth flow ─────────────────────────────────────────
+
+/**
+ * Spins up a local temporary server and opens the Next.js UI
+ * to capture the Phantom wallet authentication token.
+ */
+async function authenticateViaBrowser() {
+    return new Promise(async (resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            const parsedUrl = url.parse(req.url, true);
+
+            if (parsedUrl.pathname === '/') {
+                const token = parsedUrl.query.token;
+
+                if (token) {
+                    setToken(token);
+
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end(`
+                        <html><body style="background: #0a0a1a; color: #4ade80; font-family: system-ui, sans-serif; display: flex; align-items: center; justify-content: center; height: 100vh; margin: 0;">
+                            <div style="text-align: center;">
+                                <h1 style="font-size: 2rem; margin-bottom: 0.5rem;">✓ Authentication Complete</h1>
+                                <p style="color: #666;">You can close this tab and return to your terminal.</p>
+                            </div>
+                            <script>setTimeout(() => window.close(), 3000);</script>
+                        </body></html>
+                    `);
+
+                    server.close();
+                    resolve(token);
+                } else {
+                    res.writeHead(400, { 'Content-Type': 'text/html' });
+                    res.end('<h1>Failed to authenticate. No token returned.</h1>');
+                    server.close();
+                    reject(new Error('No token returned'));
+                }
+            }
+        });
+
+        server.listen(0, async () => {
+            const port = server.address().port;
+            const callbackUrl = `http://localhost:${port}`;
+            const loginUrl = `http://localhost:3000/?callback=${encodeURIComponent(callbackUrl)}`;
+
+            // Dynamic import for `open` (ESM-only since v9)
+            const open = (await import('open')).default;
+
+            console.log(`Opening browser to authenticate via Phantom Wallet...`);
+            await open(loginUrl);
+        });
+
+        // Timeout after 5 minutes
+        setTimeout(() => {
+            server.close();
+            reject(new Error('Authentication timed out after 5 minutes'));
+        }, 5 * 60 * 1000);
+    });
+}
+
+module.exports = {
+    authenticateViaBrowser,
+    getToken,
+    clearToken,
+};