POST /apiv2/time/add

Add a TRON address to Host Mode for automated continuous energy delegation.

Overview

The Time Add endpoint registers a TRON address for Host Mode management, enabling automatic 24-hour energy delegation cycles. Once added, the address will receive 131,000 energy units that automatically renew based on usage patterns.

Endpoint URL

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

Authentication

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

Request Headers

Header	Required	Description
Content-Type	Yes	application/json

Request Body

json

{
    "api_key": "your_api_key",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook"
}

Parameters

Parameter	Type	Required	Validation	Description
api_key	string	Yes	Must exist in system	Your API key for authentication and billing
address	string	Yes	TRC-20 format	TRON address to add to Host Mode (must start with 'T' and be 34 characters)
callback_url	string	No	HTTP/HTTPS URL, max 2048 chars	Webhook URL to notify when energy is delegated to this address

Parameter Validation

api_key: Must be a valid API key associated with your account and have sufficient balance
address: Must match TRC-20 format ^T[1-9A-HJ-NP-Za-km-z]{33}$
callback_url (optional):
- Must be a valid HTTP or HTTPS URL
- Maximum length: 2048 characters
- Only public URLs allowed (no localhost, private IPs, or internal networks)
- SSRF protection: Blocks access to private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
- Blocks metadata endpoints (169.254.0.0/16 - AWS/GCP/Azure)
- Called when energy is delegated to the address
IP Address: Your request IP must be in the whitelist associated with your API key

Example Requests

cURL

bash

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

# With callback URL (recommended for automation)
curl -X POST https://netts.io/apiv2/time/add \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook"
  }'

Python

python

import requests

url = "https://netts.io/apiv2/time/add"

# Example 1: Without callback URL
data = {
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

# Example 2: With callback URL (recommended)
data_with_callback = {
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook"
}

response = requests.post(url, json=data_with_callback, verify=True)

if response.status_code == 200:
    result = response.json()
    if result['code'] == 0:
        print(f"✅ Address added successfully: {result['data']['address']}")
        if 'callback_url' in result['data']:
            print(f"📞 Callback URL: {result['data']['callback_url']}")
        print(f"Timestamp: {result['data']['timestamp']}")
    else:
        print(f"❌ Error: {result['msg']}")
else:
    print(f"HTTP Error: {response.status_code}")

Node.js

javascript

const axios = require('axios');

const url = 'https://netts.io/apiv2/time/add';
const data = {
    api_key: 'YOUR_API_KEY_HERE',
    address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE'
};

axios.post(url, data)
    .then(response => {
        const result = response.data;
        if (result.code === 0) {
            console.log(`✅ Address added: ${result.data.address}`);
        } else {
            console.log(`❌ Error: ${result.msg}`);
        }
    })
    .catch(error => {
        console.error('Request failed:', error.response?.data || error.message);
    });

Response

Success Response (200 OK)

Without callback URL:

json

{
    "code": 0,
    "msg": "Address added to Host Mode successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "timestamp": "2025-09-02T07:30:15.123456"
    }
}

With callback URL:

json

{
    "code": 0,
    "msg": "Address added to Host Mode successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://your-server.com/webhook",
        "timestamp": "2025-09-02T07:30:15.123456"
    }
}

Updating existing address callback URL:

json

{
    "code": 0,
    "msg": "Address callback URL updated successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://new-webhook.com/endpoint",
        "timestamp": "2025-09-02T07:35:20.789012"
    }
}

Response Fields

Field	Type	Description
code	integer	Response code (0 = success, negative = error)
msg	string	Human-readable response message
data.address	string	The TRON address that was added
data.callback_url	string	Callback URL (only present if provided in request)
data.timestamp	string	ISO timestamp when address was added or updated

Error Responses

Authentication Error (401)

json

{
    "code": -1,
    "msg": "Invalid API key or IP not in whitelist",
    "data": null
}

Invalid Address Format (400)

json

{
    "code": -1,
    "msg": "Invalid TRC-20 address format",
    "data": null
}

