POST /apiv2/time/add

เพิ่มที่อยู่ TRON ไปยัง Host Mode และสามารถเลือกลงทะเบียน URL สำหรับ callback เพื่อรับการแจ้งเตือนการมอบหมาย (delegation) ได้

URL ของ Endpoint

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

การยืนยันตัวตน

ระบุ API key ของคุณในเนื้อหาคำขอ (api_key) หรือในส่วนหัว X-API-KEY โดย IP ของคำขอจะต้องอยู่ในไวท์ลิสต์ที่กำหนดค่าไว้สำหรับ API key ของคุณ

เนื้อหาคำขอ

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

พารามิเตอร์

พารามิเตอร์	ชนิด	จำเป็น	คำอธิบาย
api_key	string	ใช่*	API key สามารถส่งในส่วนหัว X-API-KEY ได้เช่นกัน
address	string	ใช่	ที่อยู่ TRON (TRC-20) ต้องตรงตามรูปแบบ ^T[1-9A-HJ-NP-Za-km-z]{33}$ (ขึ้นต้นด้วย T, ความยาว 34 อักขระ)
callback_url	string	ไม่	URL สาธารณะแบบ HTTP/HTTPS สำหรับแจ้งเตือนเมื่อมีการมอบหมาย Energy ไปยังที่อยู่ดังกล่าว ความยาวสูงสุด 2048 อักขระ
infinity	boolean	ไม่	true — เพื่อเปลี่ยนที่อยู่ไปยังโหมด infinity โดยตรงทันที ช่วยลดการเรียกคำขอแยกไปยัง /apiv2/time/infinitystart ค่าเริ่มต้นคือ false

* จำเป็นต้องมีในเนื้อหาคำขอ เว้นแต่จะใช้ส่วนหัว X-API-KEY

การตรวจสอบความถูกต้องของ callback_url: ต้องเป็น http/https, ต้องเป็นโฮสต์สาธารณะเท่านั้น (ปฏิเสธ localhost, ช่วงที่อยู่ส่วนบุคคลตาม RFC1918, link-local 169.254.0.0/16, ที่อยู่ IPv6 ส่วนบุคคล/link-local, ที่อยู่สงวนไว้ และมัลติแคสต์) และมีความยาวไม่เกิน 2048 อักขระ

พฤติกรรมการทำงาน

• หากที่อยู่ดังกล่าวเป็นที่อยู่ใหม่ จะถูกเพิ่มไปยัง Host Mode โดยมีสถานะ ไม่ใช้งาน (inactive) (status = 0, cycle_set = 0) สามารถเปิดใช้งานได้ในภายหลังด้วย /apiv2/time/order หรือ /apiv2/time/infinitystart
• หากมีที่อยู่นี้อยู่แล้วในบัญชีของคุณ การเรียกคำขอนี้จะทำการอัปเดต URL สำหรับ callback ของที่อยู่นั้น
• หากระบุ callback_url ค่าดังกล่าวจะถูกจัดเก็บ (หรืออัปเดต) สำหรับที่อยู่นั้น

infinity

เมื่อตั้งค่า "infinity": true ที่อยู่จะถูกเพิ่ม และ เปิดใช้งานในโหมด infinity ได้ในการเรียกคำขอเพียงครั้งเดียว — ซึ่งให้ผลลัพธ์เช่นเดียวกับการเรียก /apiv2/time/add แล้วตามด้วย /apiv2/time/infinitystart การคิดค่าบริการจะเหมือนกับการเรียกแยก: ไม่มีการเรียกเก็บเงินในขั้นตอนนี้ และจะคิดค่ารอบทีละรอบเมื่อมีการมอบหมาย Energy ดูข้อมูลเพิ่มเติมที่ Host Mode → รอบและราคา

