POST /apiv2/time/add

Add a TRON address to Host Mode and, optionally, register a callback URL for delegation notifications.

Endpoint URL

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

Authentication

Provide your API key in the request body (api_key) or the X-API-KEY header. The request IP must be in the whitelist configured for your API key.

Request Body

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

Parameters

Parameter	Type	Required	Description
api_key	string	Yes*	API key. Can also be sent in the X-API-KEY header.
address	string	Yes	TRON (TRC-20) address, must match ^T[1-9A-HJ-NP-Za-km-z]{33}$ (starts with T, 34 characters).
callback_url	string	No	Public HTTP/HTTPS URL to notify when energy is delegated to the address. Max 2048 characters.

* Required in the body unless the X-API-KEY header is used.

callback_url validation: must be http/https, a public host only (localhost, private RFC1918 ranges, link-local 169.254.0.0/16, IPv6 private/link-local, reserved and multicast addresses are rejected), and at most 2048 characters.

Behaviour

• If the address is new, it is added to Host Mode with status inactive (status = 0, cycle_set = 0). Activate it later with /apiv2/time/order or /apiv2/time/infinitystart.
• If the address already exists under your account, the call updates its callback URL.
• If callback_url is provided, it is stored (or updated) for that address.

Example Requests

cURL

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"
data = {
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook",  # optional
}

resp = requests.post(url, json=data, timeout=30)
result = resp.json()

if result["code"] == 0:
    print("Added:", result["data"]["address"])
else:
    print("Error:", result["msg"])

Node.js

const axios = require('axios');

const data = {
    api_key: 'YOUR_API_KEY_HERE',
    address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
    // callback_url: 'https://your-server.com/webhook', // optional
};

axios.post('https://netts.io/apiv2/time/add', data)
    .then(({ data: result }) => {
        if (result.code === 0) console.log('Added:', result.data.address);
        else console.error('Error:', result.msg);
    })
    .catch(err => console.error('Request failed:', err.response?.data || err.message));

Response

Success (new address)

{
    "code": 0,
    "msg": "Address added to Host Mode successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://your-server.com/webhook",
        "timestamp": "2026-07-13T05:30:15.123456"
    }
}

Success (callback URL updated for an existing address)

{
    "code": 0,
    "msg": "Address callback URL updated successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://new-webhook.com/endpoint",
        "timestamp": "2026-07-13T05:35:20.789012"
    }
}

Response Fields

Field	Type	Description
code	integer	0 = success, negative = error
msg	string	Human-readable message
data.address	string	The address that was added/updated
data.callback_url	string | null	The registered callback URL (null if none)
data.timestamp	string	ISO timestamp of the operation

Error Responses

All errors use code = -1 and describe the problem in msg:

msg	Cause
API key required in X-API-KEY header or request body	No API key provided
Invalid API key or IP not in whitelist	Authentication failed
Invalid TRC-20 address format	Address does not match the required format
Invalid callback URL. Only public HTTP/HTTPS URLs are allowed	Callback URL rejected by validation
Address belongs to another user	The address is registered under a different account
Database error adding/updating address	Temporary server-side error — retry
Internal server error	Unexpected error — retry or contact support

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

HTTP status codes

Endpoint errors are returned with HTTP 200 and a negative code — check code, not the HTTP status. Error bodies always include "data": null.

Some errors are returned before the request reaches the endpoint. They use a non-200 status and a different body shape:

HTTP	Body	Cause
402	{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}	Account balance is too low
403	{"detail": {"code": 1005, "msg": "API key is blocked. Contact support."}}	The API key is blocked — contact support
422	{"detail": [ … ]}	Request body failed validation: a required field is missing or has the wrong type. Note there is no code field in this response

Callbacks (webhooks)

If you registered a callback_url, the system calls it each time energy is delegated to the address (i.e. once per delegation cycle as it is processed).

Request format

The system sends an HTTP GET request with query parameters:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149936&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577

Parameter	Description
address	The TRON address that received the energy delegation
order_id	Delegation identifier (T + internal delegation id) — unique per delegation
hash	On-chain transaction hash of the energy delegation

Use order_id and hash to distinguish one delegation from another and to reconcile with your own records — two callbacks for the same address differ by these values.

Example 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')
    order_id = request.args.get('order_id')
    tx_hash = request.args.get('hash')

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

    # Your business logic (idempotent by order_id / hash)
    print(f"Energy delegated: address={address} order_id={order_id} hash={tx_hash}")
    return jsonify({"status": "success"}), 200

Delivery behaviour

• Method: GET, timeout ~10 seconds. Return HTTP 200 to acknowledge.
• Retries: up to 3 attempts are made if the request fails; if all fail, the callback is dropped (energy delegation still happens regardless).
• No signature: the request is not signed by Netts. The secret (if any) is whatever you embedded in your own callback_url.
• Reconciliation: because callbacks can be missed, also poll /apiv2/time/status and make your handler idempotent.

Updating / removing the callback

• Update: call /apiv2/time/add again with the same address and a new callback_url.
• Remove: call /apiv2/time/delete to remove the address (this also removes its callback); re-add without callback_url if needed.

Related Endpoints

• POST /apiv2/time/order — buy cycles (activates the address)
• POST /apiv2/time/infinitystart — enable infinity mode
• POST /apiv2/time/status — check status and cycles
• POST /apiv2/time/stop — stop Host Mode
• POST /apiv2/time/delete — remove the address

Notes

• New addresses start inactive; activate them with an order or infinity start.
• The same address cannot be registered under two different accounts.
• The address should be activated on the TRON network before adding it.