Time Status API

Get status information for addresses in Host Mode - either all addresses or a specific address.

Overview

The Time Status API provides two endpoints:

1. POST /apiv2/time/status - Get status for all addresses with optional pagination
2. GET /apiv2/time/status/{address} - Get status for a specific address

These endpoints return detailed information about energy delegations, cycle counts, current modes, and usage statistics. Essential for monitoring your energy allocation and managing multiple addresses efficiently.

---

POST /apiv2/time/status

Get comprehensive status of all TRON addresses in Host Mode under your account with optional pagination.

Endpoint URL

POST https://netts.io/apiv2/time/status

Authentication

This endpoint uses JSON body authentication (not headers). Only your API key is required in the request body to retrieve status for all associated addresses.

Authentication Flow

1. API Key Validation: System verifies the API key exists and is active
2. IP Whitelist Check: Request IP must match configured whitelist
3. Account Status Check: Verifies account is active and in good standing
4. Data Aggregation: Collects status for all addresses under the API key

Request Headers

Header	Required	Description
Content-Type	Yes	application/json

Request Body

{
    "api_key": "your_api_key",
    "page": 1,
    "page_size": 50
}

Parameters

Parameter	Type	Required	Validation	Description
api_key	string	Yes	Must exist in system	Your API key for authentication
page	integer	No	>= 1	Page number for pagination (default: returns all, max 1000)
page_size	integer	No	1-100	Number of addresses per page (requires page parameter)

Parameter Validation

• api_key:

  • Must be a valid 32-character hexadecimal string
  • Must be associated with an active account
  • Account must not be suspended or restricted
  • Must have at least read permissions

• page (optional):

  • Must be an integer >= 1
  • When omitted: Returns all addresses (up to 1000, sorted by created_at DESC)
  • When provided with page_size: Returns paginated results

• page_size (optional):

  • Must be an integer between 1 and 100
  • Requires page parameter to be set
  • Recommended: 50 addresses per page for optimal performance

• IP Address:

  • Your request IP must be in the whitelist associated with your API key
  • Maximum 5 IP addresses per API key
  • IPv4 and IPv6 supported

Pagination Behavior

Without pagination parameters:

{
    "api_key": "your_api_key"
}

• Returns all addresses (up to 1000)
• Sorted by created_at DESC (newest first)
• For backward compatibility with existing integrations

With pagination parameters:

{
    "api_key": "your_api_key",
    "page": 1,
    "page_size": 50
}

• Returns paginated results (50 addresses)
• Includes pagination metadata in response
• Sorted by created_at DESC

Example Requests

cURL

Without pagination (returns all addresses):

curl -X POST https://netts.io/apiv2/time/status \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY_HERE"
  }'

With pagination (50 addresses per page):

curl -X POST https://netts.io/apiv2/time/status \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "page": 1,
    "page_size": 50
  }'

Python

import requests
import json
from typing import Dict, List, Optional
from datetime import datetime

def get_host_mode_status(api_key: str, page: Optional[int] = None,
                         page_size: Optional[int] = None) -> Dict:
    """
    Get comprehensive status of all addresses in Host Mode.

    Args:
        api_key: Your API authentication key
        page: Optional page number for pagination (default: None, returns all)
        page_size: Optional number of addresses per page (default: None)

    Returns:
        API response dictionary with status for all addresses
    """
    url = "https://netts.io/apiv2/time/status"

    data = {
        "api_key": api_key
    }

    # Add pagination parameters if provided
    if page is not None:
        data["page"] = page
    if page_size is not None:
        data["page_size"] = page_size

    try:
        response = requests.post(url, json=data, verify=True, timeout=30)
        response.raise_for_status()

        result = response.json()

        if result['code'] == 0:
            # Show pagination info if available
            if 'pagination' in result['data']:
                pagination = result['data']['pagination']
                print(f"✅ Page {pagination['page']} of {pagination['total_pages']}")
                print(f"   Showing {len(result['data']['addresses'])} of {pagination['total_items']} addresses")
            else:
                print(f"✅ Status retrieved for {len(result['data']['addresses'])} addresses")

            # Display each address status
            for addr in result['data']['addresses']:
                print(f"\n📍 Address: {addr['address']}")
                print(f"   Mode: {addr['mode']}")
                print(f"   Status: {addr['status']}")
                print(f"   Cycles completed: {addr['cycles_completed']}")
                print(f"   Cycles remaining: {addr['cycles_remaining']}")

        else:
            print(f"❌ Error: {result['msg']}")

        return result

    except requests.exceptions.RequestException as e:
        print(f"❌ Request failed: {str(e)}")
        raise
    except json.JSONDecodeError as e:
        print(f"❌ Invalid JSON response: {str(e)}")
        raise

