Skip to content

POST /apiv2/time/stop

Temporarily stop energy delegation for a TRON address while keeping it in Host Mode.

Overview

The Time Stop endpoint pauses energy delegations for a specific TRON address without removing it from Host Mode. This is useful when you want to temporarily halt energy allocation while preserving your cycles and configuration. The address remains in Host Mode with all cycles intact and can be reactivated at any time without losing any settings or remaining cycles.

Endpoint URL

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

Authentication

This endpoint uses JSON body authentication (not headers). Your API key and target address are provided in the request body.

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. Ownership Verification: API key must own the specified address
  4. Status Check: Verifies address is in Host Mode and currently active
  5. Delegation Check: Ensures no critical delegations are in progress

Request Headers

HeaderRequiredDescription
Content-TypeYesapplication/json

Request Body

json
{
    "api_key": "your_api_key",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

Parameters

ParameterTypeRequiredValidationDescription
api_keystringYesMust exist in systemYour API key for authentication and account management
addressstringYesTRC-20 formatTRON address to stop delegations for (must start with 'T' and be 34 characters)

Parameter Validation

  • api_key:

    • Must be a valid 32-character hexadecimal string
    • Must be associated with an active account
    • Must have ownership of the specified address
    • Account must not be suspended or restricted
    • Must have stop/pause permissions
  • address:

    • Must match TRC-20 format ^T[1-9A-HJ-NP-Za-km-z]{33}$
    • Must be currently in Host Mode under your account
    • Must be in active or running state
    • Cannot be already stopped or paused
    • Must not have pending critical operations
  • 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

Example Requests

cURL

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

Python

python
import requests
import json
from typing import Dict, Optional

def stop_energy_delegation(api_key: str, address: str) -> Dict:
    """
    Temporarily stop energy delegation for a TRON address in Host Mode.
    
    Args:
        api_key: Your API authentication key
        address: TRON address to stop delegations for
        
    Returns:
        API response dictionary
    """
    url = "https://netts.io/apiv2/time/stop"
    
    # Validate address format
    if not address.startswith('T') or len(address) != 34:
        raise ValueError(f"Invalid TRON address format: {address}")
    
    data = {
        "api_key": api_key,
        "address": address
    }
    
    try:
        response = requests.post(url, json=data, verify=True, timeout=30)
        response.raise_for_status()
        
        result = response.json()
        
        if result['code'] == 0:
            print(f"✅ Successfully stopped delegations for: {result['data']['address']}")
            print(f"Status: {result['data']['status']}")
            print(f"Cycles preserved: {result['data']['cycles_remaining']}")
            print(f"Energy reclaimed: {result['data'].get('energy_reclaimed', 0)}")
            
            if result['data'].get('can_resume'):
                print("ℹ️ Address can be resumed anytime using /time/infinitystart")
        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 with status check
def stop_and_verify(api_key: str, address: str):
    """Stop delegation and verify the status."""
    # Stop delegation
    stop_result = stop_energy_delegation(api_key, address)
    
    if stop_result['code'] == 0:
        # Check status after stopping
        import time
        time.sleep(2)  # Wait for status update
        
        status_url = "https://netts.io/apiv2/time/status"
        status_response = requests.post(status_url, json={"api_key": api_key})
        
        if status_response.status_code == 200:
            status_data = status_response.json()
            for addr in status_data['data']['addresses']:
                if addr['address'] == address:
                    print(f"\n📊 Current Status:")
                    print(f"   Status: {addr['status']}")
                    print(f"   Delegation Active: {addr['delegation_active']}")
                    print(f"   Cycles Remaining: {addr['cycles_remaining']}")
                    break

if __name__ == "__main__":
    API_KEY = "YOUR_API_KEY_HERE"
    ADDRESS = "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
    
    stop_and_verify(API_KEY, ADDRESS)

Node.js

javascript
const axios = require('axios');

/**
 * Temporarily stop energy delegation for a TRON address in Host Mode
 * @param {string} apiKey - Your API authentication key
 * @param {string} address - TRON address to stop delegations for
 * @returns {Promise<Object>} API response
 */
async function stopEnergyDelegation(apiKey, address) {
    const url = 'https://netts.io/apiv2/time/stop';
    
    // Validate address format
    if (!address.startsWith('T') || address.length !== 34) {
        throw new Error(`Invalid TRON address format: ${address}`);
    }
    
    const data = {
        api_key: apiKey,
        address: address
    };
    
    try {
        const response = await axios.post(url, data, {
            headers: {
                'Content-Type': 'application/json'
            },
            timeout: 30000
        });
        
        const result = response.data;
        
        if (result.code === 0) {
            console.log(`✅ Successfully stopped delegations for: ${result.data.address}`);
            console.log(`Status: ${result.data.status}`);
            console.log(`Cycles preserved: ${result.data.cycles_remaining}`);
            console.log(`Energy reclaimed: ${result.data.energy_reclaimed || 0}`);
            
            if (result.data.can_resume) {
                console.log('ℹ️ Address can be resumed anytime');
            }
        } 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;
    }
}

/**
 * Stop multiple addresses in batch
 * @param {string} apiKey - Your API authentication key
 * @param {Array<string>} addresses - Array of TRON addresses
 * @returns {Promise<Array>} Results for each address
 */
async function batchStopDelegations(apiKey, addresses) {
    const results = [];
    
    for (const address of addresses) {
        try {
            console.log(`\nStopping ${address}...`);
            const result = await stopEnergyDelegation(apiKey, address);
            results.push({ address, success: result.code === 0, result });
            
            // Add delay to avoid rate limits
            await new Promise(resolve => setTimeout(resolve, 1000));
        } catch (error) {
            results.push({ address, success: false, error: error.message });
        }
    }
    
    // Summary
    const successful = results.filter(r => r.success).length;
    console.log(`\n📊 Batch Stop Summary:`);
    console.log(`   Successful: ${successful}/${addresses.length}`);
    console.log(`   Failed: ${addresses.length - successful}/${addresses.length}`);
    
    return results;
}

// Example usage
(async () => {
    const API_KEY = 'YOUR_API_KEY_HERE';
    const ADDRESS = 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE';
    
    try {
        // Stop single address
        const result = await stopEnergyDelegation(API_KEY, ADDRESS);
        console.log('Result:', result);
        
        // Example: Stop multiple addresses
        // const addresses = [
        //     'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
        //     'TYn8Y3khEsLJW2ChVWFMSMeRDow6KcbMTF'
        // ];
        // await batchStopDelegations(API_KEY, addresses);
        
    } catch (error) {
        console.error('Failed to stop delegation:', error.message);
    }
})();

PHP

php
<?php

/**
 * Temporarily stop energy delegation for a TRON address in Host Mode
 * 
 * @param string $apiKey Your API authentication key
 * @param string $address TRON address to stop delegations for
 * @return array API response
 */
function stopEnergyDelegation($apiKey, $address) {
    $url = 'https://netts.io/apiv2/time/stop';
    
    // Validate address format
    if (!preg_match('/^T[1-9A-HJ-NP-Za-km-z]{33}$/', $address)) {
        throw new InvalidArgumentException("Invalid TRON address format: $address");
    }
    
    $data = [
        'api_key' => $apiKey,
        'address' => $address
    ];
    
    $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) {
        echo "✅ Successfully stopped delegations for: {$result['data']['address']}\n";
        echo "Status: {$result['data']['status']}\n";
        echo "Cycles preserved: {$result['data']['cycles_remaining']}\n";
        echo "Energy reclaimed: " . ($result['data']['energy_reclaimed'] ?? 0) . "\n";
        
        if ($result['data']['can_resume'] ?? false) {
            echo "ℹ️ Address can be resumed anytime\n";
        }
    } else {
        echo "❌ Error: {$result['msg']}\n";
    }
    
    return $result;
}

