POST /apiv2/time/add

Host Mode'a bir TRON adresi ekleyin ve isteğe bağlı olarak yetkilendirme ve duraklatma 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 yapılan IP adresi, 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 enerji delege edildiğinde ve adres için Host Mode kapatıldığında bildirilecek genel HTTP/HTTPS URL'si. Maksimum 2048 karakter.
infinity	boolean	Hayır	`true` — adresi doğrudan sonsuz (infinity) moda geçirir ve `/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 herkese açık (public) bir ana bilgisayar olmalı (localhost, özel RFC1918 aralıkları, link-local 169.254.0.0/16, IPv6 özel/link-local, ayrılmış ve çok noktaya yayın (multicast) adresleri reddedilir) ve en fazla 2048 karakter olmalıdır.

Davranış

Adres yeniyse, Host Mode'a etkin değil (status = 0, cycle_set = 0) durumuyla 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, bu adres için saklanır (veya güncellenir).

infinity

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

Adresi eklemek ve modu açmak iki ayrı adımdır ve yalnızca ilki garanti edilir. Yanıt, ekleme işleminin sonucunu bildirir. Adres eklenmiş ancak modu açılamamışsa, çağrı yine de her zamanki mesajla birlikte code: 0 döner — adres, tıpkı bayrağı iletmemişsiniz gibi etkin olmayan durumda bırakılır. Aşağıdaki durumlarda modun açılması 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 olsun veya olmasın aynıdır — fazladan alan veya fazladan hata kodu içermez ve sonsuz modun gerçekten açılıp açılmadığını size bildirmez. Bunu Time Status ile doğrulayın: adres status: "active" ve mode: "infinity" raporlar ve sipariş kimliği bu yanıtta yer alır. Bu uç noktadan dönen code: 0 değerini modun çalıştığının bir kanıtı olarak değerlendirmeyin.

Ö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	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
`Invalid TRC-20 address format`	Adres gerekli formatla 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 tarafı hatası — 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

Hedef adrese izin verilmiyor (403)

Adres eklenmeden önce kontrol edilir. Adrese kaynak yetkilendirmesine izin verilmiyorsa, istek HTTP 403 ile reddedilir ve hiçbir şey yazılmaz — adres eklenmez ve açılmaz. Gövde detail yapısını kullanır:

code	msg	Anlamı
1006	`Address is blocked. Contact support.`	Adres engellendi
1007	`Energy rental to smart contracts is not supported.`	Adres bir akıllı sözleşmedir (GasFree cüzdan adresleri de akıllı sözleşmelerdir)
1010	`Resource delegation to this address is not available.`	Bu adrese kaynak yetkilendirmesi kullanılamıyor
1011	`This address is frozen and cannot receive resource delegation.`	Adres dondurulmuş ve kaynak yetkilendirmesi alamaz

json

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

Geri Çağırmalar (webhook'lar)

Bir callback_url kaydettiyseniz, sisteme her Energy delege edildiğinde (yani işlendikçe yetkilendirme döngüsü başına bir kez) ve adres için Host Mode her kapatıldığında sistem bu URL'yi çağırır — bkz. Host duraklatıldı olayı.

İstek formatı

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

USDT transferinden doğan bir 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 edilmez:

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 yetkilendirmesini alan TRON adresi
order_id	Yetkilendirme tanımlayıcısı (`T` + dahili yetkilendirme kimliği) — her yetkilendirme için benzersizdir
hash	Energy yetkilendirmesinin zincir üstü (on-chain) işlem karması (hash)
balance_after	Bu ücretlendirmeden hemen sonra 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 yetkilendirme transfer yapılmayan 24 saatten sonra verildi (boşta yeniden yetkilendirme), `0` — transferinizden veya etkinleştirmenizden doğan düzenli bir döngü
energy_used	Bu döngüyü üreten transfer tarafından tüketilen enerjinin tarife kademesi: `65k` (65.000 veya daha az enerji → 2 TRX) veya `131k` (65.000'den fazla → 4 TRX). İsteğe bağlı — ölçülecek bir önceki transfer olmadığında anahtar sorgu dizesinden tamamen çıkarılır (boş gönderilmez): bir etkinleştirmenin ilk yetkilendirmesi, her boşta yeniden yetkilendirme ve henüz tüketim geçmişi olmayan bir adres. Bunların tümü 4 TRX tarifesinden ü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` dahil edilmediğinde de her zaman mevcuttur. Bkz. Host Mode → Döngüler ve Fiyatlandırma