# Example usage - get all addresses (no pagination)
def example_get_all_addresses(api_key: str):
    """Get all addresses without pagination."""
    result = get_host_mode_status(api_key)
    print(f"Retrieved {len(result['data']['addresses'])} addresses")

# Example usage - paginated requests
def example_get_paginated_addresses(api_key: str):
    """Get addresses with pagination."""
    page = 1
    page_size = 50

    while True:
        result = get_host_mode_status(api_key, page=page, page_size=page_size)

        if result['code'] == 0:
            pagination = result['data'].get('pagination', {})

            print(f"\n📄 Page {page}:")
            for addr in result['data']['addresses']:
                print(f"  - {addr['address']}: {addr['cycles_remaining']} cycles")

            # Check if there are more pages
            if not pagination.get('has_next', False):
                print(f"\n✅ Retrieved all {pagination.get('total_items', 0)} addresses")
                break

            page += 1
        else:
            print(f"❌ Error on page {page}: {result['msg']}")
            break

if __name__ == "__main__":
    API_KEY = "YOUR_API_KEY_HERE"

    # Get all addresses at once
    example_get_all_addresses(API_KEY)

    # Or get addresses with pagination
    example_get_paginated_addresses(API_KEY)

Node.js

const axios = require('axios');

/**
 * Get comprehensive status of all addresses in Host Mode
 * @param {string} apiKey - Your API authentication key
 * @param {number|null} page - Optional page number for pagination
 * @param {number|null} pageSize - Optional number of addresses per page
 * @returns {Promise<Object>} API response with status data
 */
async function getHostModeStatus(apiKey, page = null, pageSize = null) {
    const url = 'https://netts.io/apiv2/time/status';

    const data = {
        api_key: apiKey
    };

    // Add pagination parameters if provided
    if (page !== null) {
        data.page = page;
    }
    if (pageSize !== null) {
        data.page_size = pageSize;
    }

    try {
        const response = await axios.post(url, data, {
            headers: {
                'Content-Type': 'application/json'
            },
            timeout: 30000
        });

        const result = response.data;

        if (result.code === 0) {
            // Show pagination info if available
            if (result.data.pagination) {
                const p = result.data.pagination;
                console.log(`✅ Page ${p.page} of ${p.total_pages}`);
                console.log(`   Showing ${result.data.addresses.length} of ${p.total_items} addresses`);
            } else {
                console.log(`✅ Status retrieved for ${result.data.addresses.length} addresses`);
            }

            // Display each address status
            result.data.addresses.forEach(addr => {
                console.log(`\n📍 Address: ${addr.address}`);
                console.log(`   Mode: ${addr.mode}`);
                console.log(`   Status: ${addr.status}`);
                console.log(`   Cycles completed: ${addr.cycles_completed}`);
                console.log(`   Cycles remaining: ${addr.cycles_remaining}`);
            });
        } else {
            console.error(`❌ Error: ${result.msg}`);
        }

        return result;

    } catch (error) {
        if (error.response) {
            console.error(`❌ API Error: ${error.response.status} - ${error.response.data?.msg || error.message}`);
        } else if (error.request) {
            console.error('❌ No response from server');
        } else {
            console.error(`❌ Request failed: ${error.message}`);
        }
        throw error;
    }
}

/**
 * Get all addresses with pagination
 * @param {string} apiKey - Your API authentication key
 * @param {number} pageSize - Number of addresses per page
 * @returns {Promise<Array>} All addresses
 */
async function getAllAddressesPaginated(apiKey, pageSize = 50) {
    const allAddresses = [];
    let page = 1;
    let hasMore = true;

    while (hasMore) {
        const result = await getHostModeStatus(apiKey, page, pageSize);

        if (result.code === 0) {
            allAddresses.push(...result.data.addresses);

            if (result.data.pagination) {
                hasMore = result.data.pagination.has_next;
                console.log(`📄 Retrieved page ${page}/${result.data.pagination.total_pages}`);
                page++;
            } else {
                hasMore = false;
            }
        } else {
            throw new Error(`Failed on page ${page}: ${result.msg}`);
        }
    }

    return allAddresses;
}

// Example usage - get all addresses without pagination
async function exampleGetAll() {
    const API_KEY = 'YOUR_API_KEY_HERE';
    const result = await getHostModeStatus(API_KEY);
    console.log(`Retrieved ${result.data.addresses.length} addresses`);
}

