POST /apiv2/time/add

Host Mode में एक TRON एड्रेस जोड़ें और वैकल्पिक रूप से डेलिगेशन नोटिफ़िकेशन के लिए एक कॉलबैक URL पंजीकृत करें।

एंडपॉइंट URL

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

प्रमाणीकरण

अनुरोध बॉडी (api_key) या X-API-KEY हेडर में अपनी API कुंजी प्रदान करें। अनुरोध IP आपकी API कुंजी के लिए कॉन्फ़िगर की गई श्वेतसूची (whitelist) में होना चाहिए।

अनुरोध बॉडी

json

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

पैरामीटर

पैरामीटर	प्रकार	आवश्यक	विवरण
api_key	string	हाँ*	API कुंजी। इसे `X-API-KEY` हेडर में भी भेजा जा सकता है।
address	string	हाँ	TRON (TRC-20) एड्रेस, `^T[1-9A-HJ-NP-Za-km-z]{33}$` से मेल खाना चाहिए (`T` से शुरू, 34 वर्ण)।
callback_url	string	नहीं	एड्रेस पर Energy डेलिगेट होने पर सूचित करने के लिए सार्वजनिक HTTP/HTTPS URL। अधिकतम 2048 वर्ण।
infinity	boolean	नहीं	`true` — एड्रेस को सीधे infinity मोड में भी स्विच करें, जिससे `/apiv2/time/infinitystart` पर एक अलग कॉल करने की आवश्यकता नहीं होगी। डिफ़ॉल्ट `false` है।

* बॉडी में आवश्यक है जब तक कि X-API-KEY हेडर का उपयोग न किया गया हो।

callback_url सत्यापन: http/https होना चाहिए, केवल एक सार्वजनिक होस्ट (localhost, निजी RFC1918 रेंज, लिंक-लोकल 169.254.0.0/16, IPv6 निजी/लिंक-लोकल, आरक्षित और मल्टीकास्ट एड्रेस अस्वीकार किए जाते हैं), और अधिकतम 2048 वर्ण।

व्यवहार

यदि एड्रेस नया है, तो इसे inactive स्थिति (status = 0, cycle_set = 0) के साथ Host Mode में जोड़ा जाता है। इसे बाद में /apiv2/time/order या /apiv2/time/infinitystart के साथ सक्रिय करें।
यदि एड्रेस आपके खाते के तहत पहले से मौजूद है, तो यह कॉल उसके कॉलबैक URL को अपडेट करती है।
यदि callback_url प्रदान किया जाता है, तो यह उस एड्रेस के लिए संग्रहीत (या अपडेट) किया जाता है।

infinity

"infinity": true के साथ एड्रेस को एक ही कॉल में जोड़ा और infinity मोड में सक्रिय किया जाता है — यह परिणाम /apiv2/time/add और फिर /apiv2/time/infinitystart को कॉल करने के समान है। बिलिंग अलग कॉल के समान ही है: इस बिंदु पर कुछ भी शुल्क नहीं लिया जाता है, और चक्रों (cycles) का शुल्क एक-एक करके लिया जाता है जैसे ही Energy डेलिगेट की जाती है। देखें Host Mode → Cycles and Pricing।

एड्रेस जोड़ना और उसे चालू करना दो अलग-अलग चरण हैं, और केवल पहले चरण की गारंटी है। प्रतिक्रिया जोड़ने के परिणाम की रिपोर्ट करती है। यदि एड्रेस जोड़ दिया गया था लेकिन उसे चालू नहीं किया जा सका, तब भी कॉल सामान्य संदेश के साथ code: 0 लौटाती है — एड्रेस को बस निष्क्रिय छोड़ दिया जाता है, ठीक वैसे ही जैसे आपने यह फ़्लैग पास न किया हो। चालू करना छोड़ दिया जाता है जब:

