POST /apiv2/bandwidth

ایک مقررہ مدت (5 منٹ یا 1 گھنٹہ) کے لیے TRON bandwidth کرایے پر حاصل کریں اور اسے وصول کنندہ کے پتے پر ڈیلیگیٹ کریں۔

⚠️ رسائی کے درجات (Access tiers)
تصدیق شدہ اکاؤنٹس پول کے سائز اور زیادہ سے زیادہ حدود کے اندر کوئی بھی مقدار (5000 تک) کرایے پر لے سکتے ہیں، ایک ساتھ متعدد آرڈرز کے ساتھ۔ تصدیق Netts سپورٹ کے ذریعے فراہم کی جاتی ہے۔
بغیر تصدیق کے آپ ایک بار میں 400 یونٹس کرایے پر لے سکتے ہیں — اگلا آرڈر صرف پچھلے کرایے کی مدت ختم ہونے کے بعد ہی ممکن ہے۔ 400 کے علاوہ دیگر مقدار کی درخواستیں، یا پہلا آرڈر فعال ہونے کے دوران دوسرا آرڈر مسترد کر دیا جاتا ہے۔

اینڈپوائنٹ URL (Endpoint URL)

POST https://netts.io/apiv2/bandwidth

درخواست کے ہیڈرز (Request Headers)

ہیڈر	درکار ہے	تفصیل
Content-Type	ہاں	application/json
X-API-KEY	ہاں	Netts ڈیش بورڈ سے آپ کی API کی
X-Real-IP	ہاں	آپ کی وائٹ لسٹ سے IP ایڈریس
X-Idempotency-Key	نہیں	ڈبل آرڈرنگ کے بغیر محفوظ طریقے سے دوبارہ کوشش کرنے کے لیے کلائنٹ کی تیار کردہ اختیاری کی (base64)۔ اگر خالی چھوڑ دیا جائے تو سرور خود بخود ایک کی تیار کرتا ہے

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

json

{
    "amount": 1500,
    "receiveAddress": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "period": "5m"
}

پیرامیٹرز (Parameters)

پیرامیٹر	قسم	درکار ہے	تفصیل
amount	integer	ہاں	کرایے پر لینے کے لیے Bandwidth یونٹس (کم از کم: 400، زیادہ سے زیادہ: 5000)
receiveAddress	string	ہاں	TRON کا پتہ جو bandwidth وصول کرے گا (`T…`، 34 حروف، base58)
period	string	ہاں	کرایے کی مدت: `"5m"` (5 منٹ) یا `"1h"` (1 گھنٹہ)
trx_send	boolean	نہیں	گارنٹی شدہ ٹرانزیکشن: اگر کوئی bandwidth دستیاب نہ ہو، تو اس کے بجائے پتے پر TRX بھیج دیا جائے تاکہ ٹرانزیکشن پھر بھی مکمل ہو سکے۔ صرف اس وقت کام کرتا ہے جب `amount = 400` ہو (بصورت دیگر نظر انداز کر دیا جاتا ہے)۔ طے شدہ `false`
check	boolean	نہیں	اگر `true` ہو اور وصول کنندہ کے پاس پہلے سے ہی 400 سے زیادہ bandwidth موجود ہو، تو آرڈر ڈیلیگیٹ نہیں کیا جاتا اور کوئی فنڈز چارج نہیں کیے جاتے (اسٹیٹس `enough`)۔ طے شدہ `false`
test	boolean	نہیں	ڈرائی رن۔ اگر `true` ہو تو آرڈر کے پورے بہاؤ کی نقالی (simulated) کی جاتی ہے — رسپانس آپ کو وہ نتیجہ بتاتا ہے جو واقع ہوگا اور وہ قیمت جو چارج کی جائے گی — بغیر کسی آن چین کارروائی اور بغیر کسی چارج کے۔ طے شدہ `false`

درخواستوں کی مثالیں (Example Requests)

نیچے دی گئی مثالیں X-Idempotency-Key کو تیار اور ارسال بھی کرتی ہیں تاکہ حادثاتی طور پر دہرائے جانے کی صورت میں دوسرا آرڈر نہ بنے۔ مکمل قواعد کے لیے Idempotency دیکھیں۔

cURL

bash

API_KEY="your_api_key"
ADDR="TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AMOUNT=1500
PERIOD="5m"
NONCE=$(( $(date +%s) / 2 ))   # stable for retries within a 2s window; or your own order UUID