// Example usage - get addresses with pagination
async function exampleGetPaginated() {
    const API_KEY = 'YOUR_API_KEY_HERE';
    const allAddresses = await getAllAddressesPaginated(API_KEY, 50);
    console.log(`\n✅ Total addresses retrieved: ${allAddresses.length}`);
}

// Run examples
(async () => {
    try {
        await exampleGetAll();
        // Or use pagination
        await exampleGetPaginated();
    } catch (error) {
        console.error('Failed:', error.message);
    }
})();

PHP

<?php

/**
 * Get comprehensive status of all addresses in Host Mode
 *
 * @param string $apiKey Your API authentication key
 * @param int|null $page Optional page number for pagination
 * @param int|null $pageSize Optional number of addresses per page
 * @return array API response with status data
 */
function getHostModeStatus($apiKey, $page = null, $pageSize = null) {
    $url = 'https://netts.io/apiv2/time/status';

    $data = [
        'api_key' => $apiKey
    ];

    // Add pagination parameters if provided
    if ($page !== null) {
        $data['page'] = $page;
    }
    if ($pageSize !== null) {
        $data['page_size'] = $pageSize;
    }

    $options = [
        'http' => [
            'header' => "Content-Type: application/json\r\n",
            'method' => 'POST',
            'content' => json_encode($data),
            'timeout' => 30
        ]
    ];

    $context = stream_context_create($options);
    $response = @file_get_contents($url, false, $context);

    if ($response === false) {
        $error = error_get_last();
        throw new RuntimeException('Request failed: ' . $error['message']);
    }

    $result = json_decode($response, true);

    if ($result['code'] == 0) {
        // Show pagination info if available
        if (isset($result['data']['pagination'])) {
            $p = $result['data']['pagination'];
            echo "✅ Page {$p['page']} of {$p['total_pages']}\n";
            echo "   Showing " . count($result['data']['addresses']) . " of {$p['total_items']} addresses\n\n";
        } else {
            echo "✅ Status retrieved for " . count($result['data']['addresses']) . " addresses\n\n";
        }

        // Display each address status
        foreach ($result['data']['addresses'] as $addr) {
            echo "📍 Address: {$addr['address']}\n";
            echo "   Mode: {$addr['mode']}\n";
            echo "   Status: {$addr['status']}\n";
            echo "   Cycles completed: {$addr['cycles_completed']}\n";
            echo "   Cycles remaining: {$addr['cycles_remaining']}\n\n";
        }
    } else {
        echo "❌ Error: {$result['msg']}\n";
    }

    return $result;
}

/**
 * Get all addresses with pagination
 *
 * @param string $apiKey Your API authentication key
 * @param int $pageSize Number of addresses per page
 * @return array All addresses
 */
function getAllAddressesPaginated($apiKey, $pageSize = 50) {
    $allAddresses = [];
    $page = 1;
    $hasMore = true;

    while ($hasMore) {
        $result = getHostModeStatus($apiKey, $page, $pageSize);

        if ($result['code'] == 0) {
            $allAddresses = array_merge($allAddresses, $result['data']['addresses']);

            if (isset($result['data']['pagination'])) {
                $hasMore = $result['data']['pagination']['has_next'];
                echo "📄 Retrieved page {$page}/{$result['data']['pagination']['total_pages']}\n";
                $page++;
            } else {
                $hasMore = false;
            }
        } else {
            throw new RuntimeException("Failed on page $page: {$result['msg']}");
        }
    }

    return $allAddresses;
}

// Example usage - get all addresses without pagination
$API_KEY = 'YOUR_API_KEY_HERE';

try {
    // Get all addresses at once
    $result = getHostModeStatus($API_KEY);
    echo "Retrieved " . count($result['data']['addresses']) . " addresses\n";

    // Or get addresses with pagination
    $allAddresses = getAllAddressesPaginated($API_KEY, 50);
    echo "\n✅ Total addresses retrieved: " . count($allAddresses) . "\n";

} catch (Exception $e) {
    echo "Failed: " . $e->getMessage() . "\n";
}
?>

Ruby

require 'net/http'
require 'json'
require 'uri'

