Positions

A position represents an active token holding that is being monitored for price changes, stop loss, and DCA opportunities.

What is a Position?

When an agent executes a buy trade, a position is created. The position tracks:

• What you bought: Token address and symbol
• Purchase details: Price, amount, and total invested
• Current state: Value, P&L, stop loss level
• DCA history: Additional buys on dips

Position Properties

Position Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   OPENED    │────▶│  MONITORED  │────▶│   CLOSED    │
│             │     │             │     │             │
│ Buy trade   │     │ Price track │     │ Sell trade  │
│ executed    │     │ Stop loss   │     │ executed    │
│             │     │ DCA eval    │     │             │
└─────────────┘     └─────────────┘     └─────────────┘

Stage 1: Opened

A position is created when:

1. Signal passes agent eligibility checks
2. Position size is calculated
3. Buy trade executes successfully

Stage 2: Monitored

While open, the position is continuously:

1. Price tracked - Current price fetched from feeds
2. P&L calculated - Profit/loss computed
3. Stop loss evaluated - Checked for trigger
4. DCA evaluated - Checked for buy opportunity

Stage 3: Closed

A position closes when:

1. Stop loss triggers - Price below threshold
2. Manual close - User closes via dashboard/API
3. Stale trade - Auto-close after idle period (if configured)

Real-Time Monitoring

Positions are monitored with sub-second latency:

Price Updates

Price Feed (Pyth/DexScreener)
         │
         ▼
  ┌──────────────┐
  │ Price Update │
  │   Manager    │
  └──────┬───────┘
         │
         ▼
  ┌──────────────┐     ┌──────────────┐
  │ Stop Loss    │     │  WebSocket   │
  │  Evaluator   │     │  Broadcast   │
  └──────────────┘     └──────────────┘

Stop Loss Evaluation

Every price update triggers stop loss evaluation:

1. Calculate price change from peak
2. Determine current stop loss threshold
3. If price ≤ threshold → trigger sell
4. Update position state

WebSocket Updates

The dashboard receives real-time updates:

{
  "type": "position_update",
  "data": {
    "id": "position-123",
    "current": {
      "priceNative": 0.00000123,
      "priceUsd": 0.00025,
      "valueUsd": 125.50
    },
    "profitLoss": {
      "percent": 15.5,
      "usd": 16.82
    },
    "stopLoss": {
      "percentage": 85
    }
  }
}

Profit & Loss Calculation

Basic P&L

P&L % = ((Current Price - Purchase Price) / Purchase Price) × 100

With DCA

When DCA buys occur, the average purchase price is recalculated:

New Average Price = Total Invested SOL / Total Tokens Held

Example:

Position States

Healthy Position

• Price above purchase price
• Positive P&L
• Stop loss trailing upward

At-Risk Position

• Price below purchase price
• Negative P&L
• Stop loss may trigger soon

DCA Opportunity

• Price dropped to DCA level
• Additional buy may execute
• Average cost will decrease

Viewing Positions

Dashboard

The Positions tab shows:

API

# Get all positions for an agent
curl http://localhost:4000/api/v1/agent-positions/{agentId} \
  -H "Authorization: Bearer <token>"

Response:

[
  {
    "id": "position-123",
    "tokenSymbol": "BONK",
    "purchase": {
      "priceNative": 0.0000005,
      "amount": 1000000
    },
    "current": {
      "priceNative": 0.00000058,
      "valueUsd": 125.50
    },
    "profitLoss": {
      "percent": 16.0,
      "usd": 17.30
    },
    "stopLoss": {
      "percentage": 85,
      "peakPrice": 0.0000006
    }
  }
]

Closing Positions

Manual Close

Via dashboard:

1. Click on the position
2. Click Close Position
3. Select reason (Manual, Take Profit, Stop Loss)
4. Confirm

Via API:

curl -X POST http://localhost:4000/api/v1/agent-positions/{agentId}/{positionId}/close \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason": "manual"}'

Automatic Close

Positions close automatically when:

1. Stop loss triggers - Price drops below threshold
2. Stale trade - Position idle for configured duration with small P&L

Historical Swaps

When a position closes, it becomes a Historical Swap record:

Historical swaps are permanent records for performance tracking.

Best Practices

1. Monitor Active Positions

Check positions regularly, especially during volatile markets.

2. Understand Stop Loss Behavior

Know at what price your position will sell.

3. Consider DCA Carefully

DCA increases your exposure. Ensure you're comfortable with more capital at risk.

4. Review Historical Swaps

Learn from past trades to improve future performance.

5. Don't Over-Leverage

Limit the number of concurrent positions based on your total capital.