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
{
"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
# 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
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
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:
{
"code": 0,
"msg": "Address added to Host Mode successfully",
"data": {
"address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
"timestamp": "2025-09-02T07:30:15.123456"
}
}
With callback URL:
{
"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:
{
"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)
{
"code": -1,
"msg": "Invalid API key or IP not in whitelist",
"data": null
}
Invalid Address Format (400)
{
"code": -1,
"msg": "Invalid TRC-20 address format",
"data": null
}
Address Already Exists (400)
{
"code": -1,
"msg": "This address is already managed in Host Mode",
"data": null
}
Invalid Callback URL (400)
{
"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)
{
"code": -1,
"msg": "Database error adding address",
"data": null
}
Internal Server Error (500)
{
"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:
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)
{
"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
andupdated_at
Related Endpoints
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):
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):
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
// 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
:
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:
{
"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):
# 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