POST /apiv2/usdt/analyze

TRON USDT ٹرانسفر لاگت کا حساب لگائیں (پرائیویٹ اینڈ پوائنٹ — تصدیق شدہ)۔

بالکل وہی TransferAnalysis پے لوڈ واپس کرتا ہے جو پبلک GET ویرینٹ کا ہے، لیکن بہت زیادہ ریٹ لمیٹ کے ساتھ (1 فی سیکنڈ کے بجائے 50 درخواستیں فی سیکنڈ فی Kong نوڈ) اور درخواست کا ڈیٹا URL کے بجائے JSON باڈی میں پاس کیا جاتا ہے۔ پروڈکشن کے کسی بھی انٹیگریشن کے لیے یہ اینڈ پوائنٹ استعمال کریں۔

اینڈ پوائنٹ URL

POST https://netts.io/apiv2/usdt/analyze

تصدیق (Authentication)

درج ذیل دو ہیڈرز میں سے کوئی بھی قبول کیا جاتا ہے (دونوں ایک ساتھ سپورٹڈ ہیں؛ X-API-KEY کو ترجیح دی جاتی ہے کیونکہ یہ باقی کے Netts /apiv2/* API سرفیس سے مطابقت رکھتا ہے):

ہیڈر	درکار	تفصیل
`Content-Type`	ہاں	`application/json` ہونا ضروری ہے۔
`X-API-KEY`	ترجیحی	آپ کی Netts API کلید — بالکل وہی فارمیٹ جو `/apiv2/order1h` اور دیگر تصدیق شدہ Netts اینڈ پوائنٹس کے لیے استعمال ہوتا ہے۔
`Authorization`	ایک متبادل کے طور پر قبول	`Bearer {key}` یا صرف `{key}` (بغیر کسی سابقے کے)۔ اگر آپ کا HTTP کلائنٹ بلٹ اِن bearer/auth کا فلو رکھتا ہے تو اسے استعمال کریں۔

اگر دونوں ہیڈرز بھیجے جائیں تو X-API-KEY کو فوقیت حاصل ہوگی۔

IP وائٹ لسٹ: وہ IP جس سے درخواست ہمارے ایج تک پہنچتی ہے، آپ کی API کلید کے لیے کنفیگر کردہ وائٹ لسٹ میں شامل ہونی چاہیے (وہی طریقہ کار جو دیگر /apiv2/* اینڈ پوائنٹس کے لیے ہے)۔ غیر وائٹ لسٹڈ IP سے آنے والی درخواستیں 401 Unauthorized کے ساتھ "Invalid API key or IP not in whitelist" واپس کرتی ہیں۔

اپنے order1h ہیڈرز کا دوبارہ استعمال

اگر آپ پہلے سے ہی X-API-KEY: {key} کے ساتھ /apiv2/order1h کو کال کر رہے ہیں، تو آپ بالکل وہی X-API-KEY ہیڈر /apiv2/usdt/analyze پر بھیج سکتے ہیں — کیلکولیٹر اب اسے بنیادی تصدیقی ہیڈر کے طور پر پہچانتا ہے۔

درخواست کی باڈی (Request body)

json

{
    "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
    "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"
}

فیلڈز

فیلڈ	قسم	درکار	شرائط
`sender_address`	string	ہاں	درست TRON ایڈریس — 34 حروف، `T` سے شروع ہوتا ہے، درست base58 چیک سم۔
`receiver_address`	string	ہاں	درست TRON ایڈریس؛ لازماً مختلف ہونا چاہیے `sender_address` سے۔

TIP

کوئی amount فیلڈ موجود نہیں ہے۔ کیلکولیٹر دونوں ایڈریسز کے درمیان ایک ہی USDT ٹرانسفر کے لیے لاگت اور وسائل کی ضروریات واپس کرتا ہے؛ اگر آپ کو کسی مخصوص USDT رقم کے لیے تفصیل درکار ہے تو اپنی جانب سے تجویز کردہ Energy کو ٹرانسفر کی تعداد سے ضرب دیں — ایک سنگل TRC-20 USDT ٹرانسفر رقم سے قطع نظر وہی تقریباً 130k Energy خرچ کرتا ہے۔

درخواست کی مثالیں

cURL (ترجیحی — `X-API-KEY`)

bash

curl -X POST "https://netts.io/apiv2/usdt/analyze" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
        "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
        "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"
      }'

cURL (متبادل — `Authorization`)

bash

curl -X POST "https://netts.io/apiv2/usdt/analyze" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
        "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
        "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"
      }'

Python

python

import requests

API_KEY = "YOUR_API_KEY"

payload = {
    "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
    "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL",
}

r = requests.post(
    "https://netts.io/apiv2/usdt/analyze",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY":    API_KEY,           # preferred; same header as /apiv2/order1h
        # or, equivalently:
        # "Authorization": f"Bearer {API_KEY}",
    },
    json=payload,
    timeout=15,
)

if r.status_code == 200:
    data = r.json()["data"]
    print("Energy needed:", data["requirements"]["energy_with_buffer"])
    print("Total cost:   ", data["costs"]["total_cost_trx"], "TRX")
    print("Method:       ", data["costs"]["recommended_method"])
elif r.status_code == 401:
    print("Auth failed:", r.json())
elif r.status_code == 429:
    print("Rate-limited — Retry-After:", r.headers.get("Retry-After"))
else:
    print("Error:", r.status_code, r.json())

جواب (Response)

کامیابی (200 OK)

پبلک اینڈ پوائنٹ جیسا ہی ہو بہو لفافہ:

json

{
    "status": "success",
    "data": { /* TransferAnalysis — see the public-endpoint page */ },
    "current_utc_time": "2026-04-23 11:54:13",
    "processing_time_ms": 20.14
}