class HostModeStatus
  API_URL = 'https://netts.io/apiv2/time/status'

  def initialize(api_key)
    @api_key = api_key
  end

  # Get comprehensive status of all addresses in Host Mode
  # @param page [Integer, nil] Optional page number for pagination
  # @param page_size [Integer, nil] Optional number of addresses per page
  # @return [Hash] API response
  def get_status(page: nil, page_size: nil)
    uri = URI.parse(API_URL)
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.read_timeout = 30

    request = Net::HTTP::Post.new(uri.path)
    request['Content-Type'] = 'application/json'

    data = { api_key: @api_key }
    data[:page] = page if page
    data[:page_size] = page_size if page_size

    request.body = data.to_json

    begin
      response = http.request(request)
      result = JSON.parse(response.body)

      if result['code'] == 0
        # Show pagination info if available
        if result['data']['pagination']
          p = result['data']['pagination']
          puts "✅ Page #{p['page']} of #{p['total_pages']}"
          puts "   Showing #{result['data']['addresses'].length} of #{p['total_items']} addresses"
        else
          puts "✅ Status retrieved for #{result['data']['addresses'].length} addresses"
        end

        display_addresses(result['data']['addresses'])
      else
        puts "❌ Error: #{result['msg']}"
      end

      result
    rescue => e
      puts "❌ Request failed: #{e.message}"
      raise
    end
  end
  
  # Get all addresses with pagination
  # @param page_size [Integer] Number of addresses per page
  # @return [Array] All addresses
  def get_all_addresses_paginated(page_size = 50)
    all_addresses = []
    page = 1
    has_more = true

    while has_more
      result = get_status(page: page, page_size: page_size)

      if result['code'] == 0
        all_addresses.concat(result['data']['addresses'])

        if result['data']['pagination']
          has_more = result['data']['pagination']['has_next']
          puts "📄 Retrieved page #{page}/#{result['data']['pagination']['total_pages']}"
          page += 1
        else
          has_more = false
        end
      else
        raise "Failed on page #{page}: #{result['msg']}"
      end
    end

    all_addresses
  end

  private

  # Display address details
  def display_addresses(addresses)
    addresses.each do |addr|
      puts "\n📍 Address: #{addr['address']}"
      puts "   Mode: #{addr['mode']}"
      puts "   Status: #{addr['status']}"
      puts "   Cycles completed: #{addr['cycles_completed']}"
      puts "   Cycles remaining: #{addr['cycles_remaining']}"
    end
  end
end

# Example usage - get all addresses without pagination
api_key = 'YOUR_API_KEY_HERE'
status_checker = HostModeStatus.new(api_key)

begin
  # Get all addresses at once
  result = status_checker.get_status
  puts "Retrieved #{result['data']['addresses'].length} addresses"

  # Or get addresses with pagination
  all_addresses = status_checker.get_all_addresses_paginated(50)
  puts "\n✅ Total addresses retrieved: #{all_addresses.length}"

rescue => e
  puts "Failed: #{e.message}"
end

Response

Success Response (200 OK)

Without pagination (all addresses):

{
    "code": 0,
    "msg": "Status retrieved successfully",
    "data": {
        "addresses": [
            {
                "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                "mode": "normal",
                "status": "active",
                "cycles_ordered": 25,
                "cycle_set": 25,
                "cycles_completed": 10,
                "cycles_remaining": 15,
                "open_orders": 2,
                "created_at": "2023-11-08T12:00:00.000000",
                "updated_at": "2023-11-09T10:00:00.000000"
            },
            {
                "address": "TYn8Y3khEsLJW2ChVWFMSMeRDow6KcbMTF",
                "mode": "infinity",
                "status": "active",
                "cycles_ordered": -1,
                "cycle_set": -1,
                "cycles_completed": 0,
                "cycles_remaining": -1,
                "open_orders": 1,
                "created_at": "2023-11-08T08:00:00.000000",
                "updated_at": "2023-11-09T09:30:00.000000"
            },
            {
                "address": "TZn9Y4khEsLJW3ChVWFMSMeRDow7KcbNUG",
                "mode": "normal",
                "status": "inactive",
                "cycles_ordered": 35,
                "cycle_set": 35,
                "cycles_completed": 5,
                "cycles_remaining": 30,
                "open_orders": 2,
                "created_at": "2023-11-05T10:00:00.000000",
                "updated_at": "2023-11-08T15:30:00.000000"
            }
        ],
        "timestamp": "2023-11-09T12:34:50.123456"
    }
}

With pagination:

{
    "code": 0,
    "msg": "Status retrieved successfully",
    "data": {
        "addresses": [
            {
                "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                "mode": "normal",
                "status": "active",
                "cycles_ordered": 25,
                "cycle_set": 25,
                "cycles_completed": 10,
                "cycles_remaining": 15,
                "open_orders": 2,
                "created_at": "2023-11-08T12:00:00.000000",
                "updated_at": "2023-11-09T10:00:00.000000"
            }
        ],
        "pagination": {
            "page": 1,
            "page_size": 50,
            "total_items": 150,
            "total_pages": 3,
            "has_next": true,
            "has_prev": false
        },
        "timestamp": "2023-11-09T12:34:50.123456"
    }
}

