Nija

Heartbeat Trading & Trust Layer Guide

Complete guide for deployment verification and transparent trade decision logging

Quick Start: Railway Deployment (10 minutes)

Step 1: Set Environment Variables in Railway

# REQUIRED: Kraken Platform Credentials
KRAKEN_PLATFORM_API_KEY=<your-64-char-api-key>
KRAKEN_PLATFORM_API_SECRET=<your-88-char-api-secret>

# REQUIRED: Trading Safety
LIVE_CAPITAL_VERIFIED=true

# REQUIRED: Heartbeat Verification (enable temporarily)
HEARTBEAT_TRADE=true
HEARTBEAT_TRADE_SIZE=5.50
HEARTBEAT_TRADE_INTERVAL=600

Step 2: Deploy & Monitor Logs

Watch for heartbeat execution (~10 minutes):

❤️  HEARTBEAT TRADE ENABLED: $5.50 every 600s
...
❤️  HEARTBEAT TRADE EXECUTION
   ✅ Heartbeat trade #1 EXECUTED

Step 3: Disable Heartbeat

Update Railway environment variable:

HEARTBEAT_TRADE=false

That’s it! Full details below.

Overview

This guide covers the new features added to NIJA for deployment verification and enhanced transparency:

  1. Heartbeat Trading - Verify exchange connectivity with tiny test trades
  2. Trade Veto Logging - Explicit logging of why trades were not executed
  3. User Status Banner - Real-time status display with account information

1. Heartbeat Trading

Purpose

Heartbeat trades are minimal-size test trades ($5.50) that verify:

Use Cases

Configuration

Add to .env or set as environment variables:

# Enable heartbeat trading
HEARTBEAT_TRADE=true

# Trade size in USD (default: $5.50 - minimum viable)
HEARTBEAT_TRADE_SIZE=5.50

# Interval between heartbeat trades in seconds (default: 600 = 10 minutes)
HEARTBEAT_TRADE_INTERVAL=600

How It Works

  1. Bot checks if heartbeat is enabled and interval has elapsed
  2. Selects a liquid market (prefers BTC-USD or ETH-USD)
  3. Executes a tiny market buy order ($5.50)
  4. Logs execution details and updates heartbeat counter
  5. Next heartbeat won’t execute until interval elapses

Verification Process

Step 1: Enable Heartbeat

# In Railway/Render environment variables:
HEARTBEAT_TRADE=true

Step 2: Deploy and Monitor Logs

❤️  HEARTBEAT TRADE ENABLED: $5.50 every 600s
...
❤️  HEARTBEAT TRADE EXECUTION
   Symbol: BTC-USD
   Size: $5.50
   Broker: KRAKEN
   Purpose: Verify connectivity & order execution
   ✅ Heartbeat trade #1 EXECUTED
   Order ID: ABC123
   Status: filled

Step 3: Verify Trade Executed Check exchange transaction history for the small order.

Step 4: Disable Heartbeat

# After confirming execution:
HEARTBEAT_TRADE=false

Important Notes

⚠️ Production Usage:

✅ Best Practice:

💡 Auto-Disable Recommendation: While the bot won’t auto-disable heartbeat, you should:

  1. Set a calendar reminder to disable after 30 minutes
  2. Or monitor logs and manually disable after seeing heartbeat execution
  3. Consider heartbeat as a temporary diagnostic tool, not a permanent feature

2. Trade Veto Logging

Purpose

Provides transparent logging of why the bot decided NOT to execute a trade. This builds trust and helps diagnose trading issues.

What Gets Logged

Every time a trade is vetoed (blocked), the bot logs:

Example Veto Logs

🚫 TRADE VETO: KRAKEN not connected
   Reason: Exchange API connection failed
   
🚫 TRADE VETO: KRAKEN in EXIT-ONLY mode
   Reason: No new positions allowed (exit only)
   
🚫 TRADE VETO: KRAKEN balance $8.50 < $10.00 minimum
   Reason: Insufficient balance for minimum trade size
   