data کی مکمل فیلڈ بہ فیلڈ تفصیل پبلک اینڈ پوائنٹ کے صفحے پر موجود ہے — دیکھیں TransferAnalysis، AddressInfo، Requirements اور Costs۔

خرابیاں (Errors)

جانچ پڑتال کی ترتیب

تصدیق کی جانچ باڈی کی توثیق سے پہلے کی جاتی ہے۔ اگر Authorization ہیڈر غائب/غلط ہے یا آپ کی IP وائٹ لسٹ میں شامل نہیں ہے، تو آپ کو ہمیشہ401 نظر آئے گا — چاہے JSON باڈی بھی خراب کیوں نہ ہو۔ پہلے تصدیق کو درست کریں، پھر درست کلید کے ساتھ دوبارہ ٹیسٹ کریں؛ صرف تبھی Pydantic کی باڈی توثیقی خرابیاں (422) سامنے آئیں گی۔

HTTP	باڈی	کب
401	`{"code": -1, "msg": "API key not provided (expected X-API-KEY or Authorization header)"}`	نہ تو `X-API-KEY` اور نہ ہی `Authorization` ہیڈر موجود ہے۔
401	`{"code": -1, "msg": "Invalid API key or IP not in whitelist"}`	نامعلوم کلید، یا درخواست کی IP آپ کی وائٹ لسٹ میں نہیں ہے۔
404	`{"code": -1, "msg": "User not found"}`	کلید درست ہے لیکن صارف کا ریکارڈ نہیں ملا (شاذ و نادر)۔
422	`{"detail": [{"loc": ["body","sender_address"], "msg": "Invalid TRON address length", "type": "value_error"}]}`	FastAPI/Pydantic کی باڈی توثیق ناکام ہوگئی۔ سٹیٹس `422 Unprocessable Entity` ہے، `400` نہیں۔
422	`{"detail": [{..., "msg": "Sender and receiver cannot be the same address", "type": "value_error"}]}`	`sender_address == receiver_address`۔
429	`{"message": "API rate limit exceeded"}`	Kong نوڈ پر مسلسل ٹریفک `50 req/sec` سے تجاوز کر گئی۔
500	`{"code": -1, "msg": "Internal server error"}`	سرور کی جانب سے غیر متوقع خرابی۔