Bir yetkilendirmeyi 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 iki geri çağırma bu değerlerle farklılık gösterir. /apiv2/time/status uç noktasını sürekli yoklamadan döngü başına harcamayı takip etmek için charged ve önceki transferin hangi tarifeye girdiğini görmek için energy_used parametrelerini 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.

Host duraklatıldı olayı

Nedeni ne olursa olsun, adres için Host Mode her kapandığında (etkin değil durumuna geçtiğinde) aynı callback_url çağrılır:

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

Parametre	Açıklama
event	Bu bildirim için her zaman `host_paused`
address	Host Mode'u kapatılan TRON adresi
reason	Modun neden kapatıldığı — aşağıdaki tabloya bakın
paused_at	Modun ne zaman kapatıldığı, ISO-8601 UTC
balance	O andaki TRX cinsinden hesap bakiyeniz, 4 ondalık basamak

reason	Anlamı
`idle`	Üst üste 2 boşta gün — transfer olmadan kapanan iki 24 saatlik döngü (bkz. Host Mode → Boşta kalma nedeniyle kapatma)
`cycles_exhausted`	Sipariş edilen tüm döngüler kullanıldı
`no_balance`	Bakiyeniz bir döngüyü veya günlük minimum yüklemeyi ücretlendirmek için yeterli değildi
`stopped`	Mod `/apiv2/time/stop` ile durduruldu veya başka bir nedenle kapatıldı

İki bildirimi birbirinden nasıl ayırt edebilirsiniz: Yalnızca duraklatma bildiriminde event parametresi bulunur; yalnızca yetkilendirme bildiriminde order_id ve hash bulunur. Yetkilendirme bildirimi formatı değişmemiştir.

Duraklatmanın ardından adres, geri çağırma URL'si ile birlikte Host Mode'da kalır; adresi /apiv2/time/order veya /apiv2/time/infinitystart ile tekrar açabilirsiniz. İletim, yetkilendirme bildirimleriyle aynı şekilde çalışır.

Ö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

    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

İletim davranışı

Yöntem: GET, zaman aşımı ~10 saniye. Onaylamak için HTTP 200 döndürün.
Yeniden denemeler: İstek 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 (buna bakılmaksızın Energy yetkilendirmesi yine de gerçekleşir).
İmza yok: İstek NETTS tarafından imzalanmaz. Gizli anahtar (varsa), kendi callback_url adresinize yerleştirdiğiniz değerdir.
Mutabakat: Geri çağırmalar atlanabileceğinden, /apiv2/time/status uç noktasını da sorgulayın ve işleyicinizi birimkuvvet (idempotent) yapı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 — sonsuz modu 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 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ına kaydedilemez.
Adres eklenmeden önce TRON ağında etkinleştirilmelidir.
Akıllı sözleşmeler — GasFree cüzdan adresleri dahil — eklenemez (HTTP 403, code 1007).

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ı ​

Hedef adrese izin verilmiyor (403) ​

Geri Çağırmalar (webhook'lar) ​

İstek formatı ​

Host duraklatıldı olayı ​

Örnek işleyici (Python / Flask) ​

İletim 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ı

Hedef adrese izin verilmiyor (403)

Geri Çağırmalar (webhook'lar)

İstek formatı

Host duraklatıldı olayı

Örnek işleyici (Python / Flask)

İletim davranışı

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

İlgili Uç Noktalar

Notlar