Response Fields

Field	Type	Description
code	integer	Status code (0 for success, -1 for error)
msg	string	Human-readable status message
data	object	Response data object
data.addresses	array	Array of address objects with detailed status
data.pagination	object	Pagination metadata (only when using pagination parameters)
data.pagination.page	integer	Current page number
data.pagination.page_size	integer	Number of addresses per page
data.pagination.total_items	integer	Total number of addresses across all pages
data.pagination.total_pages	integer	Total number of pages
data.pagination.has_next	boolean	Whether there is a next page
data.pagination.has_prev	boolean	Whether there is a previous page
data.timestamp	string	ISO timestamp of the response

Address Object Fields

Field	Type	Description
address	string	TRON address
mode	string	Current mode ("normal", "infinity", "off")
status	string	Current status ("active", "inactive")
cycles_ordered	integer	Total number of cycles purchased/ordered (-1 for infinity mode)
cycle_set	integer	Number of cycles set in hosting mode
cycles_completed	integer	Number of cycles already executed/completed
cycles_remaining	integer	Number of cycles remaining (cycles_ordered - cycles_completed, -1 for infinity)
open_orders	integer	Number of currently open orders for this address
created_at	string	ISO timestamp when address was added to Host Mode
updated_at	string	ISO timestamp when address was last updated

Error Responses

Authentication Error (401)

{
    "code": -1,
    "msg": "Invalid API key",
    "data": null
}

Causes:

• Invalid or expired API key
• API key not found in system
• Account suspended or terminated

Resolution:

• Verify API key is correct
• Check account status in dashboard
• Contact support if key should be valid

No Addresses Found (404)

{
    "code": -1,
    "msg": "No addresses found in Host Mode",
    "data": {
        "suggestion": "Use /time/add to add addresses to Host Mode",
        "api_key": "248f***4a"
    }
}

Causes:

• No addresses added to Host Mode yet
• All addresses have been deleted
• Wrong API key being used

Resolution:

• Add addresses using /time/add endpoint
• Verify using correct API key
• Check if addresses were deleted

IP Not Whitelisted (403)

{
    "code": -1,
    "msg": "IP address not whitelisted",
    "data": {
        "ip": "192.168.1.100",
        "suggestion": "Add this IP to whitelist in dashboard"
    }
}

Causes:

• Request IP not in API key whitelist
• IP address changed since configuration
• Using proxy or VPN

Resolution:

• Add IP to whitelist in dashboard
• Verify not using proxy/VPN
• Contact support to update whitelist

Account Suspended (403)

{
    "code": -1,
    "msg": "Account suspended",
    "data": {
        "reason": "payment_failure",
        "suspended_at": 1699442400,
        "contact": "[email protected]"
    }
}

Causes:

• Failed payments
• Terms of service violation
• Suspicious activity detected

Resolution:

• Resolve payment issues
• Contact support for reinstatement
• Review account activity

Invalid Pagination Parameters (400)

{
    "code": -1,
    "msg": "Invalid pagination parameters",
    "data": {
        "errors": [
            "page must be >= 1",
            "page_size must be between 1 and 100"
        ]
    }
}

Causes:

• Invalid page number (< 1)
• Invalid page_size (< 1 or > 100)
• page_size provided without page parameter

Resolution:

• Use page >= 1
• Use page_size between 1 and 100
• Provide both page and page_size together

---

GET /apiv2/time/status/

Get status for a specific TRON address in Host Mode.

Endpoint URL

GET https://netts.io/apiv2/time/status/{address}

Path Parameters:

Parameter	Type	Description
address	string	The TRON address to get status for (e.g., TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE)

Authentication

This endpoint uses header-based authentication (not JSON body). Provide your API key in the X-API-KEY header.

Request Headers

Header	Required	Description
X-API-KEY	Yes	Your API authentication key

Example Requests

cURL:

curl -X GET "https://netts.io/apiv2/time/status/TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" \
  -H "X-API-KEY: YOUR_API_KEY_HERE"

Python:

import requests

