مستقل والٹس

شروع کرنے سے پہلے

1. 1

   سیٹ اپ مکمل کریں اور اپنے کوائنز منتخب کریں۔ ہر کسٹمر کو ان کوائنز کے نیٹ ورکس پر ایک ایڈریس ملتا ہے جو آپ قبول کرتے ہیں (پورٹل، سیٹنگز)۔

2. 2

   سیکرٹ کی بنائیں۔ پورٹل میں ڈیولپرز کھولیں اور ایک API کی بنائیں۔ یہ صرف ایک بار دکھائی جاتی ہے: اسے اپنے سرور پر رکھیں، مثلاً CM_SECRET_KEY کے طور پر، کبھی کسی ویب پیج یا ایپ میں نہیں۔

3. 3

   Webhook اینڈ پوائنٹ شامل کریں۔ ڈیولپرز ہی میں اپنا URL deposit.pending، deposit.confirmed اور deposit.dropped ایونٹس (یا تمام ایونٹس) کے ساتھ شامل کریں۔ ہر درخواست کی جانچ کے لیے اس کا سائننگ سیکرٹ، whsec_…، محفوظ رکھیں۔

یہ کیسے کام کرتا ہے

1. 1

   کوئی کسٹمر آپ کی ویب سائٹ پر ڈپازٹ صفحہ کھولتا ہے۔

2. 2

   آپ کا سرور اس کسٹمر کے لیے آپ کی اپنی ID کے ساتھ POST /sticky-wallets کال کرتا ہے۔ پہلی کال ایڈریسز بناتی ہے؛ بعد کی ہر کال وہی ایڈریسز واپس کرتی ہے۔

3. 3

   کسٹمر جو کوائن منتخب کرے، آپ اس کا ایڈریس QR کوڈ کے ساتھ دکھاتے ہیں۔

4. 4

   کوائنز پہنچنے پر آپ کو deposit.pending ملتا ہے، پھر نیٹ ورک کے کنفرم کرنے پر deposit.confirmed۔

5. 5

   deposit.confirmed ملنے پر آپ sticky_wallet.reference میں درج کسٹمر کے اکاؤنٹ میں رقم شامل کرتے ہیں۔

کسی کسٹمر کا والٹ حاصل کریں

POST/sticky-wallets

پہلی کال پر کسٹمر کا والٹ بناتا ہے اور بعد کی ہر کال پر وہی والٹ واپس کرتا ہے: ابھی بنا ہو تو 201، اس کے بعد 200۔ جب بھی ڈپازٹ صفحہ کھلے، اسے کال کرنا محفوظ ہے۔

باڈی پیرامیٹرز

referenceلازمیstring

اس کسٹمر کے لیے آپ کی ID: 1 سے 120 حروف، ہندسے یا . _ : @ + -، جو کسی حرف یا ہندسے سے شروع ہو۔ ہر ریفرنس کا ہمیشہ کے لیے ایک والٹ۔

labelاختیاریstring

ایک نام جو آپ پورٹل میں دیکھیں گے۔ دوبارہ بھیجنے پر یہ بدل جاتا ہے۔

metadataاختیاریobject

آپ کا اپنا آبجیکٹ، 4 KB تک۔ دوبارہ بھیجنے پر یہ بدل جاتا ہے۔

curl https://cryptomerchant.online/api/v1/sticky-wallets \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "user-1042",
    "label": "Jane Doe",
    "metadata": { "plan": "pro" }
  }'

