Skip to content

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

HeaderRequiredDescription
Content-TypeYesapplication/json

Request Body

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

Parameters

ParameterTypeRequiredValidationDescription
api_keystringYesMust exist in systemYour API key for authentication and billing
addressstringYesTRC-20 formatTRON address to add to Host Mode (must start with 'T' and be 34 characters)
callback_urlstringNoHTTP/HTTPS URL, max 2048 charsWebhook 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

FieldTypeDescription
codeintegerResponse code (0 = success, negative = error)
msgstringHuman-readable response message
data.addressstringThe TRON address that was added
data.callback_urlstringCallback URL (only present if provided in request)
data.timestampstringISO 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):

PeriodLimitDescription
1 second1 requestMaximum 1 request per second
1 minute60 requestsMaximum 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

  1. Database Registration: Address is registered in the Host Mode system
  2. Status Set: Address status is set to 0 (ready for activation)
  3. Cycle Mode: Address is set to infinity mode by default (cycle_set = 0)
  4. 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:

Best Practices

Before Adding an Address

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

After Adding an Address

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

Troubleshooting

Common Issues

IssueCauseSolution
Authentication failedAPI key invalid or IP not whitelistedCheck API key and add IP to whitelist
Invalid address formatAddress doesn't match TRC-20 formatVerify address is 34 characters starting with 'T'
Address already existsTrying to add duplicate addressCheck existing addresses with Time Status
Database errorTemporary database issueRetry request after a few seconds

Error Code Reference

CodeHTTP StatusDescriptionAction Required
0200SuccessNone - address added successfully
-1400/401/500Various errorsCheck 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:

  1. Initial Energy Delegation: When energy is first delegated to a newly added address
  2. Cycle Renewal: When a new cycle starts and energy is re-delegated
  3. Manual Renewal: When energy is manually reclaimed and re-delegated
  4. 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:

ParameterTypeDescription
addressstringThe 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

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

Testing Callbacks

Test with webhook.site:

  1. Go to https://webhook.site/
  2. Copy the unique URL provided
  3. Use it as your callback_url when adding an address
  4. 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