# X-Idempotency-Key = base64( HMAC-SHA256( API_KEY, "addr:amount:period:nonce" ) )
IDEMP=$(printf '%s' "${ADDR}:${AMOUNT}:${PERIOD}:${NONCE}" \
  | openssl dgst -sha256 -hmac "$API_KEY" -binary | base64)

curl -X POST https://netts.io/apiv2/bandwidth \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -H "X-Idempotency-Key: $IDEMP" \
  -d "{\"amount\": $AMOUNT, \"receiveAddress\": \"$ADDR\", \"period\": \"$PERIOD\"}"

Python

python

import time, hmac, hashlib, base64, requests

API_KEY = "your_api_key"
url = "https://netts.io/apiv2/bandwidth"
payload = {
    "amount": 1500,
    "receiveAddress": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "period": "5m",
}

# X-Idempotency-Key = base64( HMAC-SHA256( API_KEY, "addr:amount:period:nonce" ) )
# Generate ONCE per order and resend the same value on every retry.
nonce = str(int(time.time() // 2))   # 2s bucket; or your own order UUID
message = f"{payload['receiveAddress']}:{payload['amount']}:{payload['period']}:{nonce}"
idem_key = base64.b64encode(
    hmac.new(API_KEY.encode(), message.encode(), hashlib.sha256).digest()
).decode()

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": API_KEY,
    "X-Real-IP": "your_whitelisted_ip",
    "X-Idempotency-Key": idem_key,
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
detail = data.get("detail", {})

if response.status_code == 200 and detail.get("status") == "completed":
    d = detail["data"]
    print(f"Order ID: {d['orderId']}")
    print(f"Hashes:   {d['hash']}")          # array of delegation tx hashes
    print(f"Bandwidth: {d['bandwidth']} for {d['period']}")
    print(f"Cost:     {d['paidTRX']} TRX")
else:
    print(f"Code: {detail.get('code')} | {detail.get('msg', detail)}")

سروس پیکیج کے ساتھ ایک مکمل کلائنٹ مثال (Python + cURL) فراہم کی گئی ہے (handler_bandwidth/doc/client_example/)۔

رسپانس (Response)

کامیابی — bandwidth ڈیلیگیٹ ہو گئی (200 OK)

json

{
    "detail": {
        "code": 10000,
        "status": "completed",
        "msg": "Successful",
        "data": {
            "orderId": "B5M<key14>",
            "paidTRX": "<amount charged in TRX>",
            "fulfilledBy": "bandwidth",
            "hash": ["a1b2c3...", "d4e5f6..."],
            "bandwidth": 1500,
            "period": "5m"
        }
    }
}

کامیابی — bandwidth کے بجائے TRX بھیجا گیا (200 OK، صرف `amount=400` + `trx_send=true`)

جب پول میں کوئی bandwidth نہ ہو اور trx_send فعال ہو، تو پتے پر TRX بھیجا جاتا ہے تاکہ ٹرانزیکشن پھر بھی مکمل ہو سکے۔ اس صورت میں درخواست کردہ مدت سے قطع نظر ایک مقررہ چارج لاگو ہوتا ہے۔

json

{
    "detail": {
        "code": 10000,
        "status": "completed",
        "msg": "Successful (sent TRX, bandwidth unavailable)",
        "data": {
            "orderId": "B5M<key14>",
            "paidTRX": "<amount charged in TRX>",
            "fulfilledBy": "trx",
            "trxSendHash": ["<txid>"],
            "hash": [],
            "bandwidth": 400,
            "period": "5m"
        }
    }
}

پہلے سے کافی ہے — چارج نہیں کیا گیا (200 OK، صرف `check=true` کے ساتھ)

json

{
    "detail": {
        "code": 10002,
        "status": "enough",
        "msg": "enough band for 1 transfer",
        "data": { "orderId": "B5M<key14>", "paidTRX": 0, "bandwidth": 400, "period": "5m" }
    }
}

پراسیسنگ جاری ہے — بیرونی فراہم کنندہ (202 Accepted)

تب واپس آتا ہے جب آرڈر غیر مطابقت پذیر (asynchronously) طور پر کسی بیرونی فراہم کنندہ کے حوالے کیا جاتا ہے۔ مکمل ہونے تک orderId کا استعمال کرتے ہوئے اسٹیٹس اینڈپوائنٹ (نیچے) کو پول (poll) کریں۔

json

{
    "detail": {
        "code": 10001,
        "status": "processing",
        "msg": "Order accepted, processed by an external provider. Poll the status endpoint.",
        "data": { "orderId": "B5M<key14>", "bandwidth": 1500, "period": "5m" }
    }
}

ٹیسٹ رن (200 OK، صرف `test=true` کے ساتھ)

پورے آرڈر کے بہاؤ کی نقالی کی جاتی ہے۔ testAction آپ کو بتاتا ہے کہ کیا ہوگا اور wouldCostTRX یہ بتاتا ہے کہ کیا چارج کیا جائے گا۔ کچھ بھی ڈیلیگیٹ نہیں کیا جاتا، کوئی TRX نہیں بھیجا جاتا، کچھ بھی چارج نہیں کیا جاتا (paidTRX: 0)۔

json

{
    "detail": {
        "code": 10003,
        "status": "test",
        "msg": "Test run — no on-chain action, no charge",
        "data": {
            "orderId": "B5M<...>",
            "testAction": "would_delegate",
            "wouldCostTRX": "<amount that would be charged in TRX>",
            "paidTRX": 0,
            "bandwidth": 400,
            "period": "5m",
            "receiverFreeBandwidth": 600
        }
    }
}

testAction کی اقدار: would_delegate (bandwidth ڈیلیگیٹ کی جائے گی)، would_trx_send (کوئی bandwidth نہیں، amount=400 + trx_send → TRX بھیجا جائے گا)، enough (وصول کنندہ کے پاس پہلے سے کافی ہے، check=true کے ساتھ)، یا would_error:<reason> (مثلاً no_bandwidth، not_whitelisted)۔

رسپانس کے فیلڈز (Response Fields)

فیلڈ	قسم	تفصیل
detail.code	integer	`10000` ڈیلیگیٹ شدہ/TRX، `10002` کافی ہے، `10001` پراسیسنگ جاری ہے
detail.status	string	`completed` / `enough` / `processing` / `failed`
detail.data.orderId	string	آرڈر ID، فارمیٹ `B5M…` (5 منٹ) / `B1H…` (1 گھنٹہ) — اسے اسٹیٹس اینڈپوائنٹ کے لیے استعمال کریں
detail.data.paidTRX	number	TRX میں چارج کی گئی رقم (جب `enough` ہو تو `0`)
detail.data.fulfilledBy	string	`bandwidth` (ڈیلیگیٹ کیا گیا) / `trx` (TRX بھیجا گیا)
detail.data.hash	array	ڈیلیگیشن ٹرانزیکشن ہیشز (10 تک)۔ ہمیشہ ایک ارے (TRX برانچ کے لیے خالی)
detail.data.trxSendHash	array	TRX ٹرانسفر ہیش (یا ہیشز)، صرف اس وقت موجود جب `fulfilledBy = trx` ہو
detail.data.bandwidth	integer	ڈیلیگیٹ کیے گئے Bandwidth یونٹس
detail.data.period	string	کرایے کی مدت (`5m` / `1h`)

اسٹیٹس اینڈپوائنٹ (Status Endpoint)

GET https://netts.io/apiv2/bandwidth/status/{orderId}

ہیڈرز: X-API-KEY + X-Real-IP (آرڈر لازماً تصدیق شدہ صارف کا ہونا چاہیے)۔

آرڈر کی حالت	HTTP	code	status
مکمل ہو گیا	200	10000	`completed` (`hash` / `trxSendHash` کے ساتھ)
جاری ہے	200	10001	`processing`
پہلے سے کافی ہے	200	10002	`enough`
ناکام ہو گیا	200	5003	`failed`
نہیں ملا / آپ کا نہیں ہے	404	-1	—

ریکلیم اینڈپوائنٹ (Reclaim Endpoint)

اپنے ڈیلیگیٹ شدہ آرڈرز میں سے کسی ایک کی bandwidth کو اس کی مدت ختم ہونے سے پہلے اپنی مرضی سے واپس حاصل (undelegate) کریں۔ bandwidth خود بخود ان ڈیلیگیٹ ہو جاتی ہے اور ٹرانزیکشن ہیش واپس کر دیا جاتا ہے۔

POST https://netts.io/apiv2/bandwidth/reclaim/{orderId}

ہیڈرز: X-API-KEY + X-Real-IP (آرڈر لازماً تصدیق شدہ صارف کا ہونا چاہیے)۔

آرڈر کی حالت	HTTP	code	status	نتیجہ
ڈیلیگیٹ شدہ → اب واپس حاصل کر لیا گیا	200	10004	`reclaimed`	`reclaimHash` (ان ڈیلیگیٹ ٹرانزیکشن ہیشز)
پہلے ہی واپس حاصل کر لیا گیا	200	10004	`reclaimed`	`reclaimHash` + پیغام "already reclaimed"
ڈیلیگیٹ شدہ حالت میں نہیں ہے (ریکلیم کرنے کے لیے کچھ نہیں ہے)	400	5005	`failed`	—
ریکلیم کا عمل ابھی مکمل نہیں ہوا	503	5003	`failed`	کچھ دیر بعد دوبارہ کوشش کریں
نہیں ملا / آپ کا نہیں ہے	404	-1	—	—

bash

curl -X POST https://netts.io/apiv2/bandwidth/reclaim/B5M<...> \
  -H "X-API-KEY: your_api_key" -H "X-Real-IP: your_whitelisted_ip"

json

{
    "detail": {
        "code": 10004,
        "status": "reclaimed",
        "msg": "Bandwidth reclaimed",
        "data": { "orderId": "B5M<...>", "reclaimHash": ["<txid>"] }
    }
}

python

import requests

order_id = "B5M..."   # the orderId from your rental response
url = f"https://netts.io/apiv2/bandwidth/reclaim/{order_id}"
headers = {"X-API-KEY": "your_api_key", "X-Real-IP": "your_whitelisted_ip"}

resp = requests.post(url, headers=headers)
detail = resp.json()["detail"]

if resp.status_code == 200 and detail["status"] == "reclaimed":
    print(f"Reclaimed: {detail['data']['reclaimHash']} ({detail['msg']})")
else:
    print(f"Code {detail.get('code')}: {detail.get('msg', detail)}")

رضاکارانہ طور پر جلد ریکلیم کرنے پر کرایے کی رقم واپس (refund) نہیں کی جاتی — ریکلیم کرنے سے صرف مدت ختم ہونے سے پہلے پول میں ڈیلیگیٹ شدہ bandwidth واپس آ جاتی ہے۔

خرابی کے رسپانسز (Error Responses)

تصدیق کی خرابی (401)

json

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

ناکافی بیلنس (403)

json

{ "detail": { "code": 1004, "status": "failed", "msg": "Insufficient funds" } }

توثیق کی خرابی (400)

json

{ "detail": { "code": 5004, "status": "failed", "msg": "Bandwidth amount out of range (400..5000)" } }

ڈیلیگیشن ناکام ہو گئی / سروس دستیاب نہیں ہے (503)

json

{ "detail": { "code": 5003, "status": "failed", "msg": "Bandwidth delegation failed" } }

خرابی کے کوڈز کا حوالہ (Error Code Reference)

کوڈ	تفصیل	HTTP اسٹیٹس
`10000`	کامیابی (ڈیلیگیٹ ہو گیا، یا TRX بھیجا گیا)	200
`10000`	کامیابی (محفوظ شدہ کیشے رسپانس)	208
`10001`	قبول کر لیا گیا، بیرونی فراہم کنندہ کے ذریعے پراسیسنگ جاری ہے	202
`10002`	وصول کنندہ کے پاس پہلے ہی کافی bandwidth موجود ہے (چارج نہیں کیا گیا)	200
`10003`	ٹیسٹ رن — نتیجہ + قیمت کا پیش نظارہ، کچھ بھی چارج نہیں کیا گیا (`test=true`)	200
`10004`	Bandwidth ریکلیم ہو گئی (رضاکارانہ ان ڈیلیگیٹ) — `reclaimHash` واپس کیا گیا	200
`-`	ڈپلیکیٹ درخواست پر ابھی پراسیسنگ جاری ہے	409
`-1`	غلط API کی / IP وائٹ لسٹ میں شامل نہیں ہے	401
`1004`	ناکافی بیلنس	403
`1005`	صارف کے لیے کوئی ادا کنندہ (payer) پتہ نہیں ہے	400
`5004`	غلط مقدار/مدت (توثیق)	400
`5005`	ریکلیم کے لیے کچھ نہیں ہے (آرڈر ڈیلیگیٹ شدہ حالت میں نہیں ہے)	400
`5007`	بغیر تصدیق کے — ایک وقت میں صرف ایک کرایہ؛ پچھلا آرڈر ابھی بھی فعال ہے (اس کے ختم ہونے تک انتظار کریں)	503
`5008`	بغیر تصدیق کے — صرف 400 یونٹ کے آرڈرز کی اجازت ہے؛ بڑی مقدار کے لیے تصدیق درکار ہے	503
`5003`	Bandwidth ڈیلیگیشن ناکام ہو گئی / دستیاب نہیں ہے	503
`5000`	اندرونی سرور کی خرابی	500

شرح کی حدود (Rate Limits)

مدت	حد	تفصیل
1 سیکنڈ	50 درخواستیں	فی IP زیادہ سے زیادہ 50 درخواستیں فی سیکنڈ

شرح کی حد سے تجاوز (429)

json

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

آئیڈیمپوٹینسی (Idempotency)

اختیاری X-Idempotency-Key ہیڈر بھیجیں تاکہ حادثاتی طور پر دہرائے جانے سے دوسرا آرڈر نہ بنے — اصل رسپانس HTTP 208 کے ساتھ واپس کیا جاتا ہے۔ اگر آپ ہیڈر نہیں بھیجتے ہیں، تو سرور مختصر وقت کے اندر آپ کی درخواست کے پیرامیٹرز سے خود بخود ایک کی حاصل کر لیتا ہے۔

کی کیسے تیار کی جائے

کی base64( HMAC-SHA256( secret, message ) ) ہے — ایک 44 حروف پر مشتمل base64 سٹرنگ، جہاں:

secret = آپ کی API کی (X-API-KEY)؛
message = فیلڈز جنہیں : کے ساتھ جوڑا گیا ہے — receiveAddress:amount:period:nonce۔

nonce کوئی بھی ایسی قدر ہے جو ایک ہی منطقی آرڈر کی دوبارہ کوششوں میں یکساں رہے لیکن مختلف آرڈرز کے درمیان منفرد ہو — مثلاً ایک UUID جو آپ اس آرڈر کے لیے رکھتے ہیں، یا ایک مختصر ٹائم اسٹیمپ بکیٹ۔ ہر آرڈر کے لیے ایک بار کی تیار کریں اور ہر بار دوبارہ کوشش کرتے ہوئے بالکل وہی قدر دوبارہ بھیجیں۔

python

import hmac, hashlib, base64, time

def make_idempotency_key(api_key, receive_address, amount, period, nonce=None):
    if nonce is None:
        nonce = str(int(time.time() // 2))   # 2-second bucket; or your own order UUID
    message = f"{receive_address}:{amount}:{period}:{nonce}"
    digest = hmac.new(api_key.encode(), message.encode(), hashlib.sha256).digest()
    return base64.b64encode(digest).decode()  # 44-char base64

bash

# then send it as a header:
-H "X-Idempotency-Key: <base64_key>"

پیغام میں period کو شامل کرنا ضروری ہے: ایک ہی پتے کے لیے 5 منٹ اور 1 گھنٹے کے لیے کرایہ پر لینا مختلف آرڈرز ہیں اور ان سے مختلف کیز بننی چاہئیں۔

توثیق۔ فراہم کردہ X-Idempotency-Key لازماً 16–64 حروف کی ایک base64 سٹرنگ ہونی چاہیے (حروف کا سیٹ A–Z a–z 0–9 + / = _ -)۔ غلط تشکیل شدہ یا ضرورت سے زیادہ لمبی کی کو HTTP 400 (code 5004) کے ساتھ مسترد کر دیا جاتا ہے۔

اسٹیٹس کوڈ	مفہوم
200	کامیابی سے پراسیس ہو گیا (پہلی درخواست)
208	پہلے ہی کامیابی سے پراسیس ہو چکا ہے — کیشے سے رسپانس دیا گیا (کوئی دوسرا چارج نہیں)
409	اسی درخواست پر فی الحال پراسیسنگ جاری ہے — انتظار کریں، ابھی دوبارہ کوشش نہ کریں

ناکامی کے بعد دوبارہ کوشش کرنا۔ صرف کامیاب نتائج (completed / enough) کیش کیے جاتے ہیں۔ اگر پچھلی کوشش ناکام ہوگئی یا ٹائم آؤٹ ہوگئی (کوئی فنڈز چارج نہیں کیے گئے تھے)، تو آپ محفوظ طریقے سے اسی X-Idempotency-Key کے ساتھ دوبارہ کوشش کر سکتے ہیں — پرانی خرابی واپس کرنے کے بجائے آرڈر کی دوبارہ کوشش کی جاتی ہے۔ جب تک کوئی کوشش جاری رہتی ہے آپ کو 409 ملتا ہے؛ انتظار کریں اور دوبارہ کوشش کریں۔

پوسٹ پیڈ اکاؤنٹس (Postpaid Accounts)

پوسٹ پیڈ بلنگ پر موجود اکاؤنٹس بھی وہی اینڈپوائنٹ، URL، ہیڈرز اور درخواست کا باڈی استعمال کرتے ہیں جو باقی سب کرتے ہیں۔ فرق صرف اس بات میں ہے کہ آرڈر کی ادائیگی کیسے کی جاتی ہے:

آپ کے ڈپازٹ سے کچھ بھی نہیں کاٹا جاتا۔ ہر ڈیلیور کیا گیا آرڈر آپ کے اکاؤنٹ کے واجب الادا بیلنس میں آپ کے معاہدے میں طے شدہ کرنسی کے تحت شامل کر دیا جاتا ہے۔ آپ اپنے معاہدے کے مطابق انوائس کے ذریعے اس کی ادائیگی کرتے ہیں۔
آپ کے اکاؤنٹ کی ایک کریڈٹ کی حد (credit limit) ہے۔ جب تک واجب الادا رقم اس حد کے اندر ہے، زیرو ڈپازٹ کے باوجود آرڈرز قبول کیے جاتے ہیں۔ 5 منٹ اور 1 گھنٹے کے کرایے ایک ہی bandwidth کی حد کے تحت شمار ہوتے ہیں۔
صرف ڈیلیور کی گئی خدمات کا بل دیا جاتا ہے: پتے پر ڈیلیگیٹ کی گئی bandwidth، یا اس کے بجائے بھیجا گیا TRX (fulfilledBy = trx)۔ رقم وہی ہے جو پری پیڈ آرڈرز کے لیے ہوتی ہے۔
مسترد شدہ، غیر عمل شدہ، ٹیسٹ رن (test: true) یا enough (check: true) رسپانس والے آرڈر کی کوئی قیمت نہیں لگتی۔
رضاکارانہ قبل از وقت ریکلیم کرنے سے واجب الادا رقم کم نہیں ہوتی، بالکل پری پیڈ آرڈرز کی طرح۔
رسائی کے درجات، مقداریں، مدتیں اور اس اینڈپوائنٹ کے دیگر تمام قوانین پری پیڈ اکاؤنٹس جیسے ہی ہیں۔

درخواست کرنے پر Netts کی جانب سے کسی اکاؤنٹ کے لیے پوسٹ پیڈ بلنگ فعال کی جاتی ہے۔ ہر رسپانس آپ کو بتاتا ہے کہ آرڈر کی ادائیگی کیسے کی گئی ہے: paymentMode یا تو postpaid ہوگا یا prepaid۔

قیمت کی جانچ (`test: true`)

json

{
    "amount": 1000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "period": "5m",
    "test": true
}

json

{
    "detail": {
        "code": 10003,
        "status": "test",
        "msg": "Test run — no on-chain action, no charge",
        "data": {
            "orderId": "B5M1a2b3c4d5e6f70",
            "testAction": "would_delegate",
            "wouldCostTRX": 0.7,
            "paidTRX": 0,
            "bandwidth": 1000,
            "period": "5m",
            "receiverFreeBandwidth": 600,
            "paymentMode": "postpaid"
        }
    }
}

wouldCostTRX وہ رقم ہے جو TRX میں آپ کے واجب الادا بیلنس میں شامل کی جائے گی۔ کچھ بھی ڈیلیگیٹ یا بل نہیں کیا جاتا۔

کامیاب آرڈر

json

{
    "detail": {
        "code": 10000,
        "status": "completed",
        "msg": "Successful, 0.700000 TRX, postpaid",
        "data": {
            "orderId": "B5M0f9e8d7c6b5a41",
            "paidTRX": 0.7,
            "fulfilledBy": "bandwidth",
            "hash": ["<txid>"],
            "bandwidth": 1000,
            "period": "5m",
            "paymentMode": "postpaid",
            "totalTRX": "0.700000"
        }
    }
}

فیلڈ	تفصیل
paidTRX	TRX میں سروس کی لاگت۔ پوسٹ پیڈ اکاؤنٹس کے لیے یہ ڈپازٹ سے نہیں کاٹی جاتی
paymentMode	`postpaid`
totalTRX	درست رقم، 6 اعشاریہ مقامات تک

باقی تمام فیلڈز، بشمول TRX برانچ (fulfilledBy = trx، trxSendHash)، پری پیڈ آرڈرز جیسے ہی ہیں۔

کریڈٹ کی حد ختم ہو گئی (402)

json

{
    "detail": {
        "code": 1004,
        "msg": "Postpaid credit limit reached.",
        "paymentMode": "postpaid",
        "reason": "limit_reached"
    }
}

آرڈر پر عمل درآمد نہیں ہوتا اور کچھ بھی بل نہیں کیا جاتا۔ آپ کی ادائیگی کے اندراج کے بعد یا آپ کی حد میں اضافہ ہونے پر نئے آرڈرز دوبارہ قبول کیے جاتے ہیں۔

پوسٹ پیڈ خرابی کے کوڈز

کوڈ	HTTP	تفصیل
`1004`	402	پوسٹ پیڈ کریڈٹ کی حد ختم ہو گئی
`5032`	503	قیمت عارضی طور پر دستیاب نہیں ہے
`5034`	503	بلنگ عارضی طور پر دستیاب نہیں ہے — آرڈر قبول نہیں کیا گیا
`5036`	503	کریڈٹ چیک عارضی طور پر دستیاب نہیں ہے — بعد میں دوبارہ کوشش کریں

اوپر دیے گئے تمام رسپانسز کے لیے کچھ بھی آرڈر نہیں ہوتا اور کچھ بھی بل نہیں کیا جاتا۔ دیگر تمام کوڈز پری پیڈ آرڈرز جیسے ہی ہیں۔

نوٹس (Notes)

رسائی کے درجات: تصدیق شدہ اکاؤنٹس پول/زیادہ سے زیادہ حدود کے اندر ایک ساتھ متعدد آرڈرز کے ساتھ کوئی بھی رقم کرایے پر لے سکتے ہیں؛ بغیر تصدیق کے — ایک بار 400 یونٹس (اگلا آرڈر صرف پچھلا کرایہ ختم ہونے کے بعد)۔ تصدیق کے لیے Netts سپورٹ سے رابطہ کریں۔
کم از کم: 400 یونٹس۔ زیادہ سے زیادہ: 5000 یونٹس فی آرڈر (موجودہ کنفیگریشن)۔
مدتیں: 5m (300 سیکنڈ) اور 1h (3600 سیکنڈ)۔ مدت ختم ہونے پر bandwidth خود بخود ریکلیم ہو جاتی ہے۔
کوئی بفر نہیں: بالکل اتنی ہی مقدار ڈیلیگیٹ کی جاتی ہے جتنی درخواست کی گئی ہو۔
hash ایک ارے ہے: ایک آرڈر 10 تک ڈیلیگیشن ہیشز پیدا کر سکتا ہے — تمام واپس کیے جاتے ہیں۔
قیمت کا تعین: درخواست کردہ رقم اور مدت کی بنیاد پر TRX میں چارج کیا جاتا ہے؛ دن کے اوقات کے لحاظ سے قیمتیں مختلف ہو سکتی ہیں۔ موجودہ قیمتوں کے لیے سپورٹ سے رابطہ کریں۔
چھوٹے آرڈر کا معاوضہ (ڈیلیگیشن): 1000 یونٹس سے کم کے آرڈرز کے لیے، آن چین ڈیلیگیشن اور ریکلیم کے معاوضے کے طور پر قیمت میں ایک مقررہ 0.372 TRX شامل کیا جاتا ہے۔ 1000 یونٹس یا اس سے زیادہ کے آرڈرز پر ایسا کوئی اضافہ نہیں ہوتا۔
TRX-send معاوضہ: جب آرڈر TRX بھیج کر پورا کیا جاتا ہے (fulfilledBy = trx)، تو اس کے بجائے ایک مقررہ 0.268 TRX شامل کیا جاتا ہے (آن چین TRX ٹرانسفر کے معاوضے کے طور پر)۔
trx_send: صرف amount = 400 کے لیے؛ اگر کوئی bandwidth دستیاب نہ ہو، تو پتے پر TRX بھیجا جاتا ہے تاکہ ٹرانزیکشن پھر بھی مکمل ہو سکے۔
check: جب وصول کنندہ کے پاس پہلے سے ہی 400 سے زیادہ bandwidth ہو تو ڈیلیگیشن (اور چارجنگ) کو چھوڑ دیتا ہے۔
آرڈر ID فارمیٹ: B5M… (5 منٹ) / B1H… (1 گھنٹہ)۔
رسپانس کا ٹائم آؤٹ: ڈیلیگیشن کے انتظار کے دوران تقریباً 12 سیکنڈ تک؛ عام طور پر 1–2 سیکنڈ۔

POST /apiv2/bandwidth ​

اینڈپوائنٹ URL (Endpoint URL) ​

درخواست کے ہیڈرز (Request Headers) ​

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

پیرامیٹرز (Parameters) ​

درخواستوں کی مثالیں (Example Requests) ​

cURL ​

Python ​

رسپانس (Response) ​

کامیابی — bandwidth ڈیلیگیٹ ہو گئی (200 OK) ​

کامیابی — bandwidth کے بجائے TRX بھیجا گیا (200 OK، صرف amount=400 + trx_send=true) ​

پہلے سے کافی ہے — چارج نہیں کیا گیا (200 OK، صرف check=true کے ساتھ) ​

پراسیسنگ جاری ہے — بیرونی فراہم کنندہ (202 Accepted) ​

ٹیسٹ رن (200 OK، صرف test=true کے ساتھ) ​

رسپانس کے فیلڈز (Response Fields) ​

اسٹیٹس اینڈپوائنٹ (Status Endpoint) ​

ریکلیم اینڈپوائنٹ (Reclaim Endpoint) ​

خرابی کے رسپانسز (Error Responses) ​

تصدیق کی خرابی (401) ​

ناکافی بیلنس (403) ​

توثیق کی خرابی (400) ​

ڈیلیگیشن ناکام ہو گئی / سروس دستیاب نہیں ہے (503) ​

خرابی کے کوڈز کا حوالہ (Error Code Reference) ​

شرح کی حدود (Rate Limits) ​

شرح کی حد سے تجاوز (429) ​

آئیڈیمپوٹینسی (Idempotency) ​

کی کیسے تیار کی جائے ​

پوسٹ پیڈ اکاؤنٹس (Postpaid Accounts) ​

قیمت کی جانچ (test: true) ​

کامیاب آرڈر ​

کریڈٹ کی حد ختم ہو گئی (402) ​

پوسٹ پیڈ خرابی کے کوڈز ​

نوٹس (Notes) ​

POST /apiv2/bandwidth

اینڈپوائنٹ URL (Endpoint URL)

درخواست کے ہیڈرز (Request Headers)

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

پیرامیٹرز (Parameters)

درخواستوں کی مثالیں (Example Requests)

cURL

Python

رسپانس (Response)

کامیابی — bandwidth ڈیلیگیٹ ہو گئی (200 OK)

کامیابی — bandwidth کے بجائے TRX بھیجا گیا (200 OK، صرف `amount=400` + `trx_send=true`)

پہلے سے کافی ہے — چارج نہیں کیا گیا (200 OK، صرف `check=true` کے ساتھ)

پراسیسنگ جاری ہے — بیرونی فراہم کنندہ (202 Accepted)

ٹیسٹ رن (200 OK، صرف `test=true` کے ساتھ)

رسپانس کے فیلڈز (Response Fields)

اسٹیٹس اینڈپوائنٹ (Status Endpoint)

ریکلیم اینڈپوائنٹ (Reclaim Endpoint)

خرابی کے رسپانسز (Error Responses)

تصدیق کی خرابی (401)

ناکافی بیلنس (403)

توثیق کی خرابی (400)

ڈیلیگیشن ناکام ہو گئی / سروس دستیاب نہیں ہے (503)

خرابی کے کوڈز کا حوالہ (Error Code Reference)

شرح کی حدود (Rate Limits)

شرح کی حد سے تجاوز (429)

آئیڈیمپوٹینسی (Idempotency)

کی کیسے تیار کی جائے

پوسٹ پیڈ اکاؤنٹس (Postpaid Accounts)

قیمت کی جانچ (`test: true`)

کامیاب آرڈر

کریڈٹ کی حد ختم ہو گئی (402)

پوسٹ پیڈ خرابی کے کوڈز

نوٹس (Notes)