// On your server, when a customer opens their deposit page
export async function depositAddresses(userId) {
  const res = await fetch("https://cryptomerchant.online/api/v1/sticky-wallets", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ reference: String(userId) }),
  });
  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message}`);
  }
  const wallet = await res.json();
  return wallet.addresses; // [{ network, address, coins: [...] }, …]
}

مستقل والٹ آبجیکٹ

idstring

والٹ کی ID، جو sw_ سے شروع ہوتی ہے۔

referencestring

کسٹمر کے لیے آپ کی ID۔

addressesarray

ہر نیٹ ورک کے لیے ایک اندراج: network (tron، evm، sol، btc یا ltc)، address اور وہ coins جو یہ قبول کرتا ہے۔ evm ایڈریس Ethereum، BNB Smart Chain، Polygon، Base اور Arbitrum پر ایک ہی ہے۔

pending_networksarray

وہ نیٹ ورکس جن کا ایڈریس ابھی تیار ہو رہا ہے، جو کم ہی ہوتا ہے۔ چند منٹ بعد دوبارہ کال کریں، یہ addresses میں آ جائیں گے۔

created_atstring

والٹ کب بنایا گیا۔

{
  "id": "sw_8Kd2pQx7Vb1mNc3T",
  "object": "sticky_wallet",
  "reference": "user-1042",
  "label": "Jane Doe",
  "metadata": { "plan": "pro" },
  "addresses": [
    {
      "network": "tron",
      "address": "TXbajeGHq4Vb…",
      "coins": [
        { "id": "TRX.TRON", "symbol": "TRX", "network": "Tron" },
        { "id": "USDT.TRON", "symbol": "USDT", "network": "Tron" }
      ]
    },
    {
      "network": "evm",
      "address": "0xE550EC6d…",
      "coins": [
        { "id": "ETH.ETH", "symbol": "ETH", "network": "Ethereum" },
        { "id": "BNB.BSC", "symbol": "BNB", "network": "BNB Smart Chain" },
        { "id": "USDT.BSC", "symbol": "USDT", "network": "BNB Smart Chain" }
      ]
    }
  ],
  "pending_networks": [],
  "created_at": "2026-10-29T18:20:41.000Z"
}

والٹس تلاش کریں

GET/sticky-wallets

GET/sticky-wallets/{id}

اپنے ریفرنس سے کوئی والٹ تلاش کریں، ID سے کوئی والٹ حاصل کریں، یا تمام والٹس صفحہ بہ صفحہ دیکھیں، تازہ ترین پہلے: limit 1 سے 100 تک، starting_after میں آپ کے پاس موجود آخری والٹ کی ID، اور has_more بتاتا ہے کہ مزید ہیں یا نہیں۔

# By your reference
curl "https://cryptomerchant.online/api/v1/sticky-wallets?reference=user-1042" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

# By id
curl https://cryptomerchant.online/api/v1/sticky-wallets/sw_8Kd2pQx7Vb1mNc3T \
  -H "Authorization: Bearer $CM_SECRET_KEY"

# All of them, 50 at a time
curl "https://cryptomerchant.online/api/v1/sticky-wallets?limit=50&starting_after=sw_8Kd2pQx7Vb1mNc3T" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [ { "id": "sw_8Kd2pQx7Vb1mNc3T", "object": "sticky_wallet", … } ],
  "has_more": false
}

ڈپازٹس کی فہرست

GET/deposits

آپ کے کسٹمرز کے والٹس میں آنے والے تمام ڈپازٹس، تازہ ترین پہلے۔ sticky_wallet (والٹ ID) اور status (pending، confirmed یا dropped) سے فلٹر کریں، اور limit اور starting_after (ڈپازٹ ID) سے صفحات بدلیں۔ جب آپ کے سرور تک کچھ webhooks نہ پہنچے ہوں تو چھوٹ جانے والے ڈپازٹس پکڑنے کے لیے اسے استعمال کریں۔

curl "https://cryptomerchant.online/api/v1/deposits?sticky_wallet=sw_8Kd2pQx7Vb1mNc3T&status=confirmed&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

ڈپازٹ آبجیکٹ

idstring

ڈپازٹ کی ID۔ ہر ڈپازٹ کی رقم صرف ایک بار شامل کرنے کے لیے اسے استعمال کریں۔

statusstring

pending: نیٹ ورک پر نظر آیا، کنفرمیشنز کا انتظار ہے۔ confirmed: حتمی، اور آپ کے بیلنس میں شامل ہو گیا۔ dropped: یہ کبھی کنفرم نہیں ہوا۔

sticky_walletobject

جس والٹ میں یہ بھیجا گیا: id اور آپ کا reference۔

coinobject

کوائن اور اس کا نیٹ ورک۔

amountstring

کسٹمر نے جو بھیجا، کوائن میں۔

feestring

فیس، کوائن میں۔

net_amountstring

کنفرم ہونے کے بعد آپ کے بیلنس میں جو شامل ہوا (رقم میں سے فیس منہا کر کے)۔

amount_usdstring

پہنچنے کے وقت اس کی امریکی ڈالر میں مالیت۔

tx_hashstring

ٹرانزیکشن ہیش؛ explorer_url اسے کسی بلاک ایکسپلورر پر کھولتا ہے۔

{
  "id": "cmvu1x9a0000l10u8k2f3h7q",
  "object": "deposit",
  "status": "confirmed",
  "sticky_wallet": { "id": "sw_8Kd2pQx7Vb1mNc3T", "reference": "user-1042" },
  "coin": { "id": "USDT.TRON", "symbol": "USDT", "network": "Tron" },
  "address": "TXbajeGHq4Vb…",
  "amount": "250",
  "amount_usd": "250.00",
  "fee": "2.5",
  "net_amount": "247.5",
  "from_address": "TQn9Y2khEsLJ…",
  "tx_hash": "36423ec5…f00d4a",
  "explorer_url": "https://tronscan.org/#/transaction/36423ec5…f00d4a",
  "confirmations": 19,
  "detected_at": "2026-10-29T18:31:02.000Z",
  "confirmed_at": "2026-10-29T18:32:01.000Z"
}

Webhooks

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

deposit.pending

آپ کے کسی کسٹمر کے مستقل والٹ میں آن چین ایک ڈپازٹ نظر آیا ہے اور کنفرمیشنز کا انتظار ہے۔

deposit.confirmed

ایک مستقل والٹ ڈپازٹ کنفرم ہو کر فیس کٹنے کے بعد آپ کے بیلنس میں شامل ہو گیا: اب اس کسٹمر کے اکاؤنٹ میں رقم شامل کریں۔

deposit.dropped

نظر آنے والا ایک مستقل والٹ ڈپازٹ کبھی کنفرم نہیں ہوا (ناکام ہو گیا یا چین سے ہٹا دیا گیا)۔

import express from "express";
import { verifyWebhook } from "./verify-webhook.js"; // from the Webhooks page
import { db } from "./db.js"; // your database; table webhook_events as on the Webhooks page

const app = express();

app.post(
  "/webhooks/crypto-merchant",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    let event;
    try {
      event = verifyWebhook(req.body, req.get("CM-Signature"), process.env.CM_WEBHOOK_SECRET);
    } catch {
      return res.sendStatus(400);
    }
    try {
      // Save first: a repeat delivery has the same event.id and is ignored
      await db.query(
        "INSERT INTO webhook_events (id, type, payload) VALUES ($1, $2, $3) ON CONFLICT (id) DO NOTHING",
        [event.id, event.type, event],
      );
    } catch {
      return res.sendStatus(500); // not saved: we send it again later
    }
    res.sendStatus(200); // stored, so confirm it
    processEvents().catch(console.error); // or run it from a background job
  },
);

async function processEvents() {
  const { rows } = await db.query(
    "SELECT payload FROM webhook_events WHERE processed_at IS NULL ORDER BY received_at",
  );
  for (const { payload: event } of rows) {
    const deposit = event.data;
    if (event.type === "deposit.pending") {
      // Optional: show "deposit on its way" to deposit.sticky_wallet.reference
    }
    if (event.type === "deposit.confirmed") {
      // Credit once: creditCustomer must skip a deposit.id it has already credited
      await creditCustomer({
        customerId: deposit.sticky_wallet.reference,
        depositId: deposit.id,
        coin: deposit.coin.id, // e.g. "USDT.TRON"
        amount: deposit.net_amount, // or deposit.amount to cover the fee yourself
        txHash: deposit.tx_hash,
      });
    }
    await db.query("UPDATE webhook_events SET processed_at = now() WHERE id = $1", [event.id]);
  }
}

ایررز

400

invalid_request: کوئی فیلڈ موجود نہیں یا غلط ہے؛ پیغام بتاتا ہے کہ کون سا۔

401

unauthorized: سیکرٹ کی موجود نہیں یا درست نہیں۔

403

sticky_wallets_unavailable: اس کاروبار کے لیے مستقل والٹس آن نہیں ہیں، یا اس کا سیٹ اپ مکمل نہیں ہوا۔

404

not_found: اس ID کا کوئی مستقل والٹ موجود نہیں۔

اچھے طریقے

• کسٹمر کے اکاؤنٹ میں رقم صرف deposit.confirmed پر شامل کریں، اور ہر ڈپازٹ id کے لیے صرف ایک بار: ایک webhook ایک سے زیادہ بار آ سکتا ہے۔
• طے کریں کہ فیس کون دے گا: فیس کسٹمر پر ڈالنے کے لیے net_amount شامل کریں، یا خود برداشت کرنے کے لیے amount۔
• آپ کا ریفرنس ہی اصل کنجی ہے: POST /sticky-wallets کو دوبارہ کال کرنا ہمیشہ محفوظ ہے، اس لیے آپ کو ایڈریسز محفوظ کرنے کی ضرورت نہیں۔
• سیکرٹ کی اپنے سرور پر رکھیں۔ اگر یہ لیک ہو جائے تو ڈیولپرز میں اسے منسوخ کریں اور نئی کی بنائیں۔
• اگر آپ کا اینڈ پوائنٹ بند رہا ہو تو confirmed ڈپازٹس کی فہرست لیں اور جو ابھی تک ہینڈل نہیں کیے ان کی رقم شامل کریں۔
• اپنے کسٹمرز کے لیے بیلنس بنا رہے ہیں؟ پڑھیں کسٹمر اکاؤنٹس میں کرپٹو ٹاپ اپ کیسے شامل کریں۔