Address Already Exists (400)

json

{
    "code": -1,
    "msg": "This address is already managed in Host Mode",
    "data": null
}

Invalid Callback URL (400)

json

{
    "code": -1,
    "msg": "Invalid callback URL. Only public HTTP/HTTPS URLs are allowed",
    "data": null
}

Causes:

Callback URL uses non-HTTP/HTTPS protocol (e.g., ftp://, file://)
URL points to private network or localhost
URL points to cloud metadata endpoints (169.254.169.254)
URL exceeds 2048 characters

Resolution:

Use only public HTTP or HTTPS URLs
Ensure URL is accessible from the internet
Check URL length is under 2048 characters
Test URL is reachable before adding

Database Error (500)

json

{
    "code": -1,
    "msg": "Database error adding address",
    "data": null
}

Internal Server Error (500)

json

{
    "code": -1,
    "msg": "Internal server error",
    "data": null
}

Rate Limits

The following rate limits apply to this endpoint (per IP address):

Period	Limit	Description
1 second	1 request	Maximum 1 request per second
1 minute	60 requests	Maximum 60 requests per minute

Rate Limit Headers

The API returns rate limiting information in response headers:

http

RateLimit-Limit: 1
RateLimit-Remaining: 0
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 1
X-RateLimit-Remaining-Second: 0
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
Retry-After: 1

Rate Limit Exceeded (429)

json

{
    "message": "API rate limit exceeded"
}

When rate limit is exceeded, wait for the time specified in Retry-After header.

What Happens After Adding an Address

Database Registration: Address is registered in the Host Mode system
Status Set: Address status is set to 0 (ready for activation)
Cycle Mode: Address is set to infinity mode by default (cycle_set = 0)
Ready for Energy: Address is now ready to receive automatic energy delegation

Host Mode Behavior

Once an address is added to Host Mode:

Energy Amount: 131,000 energy units per delegation
Duration: 24 hours per delegation cycle
Auto-Renewal: Energy automatically renews when:
- USDT transfer is detected (immediate reclaim + re-delegate)
- 24 hours pass with no activity (automatic renewal)
Cycle Consumption: Each delegation consumes 1 cycle from your balance

Security and Validation

Address Validation

Format Check: Address must match TRC-20 format T[1-9A-HJ-NP-Za-km-z]{33}
Length Check: Exactly 34 characters
Duplicate Prevention: Cannot add the same address twice

Authentication Security

API Key Validation: Key must exist and be active
IP Whitelist: Request IP must be in your account's whitelist
User Verification: System validates both TG and normal users

Database Security

Transaction Safety: Uses database transactions for consistency
Rollback Protection: Automatic rollback on errors
Connection Pooling: Secure connection management with HAProxy

Technical Details

Service Architecture

Port: 9010
Framework: FastAPI with Pydantic models
Database: PostgreSQL with connection pooling
Load Balancing: HAProxy for read/write operations
Logging: Comprehensive logging to /path/to/your/logs/time_api.log

Database Operations

Table: netts_web_hosting_mode
Operation: INSERT new record
Default Values:
- status = 0 (ready)
- cycle_set = 0 (infinity mode)
Timestamps: Automatic created_at and updated_at

After adding an address, you can:

Time Status - Check address status and cycles
Time Order - Purchase specific number of cycles
Time Infinity Start - Enable unlimited cycles
Time Stop - Temporarily pause energy delegation
Time Delete - Remove address from Host Mode

Best Practices

Before Adding an Address

Verify Address: Double-check TRON address is correct and activated
Check Balance: Ensure sufficient TRX balance for cycles
IP Whitelist: Confirm your IP is whitelisted
Test API Key: Verify API key works with other endpoints

After Adding an Address

Monitor Status: Use Time Status endpoint to track cycles
Set Cycles: Use Time Order to purchase specific cycles if needed
Enable Infinity: Use Time Infinity Start for continuous operation
Track Usage: Monitor your energy delegation cycles and costs

Troubleshooting

Common Issues

Issue	Cause	Solution
Authentication failed	API key invalid or IP not whitelisted	Check API key and add IP to whitelist
Invalid address format	Address doesn't match TRC-20 format	Verify address is 34 characters starting with 'T'
Address already exists	Trying to add duplicate address	Check existing addresses with Time Status
Database error	Temporary database issue	Retry request after a few seconds

Error Code Reference

Code	HTTP Status	Description	Action Required
`0`	200	Success	None - address added successfully
`-1`	400/401/500	Various errors	Check error message for details

Callback Webhooks

Overview

When you provide a callback_url parameter, the system will call your webhook URL whenever energy is successfully delegated to the address. This allows you to receive real-time notifications about energy delegation events without polling the status endpoint.

When Callbacks Are Triggered

Your callback URL will be called in the following scenarios:

Initial Energy Delegation: When energy is first delegated to a newly added address
Cycle Renewal: When a new cycle starts and energy is re-delegated
Manual Renewal: When energy is manually reclaimed and re-delegated
Auto-Renewal: When 24 hours pass and automatic renewal occurs

Callback Request Format

The system will make a GET request to your callback URL with the following query parameters:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE

Query Parameters:

Parameter	Type	Description
address	string	The TRON address that received energy delegation

Example Callback Handler

Python (Flask):

python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['GET'])
def energy_delegation_webhook():
    address = request.args.get('address')

    if not address:
        return jsonify({"error": "Missing address parameter"}), 400

    # Process the energy delegation event
    print(f"✅ Energy delegated to address: {address}")

    # Your business logic here:
    # - Update your database
    # - Send notification to user
    # - Trigger dependent processes
    # - Log the event

    return jsonify({"status": "success"}), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Node.js (Express):