def get_address_status(api_key: str, address: str) -> dict:
    """Get status for a specific address."""
    url = f"https://netts.io/apiv2/time/status/{address}"

    headers = {
        "X-API-KEY": api_key
    }

    response = requests.get(url, headers=headers, verify=True, timeout=30)
    response.raise_for_status()

    result = response.json()

    if result['code'] == 0:
        addr = result['data']
        print(f"📍 Address: {addr['address']}")
        print(f"   Mode: {addr['mode']}")
        print(f"   Status: {addr['status']}")
        print(f"   Cycles completed: {addr['cycles_completed']}")
        print(f"   Cycles remaining: {addr['cycles_remaining']}")

    return result

# Example usage
API_KEY = "YOUR_API_KEY_HERE"
ADDRESS = "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
result = get_address_status(API_KEY, ADDRESS)

Node.js:

const axios = require('axios');

async function getAddressStatus(apiKey, address) {
    const url = `https://netts.io/apiv2/time/status/${address}`;

    const response = await axios.get(url, {
        headers: {
            'X-API-KEY': apiKey
        },
        timeout: 30000
    });

    const result = response.data;

    if (result.code === 0) {
        const addr = result.data;
        console.log(`📍 Address: ${addr.address}`);
        console.log(`   Mode: ${addr.mode}`);
        console.log(`   Status: ${addr.status}`);
        console.log(`   Cycles completed: ${addr.cycles_completed}`);
        console.log(`   Cycles remaining: ${addr.cycles_remaining}`);
    }

    return result;
}

// Example usage
const API_KEY = 'YOUR_API_KEY_HERE';
const ADDRESS = 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE';
getAddressStatus(API_KEY, ADDRESS);

PHP:

<?php
$apiKey = 'YOUR_API_KEY_HERE';
$address = 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE';
$url = "https://netts.io/apiv2/time/status/$address";

$options = [
    'http' => [
        'header' => "X-API-KEY: $apiKey\r\n",
        'method' => 'GET',
        'timeout' => 30
    ]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$result = json_decode($response, true);

if ($result['code'] == 0) {
    $addr = $result['data'];
    echo "📍 Address: {$addr['address']}\n";
    echo "   Mode: {$addr['mode']}\n";
    echo "   Status: {$addr['status']}\n";
    echo "   Cycles completed: {$addr['cycles_completed']}\n";
    echo "   Cycles remaining: {$addr['cycles_remaining']}\n";
}
?>

Success Response (200 OK)

{
    "code": 0,
    "msg": "Status retrieved successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "mode": "normal",
        "status": "active",
        "cycles_ordered": 25,
        "cycle_set": 25,
        "cycles_completed": 10,
        "cycles_remaining": 15,
        "open_orders": 2,
        "created_at": "2023-11-08T12:00:00.000000",
        "updated_at": "2023-11-09T10:00:00.000000"
    }
}

Error Responses

Address Not Found (404):

{
    "code": -1,
    "msg": "Address not found in Host Mode",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "suggestion": "Use /time/add to add this address"
    }
}

Authentication Error (401):

{
    "code": -1,
    "msg": "Invalid API key",
    "data": null
}

Invalid Address Format (400):

{
    "code": -1,
    "msg": "Invalid TRON address format",
    "data": {
        "address": "invalid_address",
        "requirement": "Must be a valid TRON address starting with 'T'"
    }
}

---

Rate Limits

Period	Limit	Description
1 minute	60 requests	Higher limit for status checks
1 hour	1000 requests	Maximum 1000 requests per hour
1 day	10000 requests	Maximum 10000 requests per day

Rate Limit Headers

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Reset-Minute: 1699528860

X-RateLimit-Limit-Hour: 1000
X-RateLimit-Remaining-Hour: 998
X-RateLimit-Reset-Hour: 1699532400

X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 9995
X-RateLimit-Reset-Day: 1699574400

Rate Limit Exceeded Response (429)

{
    "code": -1,
    "msg": "API rate limit exceeded",
    "data": {
        "retry_after": 45,
        "limit": "60 per minute",
        "reset_at": 1699528860
    }
}

Understanding Status Data

Address Modes

1. Standard Mode

   • Fixed number of cycles
   • Manual cycle purchases
   • Cycles consumed sequentially
   • Shown as mode: "standard"

2. Infinity Mode

   • Unlimited cycles
   • Daily billing
   • Auto-renewal
   • Shown as mode: "infinity"
   • cycles_remaining: -1 indicates unlimited

Address Status Values

Status	Description	Can Receive Energy	Action Required
active	Normal operation	Yes	None
paused	Temporarily stopped	No	Use /time/infinitystart to resume
stopped	Permanently stopped	No	Use /time/add to restart
error	Problem detected	Maybe	Check error details
pending	Activation in progress	Soon	Wait for activation
expired	All cycles consumed	No	Purchase more cycles

