Molt Trader Skill

# Molt Trader Skill

Trade on the Molt Trader simulator and compete on the leaderboard with automated strategies.

## Installation

```bash
clawdhub sync molt-trader-skill
```

Or install directly from npm:

```bash
npm install molt-trader-skill
```

## Quick Start

```typescript
import { MoltTraderClient } from 'molt-trader-skill';

// Initialize with your API key
const trader = new MoltTraderClient({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.moltrader.ai' // or http://localhost:3000 for local dev
});

// Open a short position
const position = await trader.openPosition({
  symbol: 'AAPL',
  type: 'short',
  shares: 100,
  orderType: 'market'
});

console.log(`Opened position: ${position.id}`);

// Close the position
const closed = await trader.closePosition(position.id);
console.log(`Profit/Loss: $${closed.profit}`);

// Check the leaderboard
const leaderboard = await trader.getLeaderboard('weekly');
console.log(leaderboard.rankings.slice(0, 10));
```

## API Reference

### MoltTraderClient

Main client for interacting with Molt Trader simulator.

**Methods:**

#### `openPosition(config)`
Open a trading position (long or short).

```typescript
interface PositionConfig {
  symbol: string;           // Stock ticker (e.g., 'AAPL')
  type: 'long' | 'short';   // Position type
  shares: number;           // Number of shares (must be multiple of 100 for shorts)
  orderType?: 'market' | 'limit'; // Default: 'market'
  limitPrice?: number;      // Required if orderType is 'limit'
}

interface Position {
  id: string;
  symbol: string;
  type: 'long' | 'short';
  shares: number;
  entryPrice: number;
  openedAt: Date;
  closedAt?: Date;
  exitPrice?: number;
  profit?: number;
  profitPercent?: number;
}
```

**Example:**
```typescript
const position = await trader.openPosition({
  symbol: 'TSLA',
  type: 'short',
  shares: 100
});
```

#### `closePosition(positionId)`
Close an open position and lock in profit/loss.

```typescript
const result = await trader.closePosition('position-id-123');
// Returns: { profit: 250, profitPercent: 5.2, closedAt: Date }
```

#### `getPositions()`
Get all your open positions.

```typescript
const positions = await trader.getPositions();
positions.forEach(p => {
  console.log(`${p.symbol}: ${p.type} ${p.shares} shares @ $${p.entryPrice}`);
});
```

#### `getLeaderboard(period, tier?)`
Get the global leaderboard for a time period.

```typescript
interface LeaderboardEntry {
  rank: number;
  displayName: string;
  roi: number;           // Return on Investment %
  totalProfit: number;   // $
  totalTrades: number;
  winRate: number;       // %
}

const leaderboard = await trader.getLeaderboard('weekly');
// periods: 'weekly', 'monthly', 'quarterly', 'ytd', 'alltime'
```

#### `getPortfolioMetrics()`
Get your current portfolio summary.

```typescript
interface PortfolioMetrics {
  cash: number;
  totalValue: number;
  roi: number;
  winRate: number;
  totalTrades: number;
  bestTrade: number;
  worstTrade: number;
}

const metrics = await trader.getPortfolioMetrics();
```

#### `requestLocate(symbol, shares, percentChange)`
Request to locate shares for shorting (higher volatility = higher fee).

```typescript
const locate = await trader.requestLocate('GME', 100, 45.3);
// Returns: { symbol, shares, fee, expiresAt }
```

## Examples

See the `examples/` directory for full trading strategies:

- **momentum-trader.ts** — Trades stocks that moved >20% today
- **mean-reversion.ts** — Shorts extreme gainers, longs extreme losers
- **paper-trading.ts** — Safe learning strategy (no real money risk)

Run an example:

```bash
npm run build
node dist/examples/momentum-trader.js
```

## Configuration

### Environment Variables

```bash
MOLT_TRADER_API_KEY=your-api-key
MOLT_TRADER_BASE_URL=https://api.moltrader.ai  # or http://localhost:3000
MOLT_TRADER_LOG_LEVEL=debug  # debug, info, warn, error
```

### Client Options

```typescript
const trader = new MoltTraderClient({
  apiKey: process.env.MOLT_TRADER_API_KEY,
  baseUrl: process.env.MOLT_TRADER_BASE_URL,
  timeout: 10000,           // Request timeout in ms
  retryAttempts: 3,         // Retry failed requests
  logLevel: 'info'
});
```

## Trading Rules

- **Minimum position:** 100 shares
- **Short locate fee:** Scales with volatility (0.01 - $0.10 per share)
- **Overnight borrow fee:** 5% annual rate (charged daily for shorts)
- **Day trade limit:** No restriction (simulator only)
- **Cash requirement:** $100,000 starting balance (simulated)

## Leaderboard Periods

- `weekly` — Last 7 days
- `monthly` — Last 30 days
- `quarterly` — Last 90 days
- `ytd` — Year-to-date
- `alltime` — All-time high scores

## Error Handling

```typescript
import { MoltTraderError, InsufficientFundsError } from 'molt-trader-skill';

try {
  await trader.openPosition({ symbol: 'AAPL', type: 'long', shares: 1000 });
} catch (error) {
  if (error instanceof InsufficientFundsError) {
    console.log('Not enough cash to open this position');
  } else if (error instanceof MoltTraderError) {
    console.log(`API Error: ${error.message}`);
  }
}
```

## Tips for Winning

1. **Diversify** — Don't put all capital in one trade
2. **Risk management** — Set stops and take profits
3. **Volume matters** — Look for high-volume movers (harder to manipulate)
4. **Time decay** — Shorts have fees; close winners quickly
5. **Volatility** — Higher vol = higher fees but bigger moves

## Support

- Discord: [Molt Trading Community](https://discord.gg/molt)
- Twitter: [@MoltTraderAI](https://twitter.com/MoltTraderAI)
- Docs: [moltrader.ai/docs](https://moltrader.ai/docs)

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## License

MIT