การเพิ่มที่อยู่และการเปิดใช้งานโหมดเป็นสองขั้นตอนที่แยกจากกัน และรับประกันความสำเร็จเฉพาะขั้นตอนแรกเท่านั้น การตอบกลับจะรายงานผลของการเพิ่มที่อยู่ หากเพิ่มที่อยู่สำเร็จแต่ไม่สามารถเปิดใช้งานโหมดได้ คำขอยังคงส่งคืน code: 0 พร้อมข้อความตามปกติ — โดยที่อยู่จะยังคงอยู่ในสถานะไม่ใช้งาน เช่นเดียวกับกรณีที่คุณไม่ได้ส่งแฟล็กนี้มา การเปิดใช้งานจะถูกข้ามไปเมื่อ:

• ยอดคงเหลือของคุณไม่เพียงพอสำหรับหนึ่งรอบ ณ ราคาปัจจุบัน
• ที่อยู่ดังกล่าวเปิดใช้งานอยู่แล้ว
• ที่อยู่ดังกล่าวมีคำสั่งซื้อที่ยังเปิดอยู่แล้ว

การตอบกลับจะเหมือนกันทั้งกรณีที่มีและไม่มีแฟล็กนี้ — ไม่มีฟิลด์เพิ่มเติม ไม่มีรหัสข้อผิดพลาดเพิ่มเติม และจะไม่บอกว่าโหมด infinity ได้รับการเปิดใช้งานจริงหรือไม่ ยืนยันสถานะได้ด้วย สถานะเวลา: ที่อยู่จะรายงาน status: "active" และ mode: "infinity" พร้อมทั้งมี order id ปรากฏในการตอบกลับนั้น อย่าถือว่า code: 0 จาก endpoint นี้เป็นหลักฐานว่าโหมดกำลังทำงานอยู่

ตัวอย่างคำขอ

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
    # "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

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

การตอบกลับ

สำเร็จ (ที่อยู่ใหม่)

