Display Custom Stats and GUI Notifications

Gunbot custom strategies offer powerful ways to visualize important information directly within the user interface. You can display custom metrics relevant to your strategy's performance or state in the chart sidebar, and also send real-time notifications to the GUI for immediate alerts.

Displaying Custom Stats in the Chart Sidebar

Custom strategies can display key metrics or status information directly next to a trading chart in the Gunbot GUI. This is useful for monitoring specific values your strategy calculates or tracks. These custom stats are defined by assigning an array of objects to gb.data.pairLedger.sidebarExtras.

Each object in the array represents one line item in the sidebar and can have the following properties:

• label (string, required): The descriptive label for your metric (e.g., "My Custom Value:").
• value (string, required): The actual value of the metric to display (e.g., "123.45", "Active", "N/A").
• tooltip (string, optional): Text that appears when the user hovers over this stat, providing additional context or explanation.
• valueColor (string, optional): A valid CSS color string (e.g., hex like #00FF00, rgb(0,255,0), or color names like green) to style the displayed value.

Here's an example snippet demonstrating how to set these custom stats:

// Example: Displaying two custom metrics in the sidebar
gb.data.pairLedger.sidebarExtras = [
    {
        label: `My Indicator Value:`, // Descriptive label for the first item
        value: `15.75`,              // The value to display
        tooltip: `This is the current calculated value of my special indicator.`, // Optional tooltip
        valueColor: '#3498db'        // Optional color for the value text (e.g., blue)
    },
    {
        label: `Strategy Status:`,     // Label for the second item
        value: `Monitoring`,         // Current status
        valueColor: 'orange'         // Optional color (e.g., orange)
    }
];

This will render two lines in the chart's sidebar, providing at-a-glance information from your strategy.

Info

The sidebarExtras array is overwritten with each strategy execution. Ensure your strategy sets these values every cycle if you want them to remain visible or update.

Sending GUI Notifications

Custom strategies in Gunbot can also send real-time notifications directly to the GUI. This feature is excellent for alerting you to significant events, errors, or confirmations from your strategy.

Notifications are created by assigning an array of notification objects to gb.data.pairLedger.notifications. Typically, you would add one notification object at a time, but the system supports an array if multiple notifications need to be sent simultaneously.

// Example: Sending different types of notifications
gb.data.pairLedger.notifications = [
    {
        text: 'Trade executed successfully!',
        variant: 'success', // Green notification
        persist: true     // Stays visible until dismissed by the user
    },
    {
        text: 'Error processing API response.',
        variant: 'error',   // Red notification
        persist: true
    },
    {
        text: 'Market condition met for potential entry.',
        variant: 'info',    // Blue notification
        persist: false    // Auto-dismisses after a short period
    },
    {
        text: `Multi-line notification example:
Line 2: More detailed information here.
Line 3: Check strategy logs.`,
        variant: 'warning', // Yellow notification
        persist: true,
    }
];

Notification Attributes

Each notification object can have the following attributes:

• text (string, required): The message content to be displayed.
• variant (string, optional): Defines the color and icon of the notification. Common values:
  • 'success' (green)
  • 'error' (red)
  • 'warning' (yellow)
  • 'info' (blue)
  • If omitted, a default style is used.
• persist (boolean, optional):
  • If true, the notification remains visible until manually dismissed by the user.
  • If false or omitted, the notification automatically disappears after a short period.

Usage and Display of Notifications

1. Add to Pair Ledger: In your strategy code, assign the array of notification objects to gb.data.pairLedger.notifications.
2. Automatic Display: The Gunbot GUI automatically picks up these notifications and displays them.
3. Lifecycle Management: The GUI manages the lifecycle of these notifications. There's no need for your strategy to manually clear or modify the notifications array after sending them; Gunbot handles their display and dismissal.

For more details, you can also refer to the dedicated page on Send Notifications to the Gunbot GUI.