javascript

const express = require('express');
const app = express();

app.get('/webhook', (req, res) => {
    const address = req.query.address;

    if (!address) {
        return res.status(400).json({ error: 'Missing address parameter' });
    }

    // Process the energy delegation event
    console.log(`✅ Energy delegated to address: ${address}`);

    // Your business logic here:
    // - Update your database
    // - Send notification to user
    // - Trigger dependent processes
    // - Log the event

    res.status(200).json({ status: 'success' });
});

app.listen(5000, () => {
    console.log('Webhook server running on port 5000');
});

PHP:

php

<?php
// webhook.php

// Get the address parameter
$address = $_GET['address'] ?? null;

if (!$address) {
    http_response_code(400);
    echo json_encode(['error' => 'Missing address parameter']);
    exit;
}

// Process the energy delegation event
error_log("✅ Energy delegated to address: $address");

// Your business logic here:
// - Update your database
// - Send notification to user
// - Trigger dependent processes
// - Log the event

http_response_code(200);
echo json_encode(['status' => 'success']);
?>

Callback URL Requirements

Security:

Must use HTTPS in production (HTTP allowed for testing)
Should validate the incoming request
Should respond quickly (< 5 seconds timeout)
Should return 200 status code on success

SSRF Protection: The system blocks callbacks to:

Localhost: 127.0.0.1, ::1, localhost
Private Networks: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
Link-Local: 169.254.0.0/16 (AWS/GCP/Azure metadata endpoints)
IPv6 Private: fc00::/7, fe80::/10
Reserved IPs: Multicast, broadcast, and reserved ranges

Allowed:

Public HTTP/HTTPS URLs only
Maximum URL length: 2048 characters
Standard ports (80, 443) or custom ports

Updating Callback URLs

You can update the callback URL for an existing address by calling the /time/add endpoint again with the same address and a new callback_url:

bash

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

The response will indicate the callback URL was updated:

json

{
    "code": 0,
    "msg": "Address callback URL updated successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://new-webhook.com/endpoint",
        "timestamp": "2025-09-02T07:35:20.789012"
    }
}

Removing Callback URLs

To remove a callback URL, call /time/delete endpoint to remove the address entirely. When you re-add it, simply don't include the callback_url parameter.

Callback Retry Logic

