POST /apiv2/bandwidth

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

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

اینڈپوائنٹ URL

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

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

ہیڈر	درکار ہے	تفصیل
Content-Type	ہاں	application/json
X-API-KEY	ہاں	آپ کی API کلید Netts ڈیش بورڈ سے
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	نہیں	ڈرائی رن (Dry run)۔ اگر `true` ہو، تو آرڈر کے مکمل عمل کا مشابہ بنا کر ٹیسٹ کیا جاتا ہے — جواب آپ کو وہ نتیجہ بتاتا ہے جو واقع ہوگا اور وہ قیمت جو وصول کی جائے گی — بغیر کسی آن چین کارروائی کے اور بغیر کسی چارج کے۔ طے شدہ `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 تک)۔ ہمیشہ ایک array (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 خودکار طور پر undelegate ہو جاتی ہے اور ٹرانزیکشن ہیش واپس کر دی جاتی ہے۔

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

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

آرڈر کی حالت	HTTP	code	status	نتیجہ
ڈیلیگیٹڈ → اب ریکلیم کر لیا گیا	200	10004	`reclaimed`	`reclaimHash` (undelegate tx کے ہیشز)
پہلے سے ریکلیم شدہ ہے	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)}")

رضاکارانہ طور پر وقت سے پہلے ریکلیم کرنے پر کرائے کی رقم واپس نہیں کی جاتی — ریکلیم کرنے سے صرف ڈیلیگیٹڈ 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 ریکلیم کر لی گئی (رضاکارانہ طور پر undelegate) — `reclaimHash` واپس کر دیا گیا	200
`-`	ڈپلیکیٹ درخواست ابھی پراسیس ہو رہی ہے	409
`-1`	غلط API کلید / IP وائٹ لسٹ میں شامل نہیں ہے	401
`1004`	ناکافی بیلنس	403
`1005`	صارف کے لیے کوئی ادائیگی کنندہ এডریس نہیں ہے	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 کو شامل کرنا ضروری ہے: ایک ہی ایڈریس کے لیے 5m اور 1h کے لیے کرائے پر لینا مختلف آرڈرز ہیں اور ان کے لیے مختلف کیز تیار ہونی چاہئیں۔

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

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

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

نوٹس

رسائی کے درجات: تصدیق شدہ اکاؤنٹس پول/زیادہ سے زیادہ حدود کے اندر کسی بھی مقدار کو بیک وقت آرڈرز کے ساتھ کرائے پر لے سکتے ہیں؛ بغیر تصدیق کے — ایک بار میں 400 یونٹس (اگلا آرڈر صرف پچھلے کرائے کی مدت ختم ہونے کے بعد)۔ تصدیق کے لیے Netts سپورٹ سے رابطہ کریں۔
کم از کم: 400 یونٹس۔ زیادہ سے زیادہ: 5000 یونٹس فی آرڈر (موجودہ کنفیگریشن)۔
مدتیں: 5m (300 سیکنڈ) اور 1h (3600 سیکنڈ)۔ مدت ختم ہونے پر Bandwidth خودکار طور پر ریکلیم کر لی جاتی ہے۔
کوئی بفر نہیں: بالکل اتنی ہی مقدار ڈیلیگیٹ کی جاتی ہے جتنی درخواست کی گئی ہو۔
hash ایک array ہے: ایک ہی آرڈر 10 تک ڈیلیگیشن ہیشز تیار کر سکتا ہے — سبھی واپس کیے جاتے ہیں۔
قیمت کا تعین: TRX میں وصول کیا جاتا ہے، درخواست کردہ مقدار اور مدت کی بنیاد پر؛ دن کے اوقات کے لحاظ سے قیمتیں مختلف ہو سکتی ہیں۔ موجودہ قیمتوں کے لیے سپورٹ سے رابطہ کریں۔
چھوٹے آرڈر کا معاوضہ (ڈیلیگیشن): 1000 یونٹس سے کم کے آرڈرز کے لیے، آن چین ڈیلیگیشن اور ریکلیم کے معاوضے کے طور پر قیمت میں ایک مقررہ 0.372 TRX کا اضافہ کیا جاتا ہے۔ 1000 یونٹس یا اس سے زیادہ کے آرڈرز میں ایسا کوئی اضافہ نہیں ہوتا۔
TRX بھیجنے کا معاوضہ: جب آرڈر 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 ​

درخواست کے ہیڈرز (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) ​

کلید بنانے کا طریقہ ​

نوٹس ​

POST /apiv2/bandwidth

اینڈپوائنٹ 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)

کلید بنانے کا طریقہ

نوٹس