Documentation: Warn users about rate limits when checking multiple positions

[joseph-eldo]

Documentation: Warn users about rate limits when checking multiple positions

Issue

When users have many token holdings (10+), checking wallet balance triggers multiple Jupiter API calls that can hit rate limits, causing slow responses or failures.

Background

Current behavior:

• slopesniper wallet fetches price data for each token held
• Jupiter's bundled API key has rate limits
• At ~15 positions, rate limiting starts occurring
• Code has exponential backoff to handle retries, but this slows things down significantly

What exists:

• ✅ Exponential backoff with configurable retry logic (in jupiter_ultra_client.py)
• ✅ Suggestion to use custom API key for "10x better performance"
• ❌ No explicit warning about rate limits with multiple positions

Proposed Solution

Add warnings to SKILL.md and CLI output when users have 10+ positions.

1. Update SKILL.md

Add a section about performance with multiple positions:

## Performance Tips

### Multiple Positions (10+ tokens)

If you hold 10 or more different tokens, wallet balance checks may be slow due to Jupiter API rate limits.

**Symptoms:**
- `slopesniper wallet` takes 30+ seconds
- Retry messages in logs
- API timeout errors

**Solutions:**

1. **Get your own Jupiter API key** (Recommended):
   ```bash
   slopesniper config --set-jupiter-key YOUR_KEY

Free keys at: https://station.jup.ag/docs/apis/ultra-api

• 10x higher rate limits
• Significantly faster for portfolios with many tokens

2. Use custom RPC endpoint:

   slopesniper config --set-rpc helius YOUR_KEY

   Reduces load on default public RPC

3. Limit scanning:

   • Avoid frequent wallet checks if not needed
   • Use position-specific commands when possible

### 2. Add Runtime Warning

When `slopesniper wallet` detects 10+ token types, show a one-time tip:

💡 TIP: You have 12 different tokens. For faster balance checks with large portfolios,
set your own Jupiter API key: slopesniper config --set-jupiter-key YOUR_KEY
Get a free key at: https://station.jup.ag/docs/apis/ultra-api

(Suppress this message: export SLOPESNIPER_HIDE_TIPS=1)

**Trigger threshold:** 10+ unique token holdings

### 3. Update `status` Command

Add a performance indicator to `slopesniper status`:

```json
{
  "config": {
    "jupiter_api_key": null,
    "performance_note": "Using bundled API key. For portfolios with 10+ tokens, custom key recommended."
  }
}

Or if custom key is set:

{
  "config": {
    "jupiter_api_key": "abc...xyz",
    "performance_note": "Using custom API key - optimized for large portfolios."
  }
}

Implementation Details

Where to check:

• JupiterUltraClient.get_holdings() - after fetching token list
• wallet command handler - before displaying results

Threshold logic:

TOKEN_COUNT_THRESHOLD = 10  # Trigger performance tips at 10+ tokens

if len(unique_token_mints) >= TOKEN_COUNT_THRESHOLD and not has_custom_api_key():
    show_performance_tip()

Environment variable to suppress:

export SLOPESNIPER_HIDE_TIPS=1

User Experience

Before (No Warning)

$ slopesniper wallet
# ... waits 45 seconds with retries ...
{
  "tokens": [ ... 15 tokens ... ]
}

User confused why it's so slow.

After (With Warning)

$ slopesniper wallet

💡 TIP: You have 15 different tokens. For faster balance checks,
   set your own Jupiter API key: slopesniper config --set-jupiter-key YOUR_KEY

# ... waits 45 seconds with retries ...
{
  "tokens": [ ... 15 tokens ... ]
}

User understands the issue and knows how to fix it.

After User Sets Custom Key

$ slopesniper wallet
# ... completes in 5 seconds ...
{
  "tokens": [ ... 15 tokens ... ]
}

Fast and smooth.

Why 10 Positions?

• Rate limiting becomes noticeable around 10-15 positions
• Conservative threshold ensures we warn before problems occur
• Exponential backoff handles it, but creates poor UX
• Better to be proactive than reactive

Related

• Exponential backoff already implemented in JupiterUltraClient._make_request()
• Custom API key support already exists in config
• This issue is about documentation and user awareness, not new functionality

Testing

1. Create wallet with 5 tokens → no warning
2. Create wallet with 10 tokens → warning appears
3. Set custom API key → warning doesn't appear
4. Set SLOPESNIPER_HIDE_TIPS=1 → warning suppressed

---

Priority: Medium (affects UX for active traders with diverse portfolios)

Effort: Low (mostly documentation + one-time tip display)