/**
 * Stop and monitor address status
 * 
 * @param string $apiKey Your API authentication key
 * @param string $address TRON address to monitor
 * @param int $checkInterval Seconds between status checks
 * @param int $maxChecks Maximum number of status checks
 */
function stopAndMonitor($apiKey, $address, $checkInterval = 5, $maxChecks = 10) {
    // Stop delegation
    $stopResult = stopEnergyDelegation($apiKey, $address);
    
    if ($stopResult['code'] != 0) {
        return false;
    }
    
    echo "\n🔍 Monitoring status changes...\n";
    
    // Monitor status
    for ($i = 0; $i < $maxChecks; $i++) {
        sleep($checkInterval);
        
        $statusUrl = 'https://netts.io/apiv2/time/status';
        $statusData = ['api_key' => $apiKey];
        
        $options = [
            'http' => [
                'header' => "Content-Type: application/json\r\n",
                'method' => 'POST',
                'content' => json_encode($statusData),
                'timeout' => 30
            ]
        ];
        
        $context = stream_context_create($options);
        $response = @file_get_contents($statusUrl, false, $context);
        
        if ($response !== false) {
            $statusResult = json_decode($response, true);
            
            foreach ($statusResult['data']['addresses'] as $addr) {
                if ($addr['address'] == $address) {
                    echo "Check #" . ($i + 1) . ": Status = {$addr['status']}, ";
                    echo "Energy = {$addr['current_energy']}\n";
                    
                    if ($addr['status'] == 'paused' && $addr['current_energy'] == 0) {
                        echo "✅ Address successfully paused and energy reclaimed\n";
                        return true;
                    }
                    break;
                }
            }
        }
    }
    
    echo "⚠️ Max checks reached, final status may not be confirmed\n";
    return true;
}