🚫 TRADE VETO: KRAKEN balance fetch failed: timeout or error
   Reason: Could not verify account balance

Veto Session Tracking

The bot tracks vetoed trades per session:

📊 Vetoed Trades (Session): 12
📋 Last Veto Reason: KRAKEN balance $8.50 < $10.00 minimum

Benefits

  1. Transparency: Know exactly why bot isn’t trading
  2. Debugging: Quickly identify configuration issues
  3. Trust: Explicit reasons build confidence in bot behavior

3. User Status Banner

Purpose

Displays current account status at the start of each trading cycle, providing real-time visibility into:

Example Status Banner

======================================================================
📊 USER STATUS BANNER
======================================================================
   💰 KRAKEN Balance: $127.50
   📈 Active Positions: 3
   ✅ Trading Status: ACTIVE
   ❤️  Heartbeat: Last trade 245s ago (1 total)
======================================================================

When trades are vetoed:

======================================================================
📊 USER STATUS BANNER
======================================================================
   💰 KRAKEN Balance: $8.50
   📈 Active Positions: 0
   🚫 Trading Status: VETOED
   📋 Last Veto Reason: KRAKEN balance $8.50 < $10.00 minimum
   📊 Vetoed Trades (Session): 5
======================================================================

When It Displays

Railway Deployment

Step 1: Set Environment Variables

In Railway dashboard, add:

KRAKEN_PLATFORM_API_KEY=<your-api-key>
KRAKEN_PLATFORM_API_SECRET=<your-api-secret>
HEARTBEAT_TRADE=true
HEARTBEAT_TRADE_SIZE=5.50
HEARTBEAT_TRADE_INTERVAL=600
LIVE_CAPITAL_VERIFIED=true

Step 2: Deploy

Railway will automatically:

  1. Build from Dockerfile
  2. Run start.sh
  3. Connect to Kraken
  4. Display status banner
  5. Execute heartbeat trade (if enabled)

Step 3: Monitor Logs

Watch Railway logs for:

✅ KRAKEN (Platform) - PRIMARY BROKER:
   ✅ Configured (Key: 64 chars, Secret: 88 chars)

❤️  HEARTBEAT TRADE ENABLED: $5.50 every 600s

📊 USER STATUS BANNER
   💰 KRAKEN Balance: $150.00
   ✅ Trading Status: ACTIVE

Step 4: Verify and Disable Heartbeat

Once you see:

❤️  HEARTBEAT TRADE EXECUTION
   ✅ Heartbeat trade #1 EXECUTED

Update environment variable:

HEARTBEAT_TRADE=false

Railway will automatically redeploy with heartbeat disabled.

Troubleshooting

Heartbeat Not Executing

Symptoms: No heartbeat trade after 10 minutes

Checks:

  1. Verify HEARTBEAT_TRADE=true in environment
  2. Check account balance >= HEARTBEAT_TRADE_SIZE
  3. Verify broker is connected (check status banner)
  4. Look for veto logs explaining why trade was blocked

Continuous Vetos

Symptoms: Status shows “VETOED” every cycle

Common Causes:

  1. Insufficient Balance: Fund account above minimum ($10 for Kraken)
  2. API Credentials: Verify KRAKEN_PLATFORM_API_KEY and SECRET are set correctly
  3. EXIT-ONLY Mode: Check if broker is in exit-only mode (prevents new trades)
  4. Connection Issues: Verify network connectivity to exchange

Solution: Check veto reason in status banner, address the specific issue.

Status Banner Not Displaying

Symptoms: No status banner in logs

Checks:

  1. Verify bot is running (check Railway/Render logs)
  2. Look for error messages during startup
  3. Check that trading_strategy.py imported successfully

Security Notes

⚠️ API Key Security:

⚠️ Heartbeat Cost:

Summary

  1. Heartbeat Trading: Use for deployment verification, then disable
  2. Trade Veto Logging: Automatic - provides transparency on trading decisions
  3. Status Banner: Automatic - displays account status each cycle

These features enhance trust and transparency in NIJA’s autonomous trading operations.