Skip to main content

​
Quests API

Quests are autonomous tasks that execute on schedules or triggers. Each quest represents a trading strategy, portfolio check, or market scan that runs without manual intervention.

​
Get Quest Progress

curl -X GET "https://api.neuratrade.ai/api/v1/telegram/internal/quests?chat_id=YOUR_CHAT_ID" \
  -H "X-Admin-API-Key: YOUR_ADMIN_KEY"

{
  "quests": [
    {
      "quest_id": "scalping_btc_usdt",
      "quest_name": "BTC/USDT Scalping",
      "current": 42,
      "target": 100,
      "percent": 42,
      "status": "active",
      "time_remaining": "2h 15m"
    }
  ],
  "updated_at": "2026-03-03T10:30:00Z"
}
Retrieves progress for all active quests associated with a chat/user.

​
Query Parameters

​
chat_id
string
required
Telegram chat ID to fetch quests for

​
Response Fields

​
quests
array
List of quest progress objects
​
updated_at
string
ISO 8601 timestamp of last update

​
Get Quest Diagnostics

curl -X GET "https://api.neuratrade.ai/api/v1/telegram/internal/quests/diagnostics?chat_id=YOUR_CHAT_ID" \
  -H "X-Admin-API-Key: YOUR_ADMIN_KEY"

{
  "chat_id": "123456789",
  "autonomous": true,
  "started_at": "2026-03-03T08:00:00Z",
  "active_quests": 3,
  "quest_progress": [
    {
      "quest_id": "scalping_btc_usdt",
      "current": 42,
      "target": 100,
      "status": "active"
    }
  ],
  "quest_runtime": {
    "risk_lock_active": false,
    "cadence_mode": "active",
    "last_tick_at": "2026-03-03T10:29:55Z"
  },
  "safety_status": {
    "is_safe": true,
    "trading_allowed": true,
    "max_position_size": "500.00",
    "current_drawdown": "2.50%",
    "position_throttle": "100%"
  },
  "timestamp": "2026-03-03T10:30:00Z"
}
Retrieves detailed diagnostics including quest state, risk status, and runtime metrics.

​
Query Parameters

​
chat_id
string
required
Telegram chat ID to fetch diagnostics for

​
Response Fields

​
chat_id
string
Chat identifier
​
autonomous
boolean
Whether autonomous mode is active
​
started_at
string
ISO 8601 timestamp when autonomous mode started
​
active_quests
integer
Count of currently running quests
​
quest_runtime
object
Quest engine runtime diagnostics
​
safety_status
object
Portfolio safety metrics (see Budget API for details)

​
Quest Schema

Quests are defined by the following structure stored in the quest engine:

​
Quest Object

​
id
string
Unique quest identifier (UUID)
​
name
string
Human-readable quest name
​
description
string
Detailed description of quest purpose
​
type
string
Quest type:
  • routine - Time-triggered recurring tasks
  • triggered - Event-driven execution
  • goal - Milestone-based quests
  • arbitrage - Arbitrage opportunity execution
​
cadence
string
For routine quests:
  • micro - Every 1-5 minutes
  • hourly - Once per hour
  • daily - Once per day
  • weekly - Once per week
  • onetime - Single execution
​
schedule
string
Cron expression for custom schedules (optional). Example: */5 * * * * for every 5 minutes.
​
priority
string
Execution priority: CRITICAL, HIGH, NORMAL, LOW
​
status
string
Current status: pending, active, completed, failed, paused
​
next_run
string
ISO 8601 timestamp of next scheduled execution
​
last_executed_at
string
ISO 8601 timestamp of last execution
​
checkpoint
object
Quest-specific progress data (varies by quest type)

​
Quest Scheduling

​
Cron Scheduling

Quests support cron expressions for flexible scheduling: 
{
  "cron_expr": "*/15 * * * *",
  "description": "Run every 15 minutes"
}
Common patterns:
  • */5 * * * * - Every 5 minutes
  • 0 * * * * - Every hour at :00
  • 0 0 * * * - Daily at midnight
  • 0 9,17 * * 1-5 - Weekdays at 9 AM and 5 PM

​
Event Triggers

Event-driven quests execute when specific conditions are met:
  • Price Movement: Trigger when price crosses threshold
  • Funding Rate: Execute when funding rate anomaly detected
  • Portfolio Health: Run when drawdown or exposure exceeds limit
  • Order Fill: Trigger follow-up actions after order execution
Quest execution is subject to risk locks. If risk_lock_active is true, new trading quests will be blocked until safety conditions are restored.

​
Quest Types

​
Scalping Quests

Execute scalping strategies on configured pairs: 
{
  "type": "routine",
  "cadence": "micro",
  "checkpoint": {
    "symbol": "BTC/USDT:USDT",
    "side": "buy",
    "entry_price": "65432.10",
    "current_positions": 2,
    "max_positions": 3
  }
}

​
Market Scanner

Scans markets for opportunities every 5 minutes: 
{
  "type": "routine",
  "cadence": "micro",
  "checkpoint": {
    "last_scan_time": "2026-03-03T10:25:00Z",
    "status": "scanning"
  }
}

​
Portfolio Health Check

Monitors portfolio metrics hourly: 
{
  "type": "routine",
  "cadence": "hourly",
  "checkpoint": {
    "last_health_check": "2026-03-03T10:00:00Z",
    "status": "healthy",
    "chat_id": "123456789"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us