POST /apiv2/time/add

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

Endpoint URL

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

प्रमाणीकरण

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

अनुरोध Body

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 डेलिगेट होने और एड्रेस के लिए Host Mode बंद होने पर सूचित करने के लिए सार्वजनिक 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 को कॉल करने पर मिलता है। बिलिंग अलग कॉल के समान ही है: इस बिंदु पर कुछ भी शुल्क नहीं लिया जाता है, और जैसे ही energy डेलिगेट होती है, साइकिलों का शुल्क एक-एक करके लिया जाता है। देखें Host Mode → Cycles and Pricing।

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

आपका बैलेंस मौजूदा कीमत पर एक साइकिल को कवर नहीं करता है;
एड्रेस पहले से सक्रिय है;
एड्रेस पर पहले से ही एक खुला ऑर्डर है।

फ़्लैग के साथ और उसके बिना प्रतिक्रिया समान होती है — कोई अतिरिक्त फ़ील्ड नहीं, कोई अतिरिक्त त्रुटि कोड नहीं, और यह आपको यह नहीं बताती है कि 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 के साथ लौटाई जाती हैं — code की जांच करें, HTTP स्थिति की नहीं। त्रुटि बॉडी में हमेशा "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` फ़ील्ड नहीं है

गंतव्य एड्रेस की अनुमति नहीं है (403)

एड्रेस को जोड़ने से पहले उसकी जांच की जाती है। यदि इसमें संसाधन डेलिगेशन की अनुमति नहीं है, तो अनुरोध को HTTP 403 के साथ अस्वीकार कर दिया जाता है और कुछ भी नहीं लिखा जाता है — एड्रेस न तो जोड़ा जाता है और न ही चालू किया जाता है। बॉडी detail प्रारूप का उपयोग करती है:

code	msg	अर्थ
1006	`Address is blocked. Contact support.`	एड्रेस ब्लॉक है
1007	`Energy rental to smart contracts is not supported.`	एड्रेस एक स्मार्ट अनुबंध है (GasFree वॉलेट एड्रेस भी स्मार्ट अनुबंध होते हैं)
1010	`Resource delegation to this address is not available.`	इस एड्रेस पर डेलिगेशन उपलब्ध नहीं है
1011	`This address is frozen and cannot receive resource delegation.`	एड्रेस फ़्रीज़ है

json

{ "detail": { "code": 1007, "msg": "Energy rental to smart contracts is not supported." } }

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

यदि आपने एक callback_url पंजीकृत किया है, तो सिस्टम हर बार एड्रेस पर energy डेलिगेट होने पर (यानी संसाधित होने पर प्रति डेलिगेशन साइकिल एक बार) इसे कॉल करता है, और एड्रेस के लिए Host Mode बंद होने पर प्रत्येक बार एक बार — देखें होस्ट पॉज़ इवेंट।

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

सिस्टम क्वेरी पैरामीटर्स के साथ एक 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 को एक वैकल्पिक पैरामीटर के रूप में पढ़ें — एक गायब कुंजी का अर्थ है "मापने के लिए कोई ट्रांसफर नहीं", न कि कोई त्रुटि, और इसके लिए कभी भी डिफ़ॉल्ट मान न मानें।

होस्ट पॉज़ इवेंट

वही callback_url तब कॉल किया जाता है जब एड्रेस के लिए Host Mode बंद हो जाता है (निष्क्रिय हो जाता है), कारण चाहे जो भी हो:

GET https://your-server.com/webhook?event=host_paused&address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&reason=idle&paused_at=2026-09-13T11:16:58Z&balance=418.0000

पैरामीटर	विवरण
event	इस अधिसूचना के लिए हमेशा `host_paused`
address	वह TRON एड्रेस जिसका Host Mode बंद कर दिया गया था
reason	मोड क्यों बंद किया गया था — नीचे दी गई तालिका देखें
paused_at	मोड कब बंद किया गया था, ISO-8601 UTC
balance	उस समय TRX में आपका खाता शेष, 4 दशमलव

reason	अर्थ
`idle`	लगातार 2 निष्क्रिय दिन — बिना किसी ट्रांसफर के दो 24-घंटे के साइकिल बंद हुए (देखें Host Mode → Idle shutdown)
`cycles_exhausted`	सभी ऑर्डर किए गए साइकिल उपयोग कर लिए गए हैं
`no_balance`	आपका बैलेंस एक साइकिल या दैनिक न्यूनतम टॉप-अप चार्ज करने के लिए पर्याप्त नहीं था
`stopped`	मोड को `/apiv2/time/stop` के साथ रोक दिया गया था, या किसी अन्य कारण से बंद कर दिया गया था

दोनों नोटिफिकेशन्स में अंतर कैसे करें: केवल पॉज़ अधिसूचना में event पैरामीटर होता है; केवल डेलिगेशन अधिसूचना में order_id और hash होते हैं। डेलिगेशन अधिसूचना प्रारूप अपरिवर्तित है।

पॉज़ के बाद एड्रेस अपने कॉलबैक URL के साथ Host Mode में बना रहता है; इसे /apiv2/time/order या /apiv2/time/infinitystart के साथ फिर से चालू करें। डिलीवरी उसी तरह काम करती है जैसे डेलिगेशन नोटिफिकेशन्स के लिए करती है।

उदाहरण हैंडलर (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

    if request.args.get('event') == 'host_paused':
        # Host Mode switched off: reason = idle | cycles_exhausted | no_balance | stopped
        print(f"Host Mode paused: address={address} reason={request.args.get('reason')} "
              f"paused_at={request.args.get('paused_at')} balance={request.args.get('balance')}")
        return jsonify({"status": "success"}), 200

    # 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 नेटवर्क पर सक्रिय किया जाना चाहिए।
स्मार्ट अनुबंध — GasFree वॉलेट एड्रेस सहित — नहीं जोड़े जा सकते (HTTP 403, code 1007)।

POST /apiv2/time/add ​

Endpoint URL ​

प्रमाणीकरण ​

अनुरोध Body ​

पैरामीटर ​

व्यवहार ​

infinity ​

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

cURL ​

Python ​

Node.js ​

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

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

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

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

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

HTTP स्थिति कोड ​

गंतव्य एड्रेस की अनुमति नहीं है (403) ​

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

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

होस्ट पॉज़ इवेंट ​

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

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

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

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

नोट्स ​

POST /apiv2/time/add

Endpoint URL

प्रमाणीकरण

अनुरोध Body

पैरामीटर

व्यवहार

infinity

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

cURL

Python

Node.js

प्रतिक्रिया

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

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

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

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

HTTP स्थिति कोड

गंतव्य एड्रेस की अनुमति नहीं है (403)

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

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

होस्ट पॉज़ इवेंट

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

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

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

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

नोट्स