ریٹ لمیٹ (Rate limit)

50 درخواستیں / سیکنڈ فی Kong نوڈ (limit_by = ip، پالیسی local)۔
minute / hour کی حدود متعین نہیں ہیں — صرف فی سیکنڈ کی حد لاگو ہوتی ہے۔
ہر جواب کے ساتھ معیاری Kong ہیڈرز شامل ہوتے ہیں: RateLimit-Limit، RateLimit-Remaining، RateLimit-Reset، X-RateLimit-Limit-Second، X-RateLimit-Remaining-Second، اور 429 پر Retry-After۔

نمونہ 429 جواب

http

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 0

{"message":"API rate limit exceeded"}

TIP

اگر آپ ایک ہی API کلید کے ساتھ 50 req/sec تک پہنچ رہے ہیں اور مزید کی ضرورت ہے، تو سپورٹ سے رابطہ کریں — فی کلید حد بڑھائی جا سکتی ہے، یا آپ کے کنزیومر کے ساتھ ایک وقف شدہ ریٹ لمیٹ پلگ اِن منسلک کیا جا سکتا ہے۔

ڈیبگ ہیڈرز

ہر جواب کے ساتھ ایسے شناخت کنندگان بھی شامل ہوتے ہیں جو سپورٹ ٹکٹ کھولتے وقت مفید ثابت ہوتے ہیں — براہ کرم انہیں من و عن شامل کریں تاکہ ہم چند سیکنڈوں میں اپنے لاگز میں درخواست کو تلاش کر سکیں:

ہیڈر	مطلب
`X-Request-ID`	ایپلیکیشن سائیڈ درخواست ID (کیلکولیٹر کے ذریعے تیار کردہ)۔
`X-Process-Time`	ملی سیکنڈ میں ایپلیکیشن پروسیسنگ کا وقت (اپ اسٹریم، Kong کو چھوڑ کر)۔
`X-Kong-Request-Id`	Kong سائیڈ درخواست ID (Kong کے ایکسس لاگز میں موجود)۔

کلائنٹ سائیڈ ٹائم آؤٹ اور دوبارہ کوشش (Timeout and retry)

کیلکولیٹر ہر درخواست کے لیے TRON نوڈز سے لائیو آن چین سوالات کرتا ہے، چنانچہ لوڈ یا سست اپ اسٹریم نوڈز کے تحت ایک کال مکمل ہونے میں کئی سیکنڈ لگ سکتے ہیں۔ مختصر کلائنٹ ٹائم آؤٹ صحت مند جوابات پر بھی ناکام ہو جائیں گے — انٹیگریٹرز کی جانب سے موصول ہونے والی زیادہ تر cURL error 28 (Connection timed out) رپورٹس کی بنیادی وجہ یہی ہے۔

تجویز کردہ ترتیبات:

ٹائم آؤٹ ≥ 15 سیکنڈ (30 سیکنڈ زیادہ محفوظ ہے)۔ کئی HTTP کلائنٹس کی جانب سے استعمال ہونے والا ڈیفالٹ 10 سیکنڈ بہت مختصر ہے۔
HTTP 429 پر، Retry-After ہیڈر (سیکنڈز) کا احترام کریں۔ دوبارہ کوشش کرنے سے پہلے تھوڑا سا وقفہ (مثلاً 0–200 ملی سیکنڈ) شامل کریں، پھر اگر آپ اب بھی 50 req/sec کی حد سے ٹکرا رہے ہیں تو exponential backoff کا استعمال کریں۔
HTTP 5xx یا نیٹ ورک کی خرابیوں پر، زیادہ سے زیادہ 2–3 بار exponential backoff کے ساتھ دوبارہ کوشش کریں؛ اینڈ پوائنٹ پر مسلسل درخواستوں کی بوچھاڑ نہ کریں۔
نتائج کو کلائنٹ سائیڈ پر فی (sender_address, receiver_address) جوڑے 30–60 سیکنڈ کے لیے کیش کریں — بنیادی وسائل کی قیمتیں اور آن چین کیفیت شاذ و نادر ہی اتنی تیزی سے تبدیل ہوتی ہیں کہ بار بار ازسرنو حساب لگانے کی ضرورت پڑے۔