Important: The callback system does NOT implement automatic retries. If your webhook endpoint is down or returns an error:

The callback will fail silently
No retry attempts will be made
Energy delegation will still occur successfully

Recommendation: Implement your own monitoring and reconciliation:

Use /time/status endpoint to poll for delegation events
Compare with your callback logs to detect missed callbacks
Implement idempotency in your webhook handler

Best Practices

Idempotency: Design your webhook handler to be idempotent (safe to call multiple times)
Async Processing: Process webhook data asynchronously, respond quickly to avoid timeouts
Logging: Log all incoming webhook calls for debugging and reconciliation
Validation: Validate the address parameter matches your expected format
Error Handling: Handle errors gracefully and return appropriate status codes
Monitoring: Monitor webhook endpoint uptime and response times
Security: Use HTTPS and consider implementing webhook signature validation
Testing: Test your webhook endpoint before going live

Testing Callbacks

Test with webhook.site:

Go to https://webhook.site/
Copy the unique URL provided
Use it as your callback_url when adding an address
Monitor incoming requests on webhook.site

Test with ngrok (local development):

bash

# Start your local webhook server on port 5000
python webhook_server.py

# In another terminal, expose it publicly
ngrok http 5000

# Use the ngrok HTTPS URL as your callback_url
# Example: https://abc123.ngrok.io/webhook

Notes

Default Mode: Addresses are added in infinity mode by default (unlimited cycles)
Energy Delegation: System will begin managing energy for this address
Billing: Cycles are charged from your account balance automatically
Address Limit: Check your account limits for maximum addresses in Host Mode
Activation: Address should be activated on TRON network before adding
Monitoring: Use Time Status endpoint to monitor address performance

POST /apiv2/time/add ​

Overview ​

Endpoint URL ​

Authentication ​

Request Headers ​

Request Body ​

Parameters ​

Parameter Validation ​

Example Requests ​

cURL ​

Python ​

Node.js ​

Response ​

Success Response (200 OK) ​

Response Fields ​

Error Responses ​

Authentication Error (401) ​

Invalid Address Format (400) ​

Address Already Exists (400) ​

Invalid Callback URL (400) ​

Database Error (500) ​

Internal Server Error (500) ​

Rate Limits ​

Rate Limit Headers ​

Rate Limit Exceeded (429) ​

What Happens After Adding an Address ​

Host Mode Behavior ​

Security and Validation ​

Address Validation ​

Authentication Security ​

Database Security ​

Technical Details ​

Service Architecture ​

Database Operations ​

Related Endpoints ​

Best Practices ​

Before Adding an Address ​

After Adding an Address ​

Troubleshooting ​

Common Issues ​

Error Code Reference ​

Callback Webhooks ​

Overview ​

When Callbacks Are Triggered ​

Callback Request Format ​

Example Callback Handler ​

Callback URL Requirements ​

Updating Callback URLs ​

Removing Callback URLs ​

Callback Retry Logic ​

Best Practices ​

Testing Callbacks ​

Notes ​

POST /apiv2/time/add

Overview

Endpoint URL

Authentication

Request Headers

Request Body

Parameters

Parameter Validation

Example Requests

cURL

Python

Node.js

Response

Success Response (200 OK)

Response Fields

Error Responses

Authentication Error (401)

Invalid Address Format (400)

Address Already Exists (400)

Invalid Callback URL (400)

Database Error (500)

Internal Server Error (500)

Rate Limits

Rate Limit Headers

Rate Limit Exceeded (429)

What Happens After Adding an Address

Host Mode Behavior

Security and Validation

Address Validation

Authentication Security

Database Security

Technical Details

Service Architecture

Database Operations

Related Endpoints

Best Practices

Before Adding an Address

After Adding an Address

Troubleshooting

Common Issues

Error Code Reference

Callback Webhooks

Overview

When Callbacks Are Triggered

Callback Request Format

Example Callback Handler

Callback URL Requirements

Updating Callback URLs

Removing Callback URLs

Callback Retry Logic

Best Practices

Testing Callbacks

Notes