आपका बैलेंस वर्तमान मूल्य पर एक चक्र (cycle) को कवर नहीं करता है;
एड्रेस पहले से ही सक्रिय है;
एड्रेस पर पहले से ही एक खुला ऑर्डर है।

फ़्लैग के साथ और फ़्लैग के बिना प्रतिक्रिया समान होती है — कोई अतिरिक्त फ़ील्ड नहीं, कोई अतिरिक्त त्रुटि कोड नहीं, और यह आपको यह नहीं बताता कि infinity मोड वास्तव में चालू किया गया था या नहीं। Time Status के साथ इसकी पुष्टि करें: एड्रेस status: "active" और mode: "infinity" की रिपोर्ट करता है, और ऑर्डर आईडी उस प्रतिक्रिया में होती है। इस एंडपॉइंट से code: 0 को इस बात का प्रमाण न मानें कि मोड चल रहा है।

उदाहरण अनुरोध

cURL

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://your-server.com/webhook"
  }'

Python

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
    # "infinity": True,  # optional: also switch the address into infinity mode
}

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

javascript

const axios = require('axios');

const data = {
    api_key: 'YOUR_API_KEY_HERE',
    address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
    // callback_url: 'https://your-server.com/webhook', // optional
    // infinity: true, // optional: also switch the address into infinity mode
};

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));

प्रतिक्रिया

सफलता (नया एड्रेस)

json

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

सफलता (किसी मौजूदा एड्रेस के लिए कॉलबैक URL अपडेट किया गया)

json

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

प्रतिक्रिया फ़ील्ड

फ़ील्ड	प्रकार	विवरण
code	integer	`0` = सफलता, ऋणात्मक = त्रुटि
msg	string	मानव-पठनीय संदेश
data.address	string	वह एड्रेस जिसे जोड़ा/अपडेट किया गया था
data.callback_url	string \| null	पंजीकृत कॉलबैक URL (यदि कोई नहीं है तो `null`)
data.timestamp	string	ऑपरेशन का ISO टाइमस्टैम्प

त्रुटि प्रतिक्रियाएँ

सभी त्रुटियाँ code = -1 का उपयोग करती हैं और समस्या का वर्णन msg में करती हैं:

msg	कारण
`API key required in X-API-KEY header or request body`	कोई API कुंजी प्रदान नहीं की गई
`Invalid API key or IP not in whitelist`	प्रमाणीकरण विफल रहा
`Invalid TRC-20 address format`	एड्रेस आवश्यक प्रारूप से मेल नहीं खाता है
`Invalid callback URL. Only public HTTP/HTTPS URLs are allowed`	कॉलबैक URL सत्यापन द्वारा अस्वीकार कर दिया गया
`Address belongs to another user`	एड्रेस किसी भिन्न खाते के तहत पंजीकृत है
`Database error adding/updating address`	अस्थायी सर्वर-साइड त्रुटि — पुनः प्रयास करें
`Internal server error`	अप्रत्याशित त्रुटि — पुनः प्रयास करें या सहायता से संपर्क करें

json

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

HTTP स्थिति कोड

एंडपॉइंट त्रुटियाँ HTTP 200 और एक ऋणात्मक code के साथ लौटाई जाती हैं — HTTP स्थिति के बजाय code की जाँच करें। त्रुटि बॉडी में हमेशा "data": null शामिल होता है।

कुछ त्रुटियाँ अनुरोध के एंडपॉइंट तक पहुँचने से पहले लौटा दी जाती हैं। वे गैर-200 स्थिति और एक भिन्न बॉडी संरचना का उपयोग करती हैं:

HTTP	बॉडी	कारण
402	`{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}`	खाता शेष बहुत कम है
403	`{"detail": {"code": 1005, "msg": "API key is blocked. Contact support."}}`	API कुंजी ब्लॉक है — सहायता से संपर्क करें
422	`{"detail": [ … ]}`	अनुरोध बॉडी सत्यापन विफल रहा: एक आवश्यक फ़ील्ड अनुपलब्ध है या उसका प्रकार गलत है। ध्यान दें कि इस प्रतिक्रिया में कोई `code` फ़ील्ड नहीं है