براؤزر / CORS سپورٹ

یہ اینڈ پوائنٹ سرور ٹو سرور انٹیگریشنز کے لیے ڈیزائن کیا گیا ہے اور فی الوقت براؤزر سے براہ راست کالز کو سپورٹ نہیں کرتا: اپ اسٹریم FastAPI ایپ صرف Access-Control-Allow-Methods: GET کا اعلان کرتی ہے، لہٰذا براؤزرز میں کراس اوریجن POST کے لیے پری فلائٹ OPTIONS ناکام ہو جائے گا۔

اگر آپ کو براؤزر فرنٹ اینڈ سے کیلکولیٹر کو کال کرنے کی ضرورت ہے، تو کلائنٹ پر کلید کو ظاہر کرنے کے بجائے درخواست کو اپنے بیک اینڈ کے ذریعے پراکسی کریں (جس کے پاس API کلید موجود ہے)۔

TIP

اگر آپ کا استعمال جائز طور پر API کلید کے ساتھ براؤزر سائیڈ POST کا تقاضا کرتا ہے (مثلاً معلوم اوریجن پر ایک قابل اعتماد اندرونی ڈیش بورڈ)، تو سپورٹ سے رابطہ کریں — آپ کے روٹ کے لیے Kong لیول پر ایک CORS پلگ اِن منسلک کیا جا سکتا ہے۔

نوٹس

جواب کا فارمیٹ جان بوجھ کر پبلک اینڈ پوائنٹ کے مماثل رکھا گیا ہے، تاکہ پبلک رسپانس کو پارس کرنے والا کلائنٹ کوڈ تصدیق شدہ ویرینٹ پر منتقل ہونے کے بعد بھی کام کرتا رہے — صرف کال بذات خود تبدیل ہوتی ہے۔
دونوں X-API-KEY: {key} (ترجیحی، /apiv2/order1h کے ساتھ مطابقت پذیر) اور Authorization: Bearer {key} / Authorization: {key} قبول کیے جاتے ہیں؛ اگر دونوں بھیجے جائیں تو X-API-KEY غالب رہے گا۔
Cloudflare / ریورس پراکسی کی مداخلت اس اینڈ پوائنٹ کو اس طرح متاثر نہیں کرتی جس طرح پبلک والے کو کرتی ہے، کیونکہ تصدیق شدہ ٹریفک فی Kong نوڈ ریٹ لمیٹڈ ہوتی ہے اور درخواست پر فی کنزیومر طریقہ کار کو فعال کیا جا سکتا ہے۔

POST /apiv2/usdt/analyze ​

اینڈ پوائنٹ URL ​

تصدیق (Authentication) ​

درخواست کی باڈی (Request body) ​

فیلڈز ​

درخواست کی مثالیں ​

cURL (ترجیحی — X-API-KEY) ​

cURL (متبادل — Authorization) ​

Python ​

جواب (Response) ​

کامیابی (200 OK) ​

خرابیاں (Errors) ​

ریٹ لمیٹ (Rate limit) ​

نمونہ 429 جواب ​

ڈیبگ ہیڈرز ​

کلائنٹ سائیڈ ٹائم آؤٹ اور دوبارہ کوشش (Timeout and retry) ​

براؤزر / CORS سپورٹ ​

نوٹس ​