// Example usage
$API_KEY = 'YOUR_API_KEY_HERE';
$ADDRESS = 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE';

try {
    // Simple stop
    $result = stopEnergyDelegation($API_KEY, $ADDRESS);
    print_r($result);
    
    // Stop with monitoring
    // stopAndMonitor($API_KEY, $ADDRESS);
    
} catch (Exception $e) {
    echo "Failed to stop delegation: " . $e->getMessage() . "\n";
}
?>

Go

go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "time"
)

// StopRequest represents the API request structure
type StopRequest struct {
    APIKey  string `json:"api_key"`
    Address string `json:"address"`
}

// StopResponse represents the API response structure
type StopResponse struct {
    Code int    `json:"code"`
    Msg  string `json:"msg"`
    Data struct {
        Address         string `json:"address"`
        Status          string `json:"status"`
        CyclesRemaining int    `json:"cycles_remaining"`
        EnergyReclaimed int    `json:"energy_reclaimed"`
        StoppedAt       int64  `json:"stopped_at"`
        CanResume       bool   `json:"can_resume"`
        TransactionHash string `json:"transaction_hash"`
    } `json:"data"`
}

// StopEnergyDelegation stops energy delegation for a TRON address
func StopEnergyDelegation(apiKey, address string) (*StopResponse, error) {
    url := "https://netts.io/apiv2/time/stop"
    
    // Validate address format
    if len(address) != 34 || address[0] != 'T' {
        return nil, fmt.Errorf("invalid TRON address format: %s", address)
    }
    
    // Create request
    reqData := StopRequest{
        APIKey:  apiKey,
        Address: address,
    }
    
    jsonData, err := json.Marshal(reqData)
    if err != nil {
        return nil, err
    }
    
    // Make HTTP request
    client := &http.Client{Timeout: 30 * time.Second}
    req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    if err != nil {
        return nil, err
    }
    
    req.Header.Set("Content-Type", "application/json")
    
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    // Read response
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }
    
    // Parse response
    var result StopResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }
    
    if result.Code == 0 {
        fmt.Printf("✅ Successfully stopped delegations for: %s\n", result.Data.Address)
        fmt.Printf("Status: %s\n", result.Data.Status)
        fmt.Printf("Cycles preserved: %d\n", result.Data.CyclesRemaining)
        fmt.Printf("Energy reclaimed: %d\n", result.Data.EnergyReclaimed)
        
        if result.Data.CanResume {
            fmt.Println("ℹ️ Address can be resumed anytime")
        }
    } else {
        fmt.Printf("❌ Error: %s\n", result.Msg)
    }
    
    return &result, nil
}

