POST /apiv2/time/add

Host Mode'a bir TRON adresi ekleyin ve isteğe bağlı olarak delegasyon bildirimleri için bir geri çağırma (callback) URL'si kaydedin.

Uç Nokta URL'si

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

Kimlik Doğrulama

API anahtarınızı istek gövdesinde (api_key) veya X-API-KEY başlığında sağlayın. İstek IP'si, API anahtarınız için yapılandırılmış beyaz listede (whitelist) yer almalıdır.

İstek Gövdesi

json

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

Parametreler

Parametre	Tür	Gerekli	Açıklama
api_key	string	Evet*	API anahtarı. `X-API-KEY` başlığında da gönderilebilir.
address	string	Evet	TRON (TRC-20) adresi, `^T[1-9A-HJ-NP-Za-km-z]{33}$` ile eşleşmelidir (`T` ile başlar, 34 karakter).
callback_url	string	Hayır	Adrese energy delege edildiğinde bildirim yapılacak genel HTTP/HTTPS URL'si. Maksimum 2048 karakter.
infinity	boolean	Hayır	`true` — adresi doğrudan infinity moduna geçirerek `/apiv2/time/infinitystart` için ayrı bir çağrı yapma ihtiyacını ortadan kaldırır. Varsayılan değer: `false`.

* X-API-KEY başlığı kullanılmadığı sürece gövdede zorunludur.

callback_url doğrulaması: http/https olmalı, yalnızca genel bir ana makine içermeli (localhost, özel RFC1918 aralıkları, link-local 169.254.0.0/16, IPv6 özel/link-local, ayrılmış ve multicast adresleri reddedilir) ve en fazla 2048 karakter olmalıdır.

Davranış

Adres yeniyse, Host Mode'a inactive (etkin değil) durumuyla (status = 0, cycle_set = 0) eklenir. Daha sonra /apiv2/time/order veya /apiv2/time/infinitystart ile etkinleştirin.
Adres hesabınız altında zaten mevcutsa, çağrı adresin geri çağırma URL'sini günceller.
callback_url sağlanmışsa, söz konusu adres için saklanır (veya güncellenir).

infinity

"infinity": true ile adres tek bir çağrıda eklenir ve infinity modunda etkinleştirilir — bu, önce /apiv2/time/add ve ardından /apiv2/time/infinitystart çağrısı yapmakla aynı sonucu verir. Faturalandırma ayrı çağrıyla tamamen aynıdır: bu aşamada hiçbir ücret alınmaz ve energy delege edildikçe döngüler teker teker ücretlendirilir. Bkz. Host Mode → Döngüler ve Fiyatlandırma.

Adresin eklenmesi ve açılması iki ayrı adımdır ve yalnızca ilki garanti edilir. Yanıt, ekleme işleminin sonucunu bildirir. Adres eklendiği halde açılamadıysa, çağrı yine de her zamanki mesajla birlikte code: 0 döner — adres, tıpkı bayrağı iletmemişsiniz gibi, yalnızca etkin olmayan durumda bırakılır. Aşağıdaki durumlarda açma işlemi atlanır:

bakiyeniz geçerli fiyattan bir döngüyü karşılamadığında;
adres zaten etkin olduğunda;
adresin zaten açık bir siparişi olduğunda.

Yanıt, bayrak olsa da olmasa da aynıdır — fazladan alan veya fazladan hata kodu bulunmaz ve infinity modunun gerçekten açılıp açılmadığını size bildirmez. Bunu Time Status ile onaylayın: adres status: "active" ve mode: "infinity" raporlar ve sipariş kimliği bu yanıtta yer alır. Bu uç noktadan gelen code: 0 sonucunu modun çalıştığının kanıtı olarak kabul etmeyin.

Örnek İstekler

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

Yanıt

Başarılı (yeni adres)

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