Energy States

1. Delegated Energy (current_energy)

   • Amount currently delegated to address
   • Usually 131,000 when active
   • 0 when paused or stopped

2. Energy Usage (energy_usage_24h)

   • Actual consumption in last 24 hours
   • Helps optimize cycle purchases
   • Used for utilization calculations

3. Energy Efficiency (average_energy_per_tx)

   • Average energy per transaction
   • Lower is more efficient
   • Helps identify optimization opportunities

Cycle Information

• cycles_remaining: Unused cycles in queue
• cycles_used: Historical count of consumed cycles
• -1: Indicates infinity mode (unlimited)
• 0: No cycles, needs purchase or infinity mode

Summary Statistics

Key Metrics

1. Utilization Rate

   utilization_rate = (total_energy_used_24h / total_energy_capacity) × 100

   • Shows efficiency of energy allocation
   • High rate (>80%) suggests need for more energy
   • Low rate (<30%) suggests over-provisioning

2. Address Health

   • Healthy: Active with sufficient cycles
   • Warning: <5 cycles remaining
   • Critical: 0 cycles or error status

3. Cost Analysis

   • Daily spend rate
   • Cost per transaction
   • Infinity vs standard mode comparison

Monitoring Recommendations

Metric	Good	Warning	Critical
Cycles Remaining	>10	5-10	<5
Utilization Rate	50-80%	30-50% or 80-90%	<30% or >90%
Failed Transactions	0	1-5 per day	>5 per day
Account Balance	>30 days cost	7-30 days	<7 days

Using Status Data

Common Use Cases

1. Monitoring Dashboard

   # Poll status every 5 minutes
   import time
   
   while True:
       status = get_host_mode_status(API_KEY)
       update_dashboard(status)
       check_alerts(status)
       time.sleep(300)

2. Low Cycle Alert

   // Check for addresses with low cycles
   const lowCycleAddresses = result.data.addresses.filter(
       addr => addr.cycles_remaining > 0 && addr.cycles_remaining < 5
   );
   
   if (lowCycleAddresses.length > 0) {
       sendAlert('Low cycles detected', lowCycleAddresses);
   }

3. Cost Optimization

   # Compare standard vs infinity mode costs
   def analyze_cost_efficiency(status_data):
       for addr in status_data['addresses']:
           if addr['mode'] == 'standard':
               daily_cycles = addr['energy_usage_24h'] / 131000
               standard_cost = daily_cycles * 3.0  # Price per cycle
               infinity_cost = 30.0  # Daily infinity rate
               
               if standard_cost > infinity_cost:
                   print(f"{addr['address']} would save with infinity mode")

4. Automated Cycle Purchase

   // Auto-purchase cycles when low
   async function maintainCycles(minCycles = 10) {
       const status = await getHostModeStatus(API_KEY);
       
       for (const addr of status.data.addresses) {
           if (addr.cycles_remaining < minCycles && addr.mode === 'standard') {
               await orderCycles(API_KEY, addr.address, 50);
               console.log(`Ordered 50 cycles for ${addr.address}`);
           }
       }
   }

Billing Information

Understanding Billing Data

1. Current Period Charges

   • Accumulated charges in current billing period
   • Includes cycle purchases and infinity mode fees
   • Resets at billing cycle end

2. Payment Methods

   • account_balance: Using prepaid balance
   • card: Credit/debit card on file
   • crypto: Cryptocurrency payments
   • invoice: Enterprise invoicing

3. Auto-Recharge

   • Automatically tops up balance when low
   • Configurable threshold and amount
   • Prevents service interruption

Billing Cycles

Billing Type	Period	Charge Time	Invoice
Cycle Purchase	Immediate	At purchase	Yes
Infinity Daily	24 hours	Midnight UTC	Daily
Infinity Weekly	7 days	Sunday UTC	Weekly
Infinity Monthly	30 days	1st of month	Monthly

Technical Details

Response Caching

• Status data cached for 30 seconds
• Real-time delegation status always fresh
• Historical data updated every 5 minutes
• Force refresh available via header

Data Aggregation

The status endpoint aggregates data from multiple sources:

1. Database: Address configuration, cycles, history
2. Blockchain: Current delegations, energy levels
3. Cache: Recent transactions, usage statistics
4. Billing System: Charges, payments, balances

Performance Considerations

• Response time: 200-500ms typical
• Large accounts (>50 addresses): 500-1000ms
• Maximum addresses returned: 1000
• Pagination available for large accounts

