Positions - Complete API Reference

Manage open positions with automated stop-loss, take-profit, and trailing stop orders.

---

Chat Commands

View Positions

/positions                          List all positions
/positions poly                     Polymarket positions only
/positions futures                  Futures positions only
/position <id>                      Position details

Stop-Loss

/sl <position-id> at 0.35           Set stop-loss price
/sl <position-id> -10%              Stop-loss 10% below entry
/sl poly "Trump" at 0.35            Set by market name

Take-Profit

/tp <position-id> at 0.65           Set take-profit price
/tp <position-id> +20%              Take-profit 20% above entry
/tp poly "Trump" at 0.65            Set by market name

Trailing Stop

/trailing <position-id> 5%          Trail 5% from high
/trailing <position-id> $0.05       Trail $0.05 from high

Partial Exits

/tp <position-id> at 0.55 size 50%  Take profit on half
/sl <position-id> at 0.40 size 25%  Stop-loss on quarter

---

TypeScript API Reference

Create Position Manager

import { createPositionManager } from 'clodds/positions';

const positions = createPositionManager({
  // Monitoring
  checkIntervalMs: 5000,

  // Execution
  orderType: 'market',  // 'market' | 'limit'
  limitBuffer: 0.01,    // Buffer for limit orders

  // Storage
  storage: 'sqlite',
  dbPath: './positions.db',
});

// Start monitoring
await positions.start();

List Positions

const all = await positions.list();

for (const pos of all) {
  console.log(`${pos.id}: ${pos.platform} ${pos.market}`);
  console.log(`  Side: ${pos.side}`);
  console.log(`  Size: ${pos.size}`);
  console.log(`  Entry: ${pos.entryPrice}`);
  console.log(`  Current: ${pos.currentPrice}`);
  console.log(`  P&L: ${pos.pnl} (${pos.pnlPercent}%)`);
  console.log(`  Stop-loss: ${pos.stopLoss || 'none'}`);
  console.log(`  Take-profit: ${pos.takeProfit || 'none'}`);
}

Set Stop-Loss

// Absolute price
await positions.setStopLoss({
  positionId: 'pos-123',
  price: 0.35,
});

// Percentage from entry
await positions.setStopLoss({
  positionId: 'pos-123',
  percentFromEntry: 10,  // 10% below entry
});

// Percentage from current
await positions.setStopLoss({
  positionId: 'pos-123',
  percentFromCurrent: 5,  // 5% below current
});

// Partial stop-loss
await positions.setStopLoss({
  positionId: 'pos-123',
  price: 0.35,
  sizePercent: 50,  // Exit 50% of position
});

Set Take-Profit

// Absolute price
await positions.setTakeProfit({
  positionId: 'pos-123',
  price: 0.65,
});

// Percentage from entry
await positions.setTakeProfit({
  positionId: 'pos-123',
  percentFromEntry: 20,  // 20% above entry
});

// Multiple take-profit levels
await positions.setTakeProfit({
  positionId: 'pos-123',
  levels: [
    { price: 0.55, sizePercent: 25 },  // 25% at 0.55
    { price: 0.60, sizePercent: 25 },  // 25% at 0.60
    { price: 0.70, sizePercent: 50 },  // 50% at 0.70
  ],
});

Set Trailing Stop

// Percentage trail
await positions.setTrailingStop({
  positionId: 'pos-123',
  trailPercent: 5,  // Trail 5% below high
});

// Absolute trail
await positions.setTrailingStop({
  positionId: 'pos-123',
  trailAmount: 0.05,  // Trail $0.05 below high
});

// Activate after target
await positions.setTrailingStop({
  positionId: 'pos-123',
  trailPercent: 5,
  activateAt: 0.55,  // Only start trailing after 0.55
});

Remove Stops

// Remove stop-loss
await positions.removeStopLoss('pos-123');

// Remove take-profit
await positions.removeTakeProfit('pos-123');

// Remove trailing stop
await positions.removeTrailingStop('pos-123');

// Remove all
await positions.removeAllStops('pos-123');

Event Handlers

// Stop-loss triggered
positions.on('stopLossTriggered', (position, result) => {
  console.log(`🛑 Stop-loss hit: ${position.market}`);
  console.log(`  Entry: ${position.entryPrice}`);
  console.log(`  Exit: ${result.exitPrice}`);
  console.log(`  P&L: ${result.pnl}`);
});

// Take-profit triggered
positions.on('takeProfitTriggered', (position, result) => {
  console.log(`✅ Take-profit hit: ${position.market}`);
  console.log(`  P&L: ${result.pnl}`);
});

// Trailing stop triggered
positions.on('trailingStopTriggered', (position, result) => {
  console.log(`📉 Trailing stop hit: ${position.market}`);
  console.log(`  High: ${position.highWaterMark}`);
  console.log(`  Exit: ${result.exitPrice}`);
});

// Price approaching stop
positions.on('approaching', (position, type, distance) => {
  console.log(`⚠️ ${position.market} ${distance}% from ${type}`);
});

Position Summary

const summary = await positions.getSummary();

console.log(`Total positions: ${summary.count}`);
console.log(`Total value: $${summary.totalValue}`);
console.log(`Unrealized P&L: $${summary.unrealizedPnl}`);
console.log(`With stop-loss: ${summary.withStopLoss}`);
console.log(`With take-profit: ${summary.withTakeProfit}`);

---

Stop Types

Type	Description
Stop-Loss	Exit when price drops to limit losses
Take-Profit	Exit when price rises to lock in gains
Trailing Stop	Dynamic stop that follows price up
Break-Even	Move stop to entry after profit target

---

Order Execution

Option	Description
market	Immediate execution at current price
limit	Execute at specified price or better
buffer	Add buffer to limit price for fills

---

Best Practices

1. Always set stops — Don't leave positions unprotected
2. Use trailing stops — Lock in gains as price moves
3. Partial exits — Scale out at multiple levels
4. Monitor approaching — Get alerts before triggers
5. Review filled stops — Check execution quality