कॉलबैक (वेबहूक)

यदि आपने एक callback_url पंजीकृत किया है, तो सिस्टम हर बार एड्रेस पर Energy डेलिगेट होने पर इसे कॉल करता है (यानी प्रत्येक डेलिगेशन चक्र के संसाधित होने पर एक बार)।

अनुरोध प्रारूप

सिस्टम क्वेरी पैरामीटर के साथ एक HTTP GET अनुरोध भेजता है:

एक USDT ट्रांसफर से उत्पन्न चक्र — energy_used उपस्थित है:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149936&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=142.3500&idle_cycle=0&energy_used=65k&charged=2.0000

बिना किसी पूर्व ट्रांसफर वाला चक्र — energy_used छोड़ दिया गया:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149937&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=138.3500&idle_cycle=0&charged=4.0000

पैरामीटर	विवरण
address	TRON एड्रेस जिसे Energy डेलिगेशन प्राप्त हुआ
order_id	डेलिगेशन पहचानकर्ता (`T` + आंतरिक डेलिगेशन आईडी) — प्रत्येक डेलिगेशन के लिए अद्वितीय
hash	Energy डेलिगेशन का ऑन-चेन ट्रांज़ैक्शन हैश
balance_after	इस शुल्क के तुरंत बाद TRX में आपका खाता शेष (शुल्क समय का स्नैपशॉट; कॉलबैक आने के समय तक यह बदल सकता है)
idle_cycle	`1` — यह डेलिगेशन बिना किसी ट्रांसफर के 24 घंटे के बाद जारी किया गया था (आइडल पुनः डेलिगेशन), `0` — आपके ट्रांसफर या सक्रियण से उत्पन्न एक नियमित चक्र
energy_used	इस चक्र को उत्पन्न करने वाले ट्रांसफर द्वारा उपभोग की गई Energy का टैरिफ बैंड: `65k` (65,000 Energy या उससे कम → 2 TRX) या `131k` (65,000 से अधिक → 4 TRX)। वैकल्पिक — कुंजी को क्वेरी स्ट्रिंग से पूरी तरह से छोड़ दिया जाता है (खाली नहीं भेजा जाता) जब मापने के लिए कोई पूर्व ट्रांसफर नहीं था: सक्रियण का पहला डेलिगेशन, प्रत्येक आइडल पुनः डेलिगेशन, और बिना किसी उपभोग इतिहास वाला एड्रेस। उन सभी से 4 TRX की दर से शुल्क लिया जाता है
charged	इस चक्र के लिए लिया गया TRX में शुल्क — `2.0000` या `4.0000`, जो `energy_used` में टैरिफ से मेल खाता है। हमेशा उपस्थित रहता है, जिसमें तब भी शामिल है जब `energy_used` छोड़ दिया गया हो। देखें Host Mode → Cycles and Pricing

एक डेलिगेशन को दूसरे से अलग करने और अपने स्वयं के रिकॉर्ड के साथ मिलान करने के लिए order_id और hash का उपयोग करें — एक ही एड्रेस के लिए दो कॉलबैक इन मानों द्वारा भिन्न होते हैं। /apiv2/time/status को पोल किए बिना प्रति चक्र खर्च को ट्रैक करने के लिए charged का उपयोग करें, और यह देखने के लिए energy_used का उपयोग करें कि पिछला ट्रांसफर किस टैरिफ में आया था। energy_used को एक वैकल्पिक पैरामीटर के रूप में पढ़ें — एक अनुपलब्ध कुंजी का अर्थ है "मापने के लिए कोई ट्रांसफर नहीं", त्रुटि नहीं, और इसके लिए कभी भी डिफ़ॉल्ट मान न मानें।