// BatchStop stops multiple addresses with rate limiting
func BatchStop(apiKey string, addresses []string) map[string]bool {
    results := make(map[string]bool)
    
    for i, address := range addresses {
        fmt.Printf("\n[%d/%d] Stopping %s...\n", i+1, len(addresses), address)
        
        result, err := StopEnergyDelegation(apiKey, address)
        if err != nil {
            fmt.Printf("Error: %v\n", err)
            results[address] = false
        } else {
            results[address] = result.Code == 0
        }
        
        // Rate limiting delay (except for last address)
        if i < len(addresses)-1 {
            time.Sleep(1 * time.Second)
        }
    }
    
    // Print summary
    successful := 0
    for _, success := range results {
        if success {
            successful++
        }
    }
    
    fmt.Printf("\n📊 Batch Stop Summary:\n")
    fmt.Printf("   Successful: %d/%d\n", successful, len(addresses))
    fmt.Printf("   Failed: %d/%d\n", len(addresses)-successful, len(addresses))
    
    return results
}

func main() {
    apiKey := "YOUR_API_KEY_HERE"
    address := "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
    
    // Stop single address
    result, err := StopEnergyDelegation(apiKey, address)
    if err != nil {
        fmt.Printf("Failed to stop delegation: %v\n", err)
        return
    }
    
    if result.Code == 0 {
        fmt.Printf("\nTransaction Hash: %s\n", result.Data.TransactionHash)
        
        stoppedTime := time.Unix(result.Data.StoppedAt, 0)
        fmt.Printf("Stopped at: %s\n", stoppedTime.Format("2006-01-02 15:04:05"))
    }
    
    // Example: Batch stop multiple addresses
    // addresses := []string{
    //     "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    //     "TYn8Y3khEsLJW2ChVWFMSMeRDow6KcbMTF",
    // }
    // BatchStop(apiKey, addresses)
}

Response

Success Response (200 OK)

json
{
    "code": 0,
    "msg": "Energy delegation stopped successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "status": "paused",
        "previous_status": "active",
        "cycles_remaining": 25,
        "mode": "standard",
        "energy_reclaimed": 131000,
        "stopped_at": 1699528800,
        "can_resume": true,
        "resume_method": "/time/infinitystart or wait for manual resume",
        "delegation_active": false,
        "next_delegation_time": null,
        "transaction_hash": "d9f5c3a2e8b1d7f4a9c6e3b8d5f2a7c4e9b6d3f8a5c2e9b6d3f8a5c2e9b6d3f8",
        "estimated_resume_cost": 0,
        "savings": {
            "energy_saved": 131000,
            "cycles_preserved": 25,
            "cost_saved": 75.0
        }
    }
}

Response Fields

FieldTypeDescription
codeintegerStatus code (0 for success, -1 for error)
msgstringHuman-readable status message
dataobjectResponse data object
data.addressstringThe TRON address that was stopped
data.statusstringCurrent status ("paused", "stopped")
data.previous_statusstringStatus before stopping ("active")
data.cycles_remainingintegerNumber of cycles preserved
data.modestringCurrent mode ("standard", "infinity")
data.energy_reclaimedintegerAmount of energy reclaimed
data.stopped_atintegerUnix timestamp when stopped
data.can_resumebooleanWhether address can be resumed
data.resume_methodstringHow to resume delegations
data.delegation_activebooleanWhether delegation is active (always false after stop)
data.next_delegation_timenullNext delegation time (null when stopped)
data.transaction_hashstringTRON blockchain transaction hash for the reclaim
data.estimated_resume_costnumberCost to resume (usually 0)
data.savingsobjectResources saved by stopping

Error Responses

Authentication Error (401)

json
{
    "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

Address Not Found (404)

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

Causes:

  • Address not in Host Mode
  • Address was deleted from Host Mode
  • Address belongs to different API key

Resolution:

  • Verify address is in Host Mode using /time/status
  • Check if address was deleted
  • Ensure using correct API key

Already Stopped (409)

json
{
    "code": -1,
    "msg": "Address delegation already stopped",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "status": "paused",
        "stopped_at": 1699442400,
        "suggestion": "Address is already paused. Use /time/infinitystart to resume"
    }
}

Causes:

  • Address already in paused state
  • Previous stop command already executed
  • Delegation already inactive

Resolution:

  • No action needed if already stopped
  • Use /time/infinitystart to resume if needed
  • Check current status with /time/status

