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

Header	Required	Description
Content-Type	Yes	application/json

Request Body

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

Parameters

Parameter	Type	Required	Validation	Description
api_key	string	Yes	Must exist in system	Your API key for authentication and account management
address	string	Yes	TRC-20 format	TRON 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

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

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

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

/**
 * 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

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)

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

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.address	string	The TRON address that was stopped
data.status	string	Current status ("paused", "stopped")
data.previous_status	string	Status before stopping ("active")
data.cycles_remaining	integer	Number of cycles preserved
data.mode	string	Current mode ("standard", "infinity")
data.energy_reclaimed	integer	Amount of energy reclaimed
data.stopped_at	integer	Unix timestamp when stopped
data.can_resume	boolean	Whether address can be resumed
data.resume_method	string	How to resume delegations
data.delegation_active	boolean	Whether delegation is active (always false after stop)
data.next_delegation_time	null	Next delegation time (null when stopped)
data.transaction_hash	string	TRON blockchain transaction hash for the reclaim
data.estimated_resume_cost	number	Cost to resume (usually 0)
data.savings	object	Resources saved by stopping

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

Address Not Found (404)

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

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

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

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

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

Period	Limit	Description
1 minute	6 requests	Maximum 6 requests per minute per API key
1 hour	100 requests	Maximum 100 requests per hour per API key
1 day	1000 requests	Maximum 1000 requests per day per API key

Rate Limit Headers

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)

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

Feature	Stop	Delete
Reversibility	Fully reversible	Permanent for billing cycle
Cycles	Preserved	Lost
Energy	Reclaimed	Reclaimed
Host Mode	Remains active	Removed
Resume Cost	Free	Must re-add and repurchase
Use Case	Temporary pause	Permanent 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

Mode	During Stop	Billing Impact
Standard	Paused	No new charges
Infinity	Varies	May continue daily billing
Cycles	Frozen	No 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

Related Endpoints

• POST /apiv2/time/add - Add address to Host Mode
• POST /apiv2/time/infinitystart - Resume stopped address
• POST /apiv2/time/status - Check current status
• POST /apiv2/time/delete - Permanently remove address
• POST /apiv2/time/order - Purchase cycles before resuming

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

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

2. Activity-Based

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

3. Threshold-Based

   # 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

   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

   // 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

Recommended Monitoring

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

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