उदाहरण हैंडलर (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')
    order_id = request.args.get('order_id')
    tx_hash = request.args.get('hash')
    charged = request.args.get('charged')          # TRX charged for this cycle
    energy_used = request.args.get('energy_used')  # '65k' | '131k' | None (key may be absent)

    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} "
          f"charged={charged} energy_used={energy_used}")
    return jsonify({"status": "success"}), 200

डिलीवरी व्यवहार

विधि: GET, टाइमआउट ~10 सेकंड। पावती (स्वीकृति) देने के लिए HTTP 200 लौटाएं।
पुनः प्रयास: यदि अनुरोध विफल रहता है तो अधिकतम 3 प्रयास किए जाते हैं; यदि सभी विफल हो जाते हैं, तो कॉलबैक छोड़ दिया जाता है (Energy डेलिगेशन इसके बावजूद होता है)।
कोई हस्ताक्षर नहीं: अनुरोध Netts द्वारा हस्ताक्षरित नहीं है। गुप्त कुंजी (यदि कोई हो) वही है जो आपने अपने callback_url में एम्बेड की है।
समाधान (Reconciliation): चूँकि कॉलबैक छूट सकते हैं, इसलिए /apiv2/time/status को भी पोल करें और अपने हैंडलर को आइडम्पोटेंट बनाएं।

कॉलबैक को अपडेट / हटाना

अपडेट करें: उसी एड्रेस और एक नए callback_url के साथ फिर से /apiv2/time/add को कॉल करें।
हटाएं: एड्रेस को हटाने के लिए /apiv2/time/delete को कॉल करें (यह इसके कॉलबैक को भी हटा देता है); यदि आवश्यक हो तो बिना callback_url के फिर से जोड़ें।

नोट्स

नए एड्रेस inactive शुरू होते हैं; उन्हें एक ऑर्डर के साथ, infinity शुरू करके, या यहाँ "infinity": true पास करके सक्रिय करें।
एक ही एड्रेस को दो अलग-अलग खातों के तहत पंजीकृत नहीं किया जा सकता है।
एड्रेस को जोड़ने से पहले TRON नेटवर्क पर सक्रिय किया जाना चाहिए।

POST /apiv2/time/add ​

एंडपॉइंट URL ​

प्रमाणीकरण ​

अनुरोध बॉडी ​

पैरामीटर ​

व्यवहार ​

infinity ​

उदाहरण अनुरोध ​

cURL ​

Python ​

Node.js ​

प्रतिक्रिया ​

सफलता (नया एड्रेस) ​

सफलता (किसी मौजूदा एड्रेस के लिए कॉलबैक URL अपडेट किया गया) ​

प्रतिक्रिया फ़ील्ड ​

त्रुटि प्रतिक्रियाएँ ​

HTTP स्थिति कोड ​

कॉलबैक (वेबहूक) ​

अनुरोध प्रारूप ​

उदाहरण हैंडलर (Python / Flask) ​

डिलीवरी व्यवहार ​

कॉलबैक को अपडेट / हटाना ​

संबंधित एंडपॉइंट ​

नोट्स ​

POST /apiv2/time/add

एंडपॉइंट URL

प्रमाणीकरण

अनुरोध बॉडी

पैरामीटर

व्यवहार

infinity

उदाहरण अनुरोध

cURL

Python

Node.js

प्रतिक्रिया

सफलता (नया एड्रेस)

सफलता (किसी मौजूदा एड्रेस के लिए कॉलबैक URL अपडेट किया गया)

प्रतिक्रिया फ़ील्ड

त्रुटि प्रतिक्रियाएँ

HTTP स्थिति कोड

कॉलबैक (वेबहूक)

अनुरोध प्रारूप

उदाहरण हैंडलर (Python / Flask)

डिलीवरी व्यवहार

कॉलबैक को अपडेट / हटाना

संबंधित एंडपॉइंट

नोट्स