Invalid Address Format (400)

json
{
    "code": -1,
    "msg": "Invalid TRON address format",
    "data": {
        "address": "invalid_address",
        "format": "Address must start with 'T' and be 34 characters long"
    }
}

Causes:

  • Address doesn't match TRC-20 format
  • Address contains invalid characters
  • Address wrong length

Resolution:

  • Verify address starts with 'T'
  • Ensure address is exactly 34 characters
  • Check for typos or copy/paste errors

Active Delegation in Progress (409)

json
{
    "code": -1,
    "msg": "Cannot stop address with active delegation in progress",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "delegation_ends": 1699529100,
        "retry_after": 300,
        "suggestion": "Wait for current delegation to complete"
    }
}

Causes:

  • Energy delegation transaction in progress
  • Critical operation not yet completed
  • Blockchain confirmation pending

Resolution:

  • Wait for current delegation to complete
  • Retry after specified time
  • Check transaction status on blockchain

Insufficient Permissions (403)

json
{
    "code": -1,
    "msg": "Insufficient permissions to stop address",
    "data": {
        "required_permission": "manage_addresses",
        "your_permissions": ["read_only"]
    }
}

Causes:

  • API key has read-only permissions
  • Stop operations disabled for account
  • Sub-account with limited permissions

Resolution:

  • Request permission upgrade from account owner
  • Use master API key instead of sub-account key
  • Contact support to enable stop permissions

Rate Limits

PeriodLimitDescription
1 minute6 requestsMaximum 6 requests per minute per API key
1 hour100 requestsMaximum 100 requests per hour per API key
1 day1000 requestsMaximum 1000 requests per day per API key

Rate Limit Headers

http
X-RateLimit-Limit-Minute: 6
X-RateLimit-Remaining-Minute: 5
X-RateLimit-Reset-Minute: 1699528860

X-RateLimit-Limit-Hour: 100
X-RateLimit-Remaining-Hour: 98
X-RateLimit-Reset-Hour: 1699532400

X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 995
X-RateLimit-Reset-Day: 1699574400

Rate Limit Exceeded Response (429)

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

Understanding Stop Functionality

What Happens When You Stop

  1. Immediate Actions

    • Energy delegation halted immediately
    • Any active energy reclaimed from address
    • Address status changed to "paused"
    • Cycles remain intact and preserved
  2. Energy Reclamation

    • Currently delegated energy returned to pool
    • Takes 1-2 TRON blocks (3-6 seconds)
    • Energy available for other addresses
    • Transaction recorded on blockchain
  3. Cycle Preservation

    • All remaining cycles kept in queue
    • No cycles lost or expired
    • Cycle counter frozen
    • Ready for resumption anytime
  4. Status Updates

    • Database updated to paused state
    • Monitoring alerts may trigger
    • Webhooks sent if configured
    • Dashboard reflects new status

Stop vs Delete Comparison

FeatureStopDelete
ReversibilityFully reversiblePermanent for billing cycle
CyclesPreservedLost
EnergyReclaimedReclaimed
Host ModeRemains activeRemoved
Resume CostFreeMust re-add and repurchase
Use CaseTemporary pausePermanent removal

When to Use Stop

  1. Maintenance Windows

    • Scheduled blockchain maintenance
    • Smart contract upgrades
    • Wallet maintenance
    • Security audits
  2. Cost Optimization

    • Low activity periods
    • Weekend/holiday breaks
    • Testing phases complete
    • Budget constraints
  3. Security Concerns

    • Suspicious activity detected
    • Key compromise suspected
    • Pending security review
    • Emergency response
  4. Operational Reasons

    • Project paused
    • Development halted
    • Migration in progress
    • Resource reallocation

Resume Process

How to Resume

After stopping an address, you can resume energy delegations using:

  1. Automatic Resume (Not available - must use manual)

  2. Manual Resume via API

    • Use /time/infinitystart endpoint to resume
    • Same API key required
    • Instant reactivation
  3. Dashboard Resume

    • Login to dashboard
    • Navigate to Host Mode section
    • Click "Resume" button
    • Confirm action