Security Considerations

Data Privacy

• Only shows addresses owned by API key
• No cross-account data exposure
• Sensitive data (full API key) redacted
• Transaction hashes truncated

Access Control

1. Read-Only Access

   • Status endpoint is read-only
   • Cannot modify addresses or settings
   • Safe for monitoring systems

2. IP Restrictions

   • Enforced even for read operations
   • Prevents unauthorized access
   • Logs all access attempts

3. Rate Limiting

   • Higher limits for status checks
   • Prevents abuse and scanning
   • Per-API-key enforcement

Related Endpoints

• POST /apiv2/time/add - Add new addresses to Host Mode
• POST /apiv2/time/order - Purchase cycles for addresses
• POST /apiv2/time/infinitystart - Enable infinity mode
• POST /apiv2/time/stop - Pause energy delegations
• POST /apiv2/time/delete - Remove addresses from Host Mode

Best Practices

Monitoring Strategy

1. Regular Polling

   • Check status every 5-15 minutes
   • More frequent during high activity
   • Less frequent during off-hours

2. Alert Thresholds

   • Low cycles: <5 remaining
   • Low balance: <7 days of costs
   • High utilization: >90%
   • Errors: Any error status

3. Data Retention

   • Store status snapshots hourly
   • Keep daily summaries for 30 days
   • Archive monthly reports

Integration Patterns

1. Dashboard Integration

   // Update dashboard with real-time data
   setInterval(async () => {
       const status = await getHostModeStatus(API_KEY);
       updateDashboard(status);
       checkAlerts(status);
   }, 300000); // Every 5 minutes

2. Webhook Triggers

   # Trigger webhooks based on status
   def check_status_triggers(status_data):
       for addr in status_data['addresses']:
           if addr['cycles_remaining'] < 5:
               trigger_webhook('low_cycles', addr)
           if addr['status'] == 'error':
               trigger_webhook('address_error', addr)

3. Automated Management

   # Automated address management
   def manage_addresses(status_data):
       for addr in status_data['addresses']:
           # Auto-purchase cycles
           if addr['cycles_remaining'] < 10:
               order_cycles(addr['address'], 50)
           
           # Switch to infinity for high usage
           if addr['energy_usage_24h'] > 300000:
               enable_infinity_mode(addr['address'])

Troubleshooting

Common Issues

Empty Address List

Problem: Status returns no addresses despite having added them

Solutions:

• Verify correct API key is being used
• Check if addresses were deleted
• Ensure addresses were successfully added
• Wait 1-2 minutes after adding for propagation

Stale Data

Problem: Status data seems outdated

Solutions:

• Check last_activity timestamps
• Verify blockchain connectivity
• Force cache refresh with header
• Contact support if persists

Missing Fields

Problem: Some expected fields are null or missing

Solutions:

• Check if address is in correct mode
• Some fields only appear for specific statuses
• Infinity mode has different fields than standard
• Review field documentation

Incorrect Energy Values

Problem: Energy values don't match expectations

Solutions:

• Energy updates may have 1-2 minute delay
• Check blockchain for confirmation
• Verify delegation transaction completed
• Consider network congestion

Performance Issues

Slow Response Times

Symptoms: Status endpoint takes >2 seconds

Solutions:

• Check number of addresses (pagination for >100)
• Verify network connectivity
• Consider caching responses client-side
• Use summary endpoint for overview

Rate Limit Issues

Symptoms: Hitting rate limits frequently

Solutions:

• Reduce polling frequency
• Implement exponential backoff
• Cache responses appropriately
• Consider webhook notifications instead

Notes

• Real-Time Data: Energy and delegation status are real-time from blockchain
• Historical Data: Transaction counts and usage stats update every 5 minutes
• Billing Data: Payment and charge information updates immediately
• No Filtering: All addresses returned; filter client-side if needed
• Timezone: All timestamps in Unix format (UTC)
• Precision: Energy amounts in base units (1 TRX = 1,000,000 SUN)
• Infinity Mode: Shows as -1 cycles (unlimited)
• Pagination: Available for accounts with >1000 addresses
• Webhooks: Consider webhooks for real-time updates instead of polling
• Caching: Implement client-side caching to reduce API calls
• Batch Operations: Status check is more efficient than individual address queries
• Mobile Apps: Higher rate limits available for verified mobile applications
• Enterprise: Custom endpoints available for enterprise accounts
• SLA: 99.9% uptime guarantee for status endpoint
• Monitoring: Built-in monitoring and alerting for enterprise accounts