Budget API The Budget API tracks AI provider costs and enforces spending limits to prevent runaway expenses.
Get Budget Status curl -X GET "https://api.neuratrade.ai/api/v1/budget/status" \ -H "Authorization: Bearer YOUR_TOKEN"
{ "daily" : { "used" : "2.45" , "remaining" : "7.55" , "percent_used" : 24.5 }, "monthly" : { "used" : "38.20" , "remaining" : "161.80" , "percent_used" : 19.1 }, "limits" : { "daily" : "10.00" , "monthly" : "200.00" } }
Returns current AI usage and remaining budget for daily and monthly periods.
Response Fields Daily budget status Amount spent today in USD (2 decimal precision)
Remaining daily budget in USD
Percentage of daily budget consumed (0-100)
Monthly budget status (same structure as daily)
Configured budget limits Daily spending limit in USD
Monthly spending limit in USD
Check Budget Availability curl -X GET "https://api.neuratrade.ai/api/v1/budget/check" \ -H "Authorization: Bearer YOUR_TOKEN"
Verifies whether budget is available before making an AI call.
Response Fields true if budget is available, false if exceeded
Error Responses When budget is exceeded:
Daily Limit Exceeded (429) { "error" : "daily budget exceeded" , "limit" : "10.00" , "reset_at" : "2026-03-04T00:00:00Z" }
Monthly Limit Exceeded (429) { "error" : "monthly budget exceeded" , "limit" : "200.00" , "reset_at" : "2026-04-01T00:00:00Z" }
When budget limits are exceeded, all AI agent operations will be blocked until the next reset period. Quest execution continues but AI-powered reasoning is disabled.
Budget Configuration Budget limits are configured via environment variables:
# Daily AI spending limit (default: $10.00) AI_DAILY_BUDGET = "10.00" # Monthly AI spending limit (default: $200.00) AI_MONTHLY_BUDGET = "200.00"
Default Limits If not configured:
Daily: $10.00 USD
Monthly: $200.00 USD
These defaults are designed for moderate autonomous trading activity with LLM-powered decision making.
Budget Tracking Usage is tracked in the ai_usage_logs table:
Schema CREATE TABLE ai_usage_logs ( id TEXT PRIMARY KEY , user_id TEXT , chat_id TEXT , provider TEXT NOT NULL , model TEXT NOT NULL , input_tokens INTEGER NOT NULL , output_tokens INTEGER NOT NULL , total_tokens INTEGER NOT NULL , cost_usd REAL NOT NULL , request_type TEXT , created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );
Cost Calculation Costs are calculated using provider-specific token pricing:
Provider Input (per 1M tokens) Output (per 1M tokens) Zhipu GLM-4-Flash $0.10 $0.10 MiniMax abab6.5s $0.50 $0.50 Anthropic Claude 3.5 $3.00 $15.00 MLX Local $0.00 $0.00
Pricing is approximate and may vary. Check your provider’s official pricing for exact rates.
Budget Alerts Alerts are triggered at usage thresholds:
Daily Thresholds
50% - Warning notification75% - High usage alert90% - Critical alert100% - Budget exhausted, AI disabled
Monthly Thresholds
60% - Warning notification80% - High usage alert95% - Critical alert100% - Budget exhausted, AI disabled
Notifications are sent via:
Telegram messages (if configured)
Quest diagnostics (quest_runtime field)
System logs
Budget Enforcement When budget is exceeded:
AI Calls Blocked : All LLM provider requests return 429 errorsQuest Execution : Continues but falls back to non-AI logicNotifications : Admin receives budget exhaustion alertReset : Automatic at next period boundary (midnight UTC for daily, 1st of month for monthly)
Bypass (Emergency Only) To temporarily bypass budget limits:
# Disable budget enforcement (NOT RECOMMENDED) export NEURATRADE_BYPASS_BUDGET_LIMITS = true
Bypassing budget limits can lead to unexpected costs. Only use in controlled testing environments.
Fund Tracking The AI Fund Tracker monitors portfolio growth toward target values:
Fund Status { "current_value" : 125.50 , "start_value" : 100.00 , "target_value" : 1000.00 , "progress_percent" : 12.55 , "milestones_total" : 5 , "milestones_achieved" : 1 , "performance" : { "total_return" : 25.50 , "total_return_pct" : 25.5 , "daily_return" : 0.02 , "sharpe_ratio" : 1.8 , "max_drawdown" : 0.035 } }
Milestones AI-generated milestones mark progress:
{ "milestones" : [ { "id" : "ai_m1" , "target_value" : 250.00 , "target_percent" : 25 , "description" : "Quarter milestone - establish consistent trading" , "reasoning" : "First milestone focuses on stability and risk management" , "status" : "pending" , "created_at" : "2026-03-01T00:00:00Z" }, { "id" : "ai_m2" , "target_value" : 500.00 , "target_percent" : 50 , "description" : "Halfway point - optimize strategies" , "status" : "pending" } ] }
Milestone Alerts When a milestone is achieved:
{ "type" : "milestone_achieved" , "milestone_id" : "ai_m1" , "target_value" : 250.00 , "current_value" : 252.30 , "achieved_at" : "2026-03-15T14:23:10Z" }
Milestone generation uses AI reasoning to adapt targets based on performance velocity and market conditions.