Resume Requirements

  • Address must be in paused state
  • API key must own the address
  • Account must be active
  • No pending operations

Resume Timeline

  • Instant: Status change immediate
  • Energy Delegation: Next cycle within 1-5 minutes
  • Full Activation: Complete within one cycle period

Host Mode Impact

Before Stopping

  • Address receives automatic energy every 24 hours
  • Cycles consumed sequentially
  • Energy available for transactions
  • Automatic management active

During Stop Period

  • No energy delegations occur
  • Cycles remain frozen
  • Address uses own resources only
  • Management suspended

After Resuming

  • Energy delegations restart
  • Cycles continue from where stopped
  • Automatic management resumes
  • No configuration lost

Billing Implications

Cost Savings

  • Standard Mode: No charges during stop period
  • Infinity Mode: Daily charges may pause (check terms)
  • Cycles: Preserved cycles retain value
  • Refunds: No refunds for partial cycles

Billing Behavior

ModeDuring StopBilling Impact
StandardPausedNo new charges
InfinityVariesMay continue daily billing
CyclesFrozenNo consumption, no charges

Resume Costs

  • Standard Mode: No cost to resume
  • Infinity Mode: Regular billing resumes
  • Additional Cycles: Can purchase when resuming

Security Considerations

Authentication Security

  • API Key Storage: Never expose API keys in client-side code
  • HTTPS Only: All requests must use HTTPS
  • IP Whitelist: Configure IP whitelist for production use
  • Key Rotation: Rotate API keys regularly

Stop Operation Security

  1. Ownership Verification

    • Only owner can stop address
    • API key must match records
    • IP must be whitelisted
  2. State Validation

    • Address must be active
    • No pending operations
    • Valid Host Mode status
  3. Audit Trail

    • All stop operations logged
    • Timestamp recorded
    • IP address captured
    • Reason tracking available

Security Best Practices

  • Stop addresses immediately if compromise suspected
  • Monitor stop/resume patterns for anomalies
  • Set up alerts for unexpected stops
  • Review audit logs regularly

Technical Architecture

Service Components

  1. API Gateway

    • Request validation and routing
    • Rate limiting enforcement
    • IP whitelist checking
  2. State Manager

    • Address state transitions
    • Status validation
    • Conflict resolution
  3. Energy Manager

    • Delegation control
    • Energy reclamation
    • Resource reallocation
  4. Blockchain Service

    • Undelegate transactions
    • Confirmation monitoring
    • Transaction verification
  5. Database Layer

    • State persistence
    • Audit logging
    • Status tracking

Request Flow

  1. Client sends POST request with API key and address
  2. API Gateway validates request format and rate limits
  3. Authentication Service verifies API key and permissions
  4. State Manager checks current address status
  5. Energy Manager initiates reclamation if energy delegated
  6. Blockchain Service submits undelegate transaction
  7. Database updated with paused state
  8. Response sent to client with transaction details

State Transitions

Active → Stopping → Paused → Resuming → Active
         ↓                      ↓
      [Error]              [Error]
         ↓                      ↓
      Active                Paused

Best Practices

When to Stop

  1. Planned Maintenance

    • Stop before maintenance windows
    • Resume after confirmation
    • Test on non-critical addresses first
  2. Cost Management

    • Stop during low activity periods
    • Monitor usage patterns
    • Optimize based on actual needs
  3. Security Response

    • Stop immediately on suspicion
    • Investigate thoroughly
    • Resume only when cleared

Stop Patterns

  1. Regular Schedule

    python
    # Stop addresses on weekends
    import datetime
    
    if datetime.datetime.now().weekday() >= 5:  # Saturday or Sunday
        stop_energy_delegation(API_KEY, ADDRESS)
  2. Activity-Based

    javascript
    // Stop if no activity for 24 hours
    if (address.transaction_count_24h === 0) {
        await stopEnergyDelegation(API_KEY, address.address);
    }
  3. Threshold-Based

    python
    # Stop if energy usage below threshold
    if address['energy_usage_24h'] < 10000:
        stop_energy_delegation(API_KEY, address['address'])

