Configuration

Environment variables, ticker formats, and npm scripts.

Environment Variables

Create a .env file in the project root with the following variables:

Variable	Required	Description	Example
TELEGRAM_BOT_TOKEN	Yes	Bot token from @BotFather	123456:ABCdefGHIjklMNOpqrsTUVwxyz
OPENCLAW_API_KEY	Yes	API key from OpenClaw console	oc-api-...

.env.example

# Telegram Bot Token from @BotFather
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

# OpenClaw API Key
OPENCLAW_API_KEY=your_openclaw_api_key_here

Never commit your .env file to version control. Add it to .gitignore.

Supported Ticker Formats

MarketClaw supports any symbol available on Yahoo Finance:

Type	Examples
US Stocks	AAPL, MSFT, GOOGL
Crypto	BTC-USD, ETH-USD
Forex	EURUSD=X, GBPUSD=X
Other	Any Yahoo Finance symbol

US Stocks

Standard ticker symbol

/analyze AAPL

Cryptocurrency

Symbol with -USD suffix

/analyze BTC-USD

Forex

Pair with =X suffix

/analyze EURUSD=X

npm Scripts

Script	Description
npm run build	Compiles TypeScript to dist/
npm start	Runs the compiled bot (production)
npm run dev	Runs directly via ts-node (development)

Production

npm run build && npm start

Development

npm run dev

Uses ts-node for direct TypeScript execution. Changes require restart.

Data Storage

Watchlists and alerts are stored as plain JSON files in the data/ folder. These files are created automatically when you first use the relevant commands.

Watchlists Schema

data/watchlists.json

{
  "123456789": ["AAPL", "MSFT", "NVDA"],
  "987654321": ["BTC-USD", "ETH-USD"]
}
// Key: Telegram user ID
// Value: Array of ticker symbols

Alerts Schema

data/alerts.json

{
  "123456789": [
    {
      "id": "1738412345678",
      "ticker": "AAPL",
      "condition": "below",
      "targetPrice": 220,
      "createdAt": "2025-02-01T12:00:00.000Z"
    }
  ]
}
// Key: Telegram user ID
// Value: Array of PriceAlert objects

Backup Tip

The data/ folder is excluded from git by default. To preserve user data across deployments, back up this folder or configure persistent storage.