diff --git a/docs/HELIUS_RATE_LIMITS.md b/docs/HELIUS_RATE_LIMITS.md new file mode 100644 index 0000000..e771150 --- /dev/null +++ b/docs/HELIUS_RATE_LIMITS.md @@ -0,0 +1,146 @@ +# Helius RPC Rate Limits + +## Overview +Our bot uses Helius RPC as the Solana endpoint. Understanding rate limits is critical for reliable operation. + +## Helius Rate Limit Tiers + +### Free Tier (Current) +- **Burst:** 100 requests/second +- **Sustained:** 10 requests/second +- **Monthly:** 100k requests +- **Best for:** Testing, small-scale trading + +### Paid Tiers +- **Developer ($49/month):** 50 RPS sustained, 1M requests/month +- **Professional ($199/month):** 100 RPS sustained, 10M requests/month +- **Business ($499/month):** 300 RPS sustained, 100M requests/month + +## Bot Configuration (Nov 14, 2025) + +### Retry Strategy +```typescript +// lib/drift/orders.ts +retryWithBackoff(operation, maxRetries=3, baseDelay=5000) +// Progression: 5s → 10s → 20s +``` + +**Why 5s base delay?** +- Free tier: 10 req/s = 1 request every 100ms maximum +- If rate limited, need >1s to clear backlog +- 5s gives ample time for Helius to recover +- Prevents cascade of failed retries + +### Operations that Hit RPC + +**High frequency (every price update):** +- `getPosition()` - Check current position size (for TP1/TP2 detection) + +**Medium frequency (on trade events):** +- `placeExitOrders()` - Place TP/SL orders (3-6 requests: cancel old + place new) +- `cancelAllOrders()` - Cancel orders (2-3 requests) + +**Low frequency (trade open/close):** +- `placePerpOrder()` + `confirmTransaction()` - Open position (2 requests) +- `closePosition()` + `confirmTransaction()` - Close position (2 requests) + +### Estimated Daily Usage + +**1 trade/hour scenario:** +- Open: 2 RPC calls +- Monitoring: ~1 call/10s = 360 calls/hour +- TP1 hit: 6 calls (cancel + place breakeven orders) +- Close: 2 calls +- **Per trade:** ~370 requests +- **Per day (24 trades):** ~8,880 requests + +**Free tier capacity:** 100,000/month = ~3,300/day +**Headroom:** 3,300 - 8,880 = **DEFICIT of -5,580/day** + +## Monitoring + +### Check current rate limit health: +```bash +curl http://localhost:3001/api/analytics/rate-limits | jq . +``` + +### SQL query for rate limit events: +```sql +SELECT + "eventType", + COUNT(*) as count, + MAX("createdAt") as last_occurrence +FROM "SystemEvent" +WHERE "eventType" IN ('rate_limit_hit', 'rate_limit_recovered', 'rate_limit_exhausted') + AND "createdAt" > NOW() - INTERVAL '24 hours' +GROUP BY "eventType"; +``` + +## Warning Signs + +### 🔴 Critical (Upgrade Required) +- `rate_limit_exhausted` events > 0/day +- `rate_limit_hit` events > 20/day +- Positions closed late due to rate limits +- Missing trades due to failed opens + +### ⚠️ Warning (Monitor Closely) +- `rate_limit_hit` events 10-20/day +- Recovery times > 10 seconds +- Frequent retries during high volatility + +### ✅ Healthy +- `rate_limit_hit` events < 5/day +- All recoveries within 2 retries +- No exhausted events + +## Optimization Strategies + +### Short-term (Current) +1. ✅ Increased retry delays (5s base) +2. ✅ Rate limit-aware error handling +3. ✅ Database logging for analytics + +### Medium-term (If limits become issue) +1. **Reduce monitoring frequency**: + - Current: Every Pyth price update (~1s) + - Alternative: Sample every 5s instead + +2. **Batch order operations**: + - Combine cancel + place into fewer RPC calls + - Use Drift SDK's batch order methods + +3. **Cache position data**: + - Only call `getPosition()` when price crosses key levels + - Trust Position Manager's tracked size between checks + +### Long-term (Growth) +1. **Upgrade to Developer tier ($49/month)**: + - 5x sustained capacity (50 RPS vs 10 RPS) + - 10x monthly quota (1M vs 100k) + - Cost: ~$2/day for reliable trading + +2. **Implement request queueing**: + - Rate limiter middleware + - Priority queue (closes > opens > monitoring) + - Automatic backoff when approaching limits + +## Cost-Benefit Analysis + +**Current situation:** +- Free tier: $0/month +- Risk: Missed trades, late closes, orphaned positions +- Manual intervention required + +**Developer tier ($49/month):** +- Eliminates rate limit issues +- Reliable trade execution +- Cost per trade: ~$0.10 (assuming 500 trades/month) +- ROI: One avoided $5 loss pays for 50 trades worth of RPC cost + +**Recommendation:** Upgrade to Developer tier once reaching 200+ trades/month or experiencing frequent rate limit events. + +## References +- [Helius Documentation](https://docs.helius.dev/) +- [Helius Pricing](https://www.helius.dev/pricing) +- [Solana RPC Methods](https://docs.solana.com/api/http)