Başarılı (mevcut bir adres için geri çağırma URL'si güncellendi)

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

Yanıt Alanları

Alan	Tür	Açıklama
code	integer	`0` = başarılı, negatif = hata
msg	string	İnsan tarafından okunabilir mesaj
data.address	string	Eklenen/güncellenen adres
data.callback_url	string \| null	Kayıtlı geri çağırma URL'si (yoksa `null`)
data.timestamp	string	İşlemin ISO zaman damgası

Hata Yanıtları

Tüm hatalar code = -1 kullanır ve sorunu msg içinde açıklar:

msg	Neden
`API key required in X-API-KEY header or request body`	API anahtarı sağlanmadı
`Invalid API key or IP not in whitelist`	Kimlik doğrulama başarısız oldu
`Invalid TRC-20 address format`	Adres gerekli biçimle eşleşmiyor
`Invalid callback URL. Only public HTTP/HTTPS URLs are allowed`	Geri çağırma URL'si doğrulama tarafından reddedildi
`Address belongs to another user`	Adres farklı bir hesap altında kayıtlı
`Database error adding/updating address`	Geçici sunucu taraflı hata — tekrar deneyin
`Internal server error`	Beklenmeyen hata — tekrar deneyin veya destekle iletişime geçin

json

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

HTTP durum kodları

Uç nokta hataları HTTP 200 ve negatif bir code ile döndürülür — HTTP durumunu değil, code değerini kontrol edin. Hata gövdeleri her zaman "data": null içerir.

Bazı hatalar, istek uç noktaya ulaşmadan önce döndürülür. Bunlar 200 dışı bir durum ve farklı bir gövde yapısı kullanır:

HTTP	Gövde	Neden
402	`{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}`	Hesap bakiyesi çok düşük
403	`{"detail": {"code": 1005, "msg": "API key is blocked. Contact support."}}`	API anahtarı engellendi — destekle iletişime geçin
422	`{"detail": [ … ]}`	İstek gövdesi doğrulamadan geçemedi: zorunlu bir alan eksik veya yanlış türde. Bu yanıtta `code` alanı bulunmadığına dikkat edin

Geri Çağırmalar (webhooks)

Bir callback_url kaydettiyseniz, sisteme adrese her energy delege edildiğinde (yani işlendikçe her delegasyon döngüsü başına bir kez) bu URL'yi çağırır.

İstek biçimi

Sistem sorgu parametreleriyle bir HTTP GET isteği gönderir:

Bir USDT transferinden doğan döngü — energy_used mevcut:

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

Öncesinde transfer olmayan bir döngü — energy_used dahil edilmemiştir:

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

Parametre	Açıklama
address	Energy delegasyonunu alan TRON adresi
order_id	Delegasyon tanımlayıcısı (`T` + dahili delegasyon kimliği) — delegasyon başına benzersizdir
hash	Energy delegasyonunun zincir üzerindeki işlem özeti (hash)
balance_after	Bu tahsilatın hemen ardından TRX cinsinden hesap bakiyeniz (ücretlendirme anındaki anlık görüntü; geri çağırma ulaştığı anda değişmiş olabilir)
idle_cycle	`1` — bu delegasyon transfer olmaksızın geçen 24 saatin ardından verildi (boşta yeniden delegasyon), `0` — transferinizden veya etkinleştirmenizden doğan düzenli bir döngü
energy_used	Bu döngüyü üreten transferin tükettiği energy miktarının tarife kademesi: `65k` (65.000 energy veya daha az → 2 TRX) veya `131k` (65.000'den fazla → 4 TRX). İsteğe bağlıdır — ölçülecek bir önceki transfer bulunmadığında anahtar sorgu dizesinden tamamen çıkarılır (boş gönderilmez): bir etkinleştirmenin ilk delegasyonu, her boşta yeniden delegasyon ve henüz tüketim geçmişi olmayan bir adres. Bunların tümü 4 TRX oranından ücretlendirilir
charged	Bu döngü için tahsil edilen TRX tutarı — `energy_used` içindeki tarifeyle eşleşen `2.0000` veya `4.0000`. `energy_used` hariç tutulduğu durumlar da dahil olmak üzere her zaman mevcuttur. Bkz. Host Mode → Döngüler ve Fiyatlandırma

Bir delegasyonu diğerinden ayırt etmek ve kendi kayıtlarınızla mutabakat sağlamak için order_id ve hash kullanın — aynı adres için yapılan iki geri çağırma bu değerlerle farklılık gösterir. /apiv2/time/status uç noktasını sürekli sorgulamadan döngü başına harcamayı izlemek için charged, önceki transferin hangi tarifeye girdiğini görmek için energy_used kullanın. energy_used parametresini isteğe bağlı bir parametre olarak değerlendirin — eksik bir anahtar bir hata değil, "ölçülecek transfer yok" anlamına gelir ve bunun için asla varsayılan bir değer varsaymayın.

Örnek işleyici (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

Teslimat davranışı

Yöntem: GET, zaman aşımı ~10 saniye. Onaylamak için HTTP 200 döndürün.
Yeniden denemeler: istek başarısız olursa en fazla 3 deneme yapılır; tümü başarısız olursa geri çağırma bırakılır (energy delegasyonu bundan bağımsız olarak yine de gerçekleşir).
İmza yok: istek Netts tarafından imzalanmaz. Varsa gizli anahtar (secret), kendi callback_url adresinize yerleştirdiğiniz değerdir.
Mutabakat: geri çağırmalar kaçırılabileceğinden, /apiv2/time/status uç noktasını da sorgulayın ve işleyicinizi tekil işlem (idempotent) yapacak şekilde tasarlayın.

Geri çağırmayı güncelleme / kaldırma

Güncelleme: aynı adres ve yeni bir callback_url ile /apiv2/time/add uç noktasını tekrar çağırın.
Kaldırma: adresi kaldırmak için /apiv2/time/delete çağrısı yapın (bu işlem geri çağırmasını da kaldırır); gerekirse callback_url olmadan yeniden ekleyin.

İlgili Uç Noktalar

POST /apiv2/time/order — döngü satın al (adresi etkinleştirir)
POST /apiv2/time/infinitystart — infinity modunu etkinleştir
POST /apiv2/time/status — durumu ve döngüleri kontrol et
POST /apiv2/time/stop — Host Mode'u durdur
POST /apiv2/time/delete — adresi kaldır

Notlar

Yeni adresler inactive (etkin değil) olarak başlar; bunları bir siparişle, infinity start ile veya burada "infinity": true ileterek etkinleştirin.
Aynı adres iki farklı hesap altında kaydedilemez.
Adres eklenmeden önce TRON ağında etkinleştirilmiş olmalıdır.

POST /apiv2/time/add ​

Uç Nokta URL'si ​

Kimlik Doğrulama ​

İstek Gövdesi ​

Parametreler ​

Davranış ​

infinity ​

Örnek İstekler ​

cURL ​

Python ​

Node.js ​

Yanıt ​

Başarılı (yeni adres) ​

Başarılı (mevcut bir adres için geri çağırma URL'si güncellendi) ​

Yanıt Alanları ​

Hata Yanıtları ​

HTTP durum kodları ​

Geri Çağırmalar (webhooks) ​

İstek biçimi ​

Örnek işleyici (Python / Flask) ​

Teslimat davranışı ​

Geri çağırmayı güncelleme / kaldırma ​

İlgili Uç Noktalar ​

Notlar ​

POST /apiv2/time/add

Uç Nokta URL'si

Kimlik Doğrulama

İstek Gövdesi

Parametreler

Davranış

infinity

Örnek İstekler

cURL

Python

Node.js

Yanıt

Başarılı (yeni adres)

Başarılı (mevcut bir adres için geri çağırma URL'si güncellendi)

Yanıt Alanları

Hata Yanıtları

HTTP durum kodları

Geri Çağırmalar (webhooks)

İstek biçimi

Örnek işleyici (Python / Flask)

Teslimat davranışı

Geri çağırmayı güncelleme / kaldırma

İlgili Uç Noktalar

Notlar