{
    "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 สำหรับ callback ของที่อยู่เดิมเรียบร้อยแล้ว)

{
    "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 สำหรับ callback ที่ลงทะเบียนไว้ (null หากไม่มี)
data.timestamp	string	การประทับเวลา ISO ของการดำเนินการ

การตอบกลับข้อผิดพลาด

ข้อผิดพลาดทั้งหมดจะใช้ code = -1 และอธิบายปัญหาไว้ใน msg:

msg	สาเหตุ
API key required in X-API-KEY header or request body	ไม่ได้ระบุ API key
Invalid API key or IP not in whitelist	การยืนยันตัวตนล้มเหลว
Invalid TRC-20 address format	รูปแบบที่อยู่ไม่ถูกต้องตามที่กำหนด
Invalid callback URL. Only public HTTP/HTTPS URLs are allowed	URL สำหรับ callback ไม่ผ่านการตรวจสอบความถูกต้อง
Address belongs to another user	ที่อยู่นี้ลงทะเบียนไว้กับบัญชีอื่นแล้ว
Database error adding/updating address	เกิดข้อผิดพลาดชั่วคราวที่ฝั่งเซิร์ฟเวอร์ — ให้ลองใหม่อีกครั้ง
Internal server error	เกิดข้อผิดพลาดที่ไม่คาดคิด — ให้ลองใหม่อีกครั้งหรือติดต่อฝ่ายสนับสนุน

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

รหัสสถานะ HTTP

ข้อผิดพลาดของ endpoint จะถูกส่งกลับมาพร้อมกับ HTTP 200 และค่า code ที่เป็นลบ — ให้ตรวจสอบที่ code ไม่ใช่สถานะ HTTP เนื้อหาข้อผิดพลาดจะมี "data": null รวมอยู่ด้วยเสมอ

ข้อผิดพลาดบางรายการจะถูกส่งกลับมาก่อนที่คำขอจะไปถึง endpoint โดยจะใช้สถานะที่ไม่ใช่ 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 key ถูกบล็อก — โปรดติดต่อฝ่ายสนับสนุน
422	{"detail": [ … ]}	เนื้อหาคำขอไม่ผ่านการตรวจสอบความถูกต้อง: ฟิลด์ที่จำเป็นขาดหายไปหรือมีชนิดข้อมูลไม่ถูกต้อง โปรดทราบว่าจะไม่มีฟิลด์ code ในการตอบกลับนี้

Callbacks (เว็บฮุก)

หากคุณได้ลงทะเบียน 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	แฮชธุรกรรมบนเชน (On-chain transaction hash) ของการมอบหมาย Energy
balance_after	ยอดคงเหลือในบัญชีของคุณในหน่วย TRX ทันทีหลังจากการหักค่าธรรมเนียมนี้ (สแนปช็อต ณ เวลาที่เรียกเก็บเงิน ซึ่งอาจมีการเปลี่ยนแปลงเมื่อ callback ไปถึง)
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 → รอบและราคา

ใช้ order_id และ hash เพื่อแยกความแตกต่างระหว่างการมอบหมายแต่ละรายการและใช้กระทบยอดกับบันทึกของคุณเอง — callback สองรายการสำหรับที่อยู่เดียวกันจะมีค่าเหล่านี้ต่างกัน ใช้ charged เพื่อติดตามค่าใช้จ่ายต่อรอบโดยไม่ต้องคอยเรียกดู /apiv2/time/status และใช้ energy_used เพื่อดูว่าการโอนก่อนหน้าอยู่ในอัตราค่าบริการใด ให้ประมวลผล energy_used ในฐานะพารามิเตอร์ที่ไม่บังคับ — คีย์ที่หายไปหมายถึง "ไม่มีการโอนให้วัดผล" ไม่ใช่ข้อผิดพลาด และห้ามตั้งค่าเริ่มต้นให้กับพารามิเตอร์นี้เด็ดขาด

ตัวอย่างการประมวลผล (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')
    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 ครั้งหากคำขอล้มเหลว หากล้มเหลวทั้งหมด callback จะถูกทิ้งไป (การมอบหมาย Energy จะยังคงเกิดขึ้นตามปกติ)
• ไม่มีลายเซ็น: คำขอไม่ได้ลงนามโดย Netts โดยข้อมูลลับ (หากมี) คือสิ่งที่คุณฝังไว้ใน callback_url ของคุณเอง
• การกระทบยอด: เนื่องจาก callback อาจสูญหายได้ จึงควรตรวจสอบผลด้วยการเรียกดู /apiv2/time/status ร่วมด้วย และเขียนฟังก์ชันจัดการของคุณให้เป็น idempotent

การอัปเดต / การลบ callback

• อัปเดต: เรียกคำขอ /apiv2/time/add อีกครั้งด้วยที่อยู่เดิมและ callback_url ใหม่
• ลบ: เรียกคำขอ /apiv2/time/delete เพื่อลบที่อยู่ (จะเป็นการลบ callback ออกด้วย) และเพิ่มที่อยู่อีกครั้งโดยไม่ระบุ callback_url หากต้องการ

Endpoint ที่เกี่ยวข้อง

• POST /apiv2/time/order — ซื้อรอบ (เปิดใช้งานที่อยู่)
• POST /apiv2/time/infinitystart — เปิดใช้งานโหมด infinity
• POST /apiv2/time/status — ตรวจสอบสถานะและรอบ
• POST /apiv2/time/stop — หยุดการทำงาน Host Mode
• POST /apiv2/time/delete — ลบที่อยู่

หมายเหตุ

• ที่อยู่ใหม่จะเริ่มต้นด้วยสถานะ ไม่ใช้งาน (inactive) เปิดใช้งานได้ด้วยการสร้างคำสั่งซื้อ, การเริ่มใช้งานโหมด infinity หรือส่งค่า "infinity": true ที่นี่
• ที่อยู่เดียวกันไม่สามารถลงทะเบียนภายใต้สองบัญชีที่แตกต่างกันได้
• ที่อยู่ควรได้รับการเปิดใช้งานบนเครือข่าย TRON ก่อนที่จะนำมาเพิ่มที่นี่