Sub-wallet derivation

Use the derive API when your platform needs one unique wallet address per user. Each address is deterministically derived from your merchant HD seed at a given index — same index always returns the same address.

This is how platforms like exchanges, savings apps, and payment gateways give every user their own receiving address without creating separate accounts.

Idempotent by design

Calling POST /v1/wallets/derive with the same index twice returns the same TRON and BSC addresses. Nothing is stored in HelaMesh's database — the address is pure math (xpub + index). You own the mapping between your user IDs and HD indexes.

Authentication

All derive endpoints use your secret API key (x-api-key). No OTP required — the API key is the authentication layer for server-to-server calls.

x-api-key: hm_live_…   # or hm_test_…

Server-side only

Never expose your secret API key in client-side code. These endpoints are designed for server-to-server use only.

---

POST /v1/wallets/derive

Derive TRON and BSC addresses at a given HD index.

Body

Field	Type	Required	Notes
index	integer	yes	Non-negative integer. Map your user ID to an index and store it.

Example

node.js

const res = await fetch('https://api.helamesh.com/v1/wallets/derive', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HELAMESH_API_KEY,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ index: 42 }),
});

const wallet = await res.json();
// Store wallet.tron and wallet.bsc against your user

Response

200 OK

{
  "index": 42,
  "tron": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "bsc": "0x4b0897b0513fdc7c541b6d9d7e929c4e5364d2db"
}

---

GET /v1/wallets/derive/:index/balance

Get the current USDT balance at the derived address for a given network.

Query params

Param	Required	Values
network	yes	TRON or BSC

Example

const res = await fetch(
  'https://api.helamesh.com/v1/wallets/derive/42/balance?network=TRON',
  { headers: { 'x-api-key': process.env.HELAMESH_API_KEY } },
);
const { balance } = await res.json();
console.log(`Balance: ${balance} USDT`);

Response

200 OK

{
  "index": 42,
  "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "network": "TRON",
  "balance": "10.50"
}

---

POST /v1/wallets/derive/:index/send

Send USDT from a derived address to any destination. Signed server-side using your merchant seed.

Gas required

The source address must hold enough native gas before calling this endpoint:

• TRON: at least 10 TRX at the source address
• BSC: at least 0.001 BNB at the source address

HelaMesh does not auto-top-up gas on programmatic sends — your platform is responsible for funding gas at derived addresses.

Rate limit

Max 5 sends per minute per merchant via this endpoint. Exceeding this returns 429 Too Many Requests.

Body

Field	Type	Required	Notes
toAddress	string	yes	TRON base58 or BSC hex destination
amount	string	yes	Decimal USDT, up to 6 decimal places (e.g. "10.50")
network	string	yes	"TRON" or "BSC"

Example

const res = await fetch(
  'https://api.helamesh.com/v1/wallets/derive/42/send',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HELAMESH_API_KEY,
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      toAddress: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
      amount: '10.50',
      network: 'TRON',
    }),
  },
);

const result = await res.json();
console.log('txHash:', result.txHash);

Response

200 OK

{
  "ok": true,
  "txHash": "a1b2c3d4e5f6...",
  "network": "TRON",
  "fromAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "toAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "amount": "10.50",
  "index": 42
}

---

Recommended integration pattern

1. User signs up on your platform
   → POST /v1/wallets/derive { index: user.id }
   → Store { userId, hdIndex, tronAddress, bscAddress } in your DB

2. User wants to deposit
   → Show them their tronAddress or bscAddress (QR code is helpful)
   → HelaMesh fires transfer.confirmed to your webhook when funds arrive
   → Your webhook handler looks up user by hdIndex, credits their balance

3. User wants to withdraw
   → POST /v1/wallets/derive/:index/send
   → Verify gas is available at the source address first
   → Return txHash to the user

Use webhooks, not polling

When a deposit arrives at a derived address, HelaMesh fires a transfer.confirmed webhook to your endpoint. This is the reliable way to detect deposits — you get notified only after the required confirmation depth, with full deduplication and retry built in. Polling the balance endpoint works for testing but adds latency and wastes API quota in production.