Automation Examples

  1. Scheduled Stop/Resume

    python
    import schedule
    import time
    
    def stop_for_maintenance():
        stop_energy_delegation(API_KEY, ADDRESS)
    
    def resume_after_maintenance():
        # Use infinitystart endpoint to resume
        resume_energy_delegation(API_KEY, ADDRESS)
    
    # Schedule stop at 2 AM
    schedule.every().day.at("02:00").do(stop_for_maintenance)
    # Schedule resume at 4 AM
    schedule.every().day.at("04:00").do(resume_after_maintenance)
    
    while True:
        schedule.run_pending()
        time.sleep(60)
  2. Conditional Stop

    javascript
    // Stop based on market conditions
    async function conditionalStop() {
        const marketPrice = await getTRXPrice();
        
        if (marketPrice > THRESHOLD_PRICE) {
            // Stop to save costs when price high
            await stopEnergyDelegation(API_KEY, ADDRESS);
        }
    }

Troubleshooting

Common Issues

"Address not found in Host Mode"

Problem: Trying to stop an address not in Host Mode

Solutions:

  • Verify address with /time/status endpoint
  • Check if address was deleted
  • Ensure using correct API key
  • Verify address format is correct

"Address delegation already stopped"

Problem: Address is already in paused state

Solutions:

  • Check current status with /time/status
  • No action needed if already stopped
  • Use /time/infinitystart to resume if needed

"Cannot stop address with active delegation"

Problem: Delegation transaction in progress

Solutions:

  • Wait 1-2 minutes for transaction to complete
  • Check blockchain for transaction status
  • Retry after confirmation
  • Contact support if persists

"Invalid API key"

Problem: API key not recognized or expired

Solutions:

  • Verify API key is correct
  • Check account status in dashboard
  • Ensure API key has proper permissions
  • Generate new API key if needed

Stop Not Taking Effect

Symptoms: Address still showing as active after stop

Solutions:

  1. Wait 1-2 minutes for propagation
  2. Check transaction hash on blockchain
  3. Verify no errors in response
  4. Force refresh status endpoint
  5. Contact support with transaction details

Energy Not Reclaimed

Symptoms: Energy still delegated after stop

Solutions:

  1. Check blockchain transaction status
  2. Wait for network confirmation
  3. Verify sufficient bandwidth for transaction
  4. Check for network congestion
  5. Contact support if energy stuck

Cannot Resume After Stop

Symptoms: Resume attempts fail

Solutions:

  1. Verify address is in paused state
  2. Check account has sufficient balance
  3. Ensure no pending operations
  4. Try resume after 5 minutes
  5. Contact support with error details

Monitoring and Alerts

  1. Stop Events

    • Track all stop operations
    • Monitor stop frequency
    • Alert on unexpected stops
  2. Resume Patterns

    • Track time between stop and resume
    • Identify addresses frequently stopped
    • Alert on failed resumes
  3. Cost Impact

    • Calculate savings from stops
    • Track efficiency improvements
    • Monitor billing changes

Alert Configurations

json
{
    "alerts": [
        {
            "type": "address_stopped",
            "threshold": "immediate",
            "notification": "email"
        },
        {
            "type": "multiple_stops",
            "threshold": "3 in 1 hour",
            "notification": "sms"
        },
        {
            "type": "stop_failed",
            "threshold": "immediate",
            "notification": "webhook"
        }
    ]
}

Notes

  • Instant Effect: Stop takes effect immediately upon success
  • Cycle Preservation: All cycles remain intact during stop period
  • Free Resume: No cost to resume stopped addresses
  • Energy Reclaim: Reclaimed energy available for other addresses immediately
  • No Time Limit: Addresses can remain stopped indefinitely
  • Batch Operations: Stop multiple addresses with client-side iteration
  • Webhook Support: Configure webhooks for stop/resume notifications
  • Audit Trail: All stop operations logged for compliance
  • Emergency Stop: Can be used for immediate security response
  • Graceful Handling: System handles stop during active delegations
  • Status Persistence: Stop status survives system restarts
  • API Versioning: This is v2 API; v1 has different behavior
  • Maintenance Mode: Addresses remain stopped during platform maintenance
  • Recovery: Automatic recovery procedures if stop fails
  • Monitoring: Real-time monitoring of stopped addresses in dashboard