Build a Cross-Chain Wallet with BIP39 and HD Derivation in 10 Minutes

Introduction

Building a cross-chain wallet doesn't require a PhD in cryptography or months of development. With FluxRail's stateless wallet helpers and the BIP39 standard, you can generate deterministic wallets that work across 36+ blockchains in minutes. This tutorial walks you through generating mnemonic seeds, deriving hierarchical deterministic (HD) keys, and integrating with FluxRail's Core, Pay, and Liquidity APIs—all with simple curl commands.

Why BIP39 and HD Wallets?

BIP39 defines mnemonic phrases (12, 18, or 24 words) that encode entropy. HD wallets (BIP32) let you derive an unlimited number of child keys from a single seed. Combined, they give users a portable, backup-friendly wallet that works across chains. FluxRail's /api/v1/wallet endpoints handle the heavy lifting: mnemonic generation, derivation, and validation—no external libraries needed.

Step 1: Generate a Mnemonic

Start by creating a 12-word BIP39 mnemonic. Use FluxRail's POST /api/v1/wallet/mnemonic endpoint.

curl -X POST https://api.fluxrail.io/api/v1/wallet/mnemonic \
  -H "X-API-Key: flux_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{"entropy_bits":128}'

Response (truncated):

{
  "mnemonic": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
  "entropy": "00000000000000000000000000000000",
  "language": "english"
}

The entropy_bits field accepts 128 (12 words), 192 (18 words), or 256 (24 words). Save the mnemonic securely—it's your master seed.

Step 2: Derive a Cross-Chain Address

Now derive an address for a specific chain. FluxRail supports EVM (Ethereum, Polygon, etc.), Bitcoin, Solana, and TRON. Use POST /api/v1/wallet/derive with the mnemonic and desired path.

curl -X POST https://api.fluxrail.io/api/v1/wallet/derive \
  -H "X-API-Key: flux_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mnemonic": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
    "path": "m/44\u002760\u00270\u00270/0",
    "coin": "ETH"
  }'

Response:

{
  "address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
  "path": "m/44'/60'/0'/0/0",
  "public_key": "0x...",
  "chain": "ethereum"
}

For Bitcoin, use "coin":"BTC" and path m/44'/0'/0'/0/0. For Solana, "coin":"SOL" with path m/44'/501'/0'/0'. FluxRail returns the address and public key—no private key is exposed (derivation happens server-side in test mode; in production, you can supply your own entropy).

Step 3: Validate a Mnemonic

Before using a user-supplied mnemonic, validate it with POST /api/v1/wallet/validate.

curl -X POST https://api.fluxrail.io/api/v1/wallet/validate \
  -H "X-API-Key: flux_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{"mnemonic": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"}'

Response:

{
  "valid": true,
  "checksum": true,
  "language": "english"
}

Step 4: Monitor Addresses with FluxRail Core

Now that you have addresses, monitor them for incoming transactions. Create a subscription via POST /api/v1/subscriptions.

curl -X POST https://api.fluxrail.io/api/v1/subscriptions \
  -H "X-API-Key: flux_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
    "chain": "ethereum",
    "webhook_url": "https://your-server.com/webhook",
    "events": ["native_transfer", "erc20_transfer"]
  }'

FluxRail will send signed webhooks when transactions occur. You can also monitor multiple addresses with one subscription by using wildcards or creating separate subscriptions.

Step 5: Execute Gas-Free Transfers

With FluxRail Pay, you can send tokens without worrying about gas fees. Use POST /api/v1/transfer with a paymaster sponsor.

curl -X POST https://api.fluxrail.io/api/v1/transfer \
  -H "X-API-Key: flux_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "amount": "10",
    "from": "0xYourAddress",
    "to": "0xRecipientAddress",
    "chain": "polygon",
    "sponsor_gas": true,
    "client_reference_id": "wallet-123"
  }'

Response:

{
  "id": "txn_abc123",
  "status": "pending",
  "gas_sponsored": true
}

Check status with GET /api/v1/transfer/txn_abc123.

Step 6: Swap Assets via Liquidity API

If your wallet needs to convert tokens, use FluxRail Liquidity. First get a quote:

curl -X POST https://api.fluxrail.io/api/v1/liquidity/quote \
  -H "X-API-Key: flux_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_asset": "USDC",
    "from_network": "polygon",
    "to_asset": "USDT",
    "to_network": "ethereum",
    "amount": "100",
    "side": "sell"
  }'

Response includes a quote_id. Execute the swap:

curl -X POST https://api.fluxrail.io/api/v1/liquidity/execute/{quote_id} \
  -H "X-API-Key: flux_test_your_test_key"

FluxRail handles the cross-chain bridging and conversion.

Step 7: Payout to Bank Accounts

Finally, let users cash out. With FluxRail Payouts, convert stablecoins to fiat and send to bank accounts in 75+ countries. First create a customer:

curl -X POST https://api.fluxrail.io/api/v1/payouts/customers \
  -H "X-API-Key: flux_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user-123",
    "email": "user@example.com",
    "individual": {
      "given_name": "Jane",
      "family_name": "Doe"
    }
  }'

Then send a payout:

curl -X POST https://api.fluxrail.io/api/v1/payouts/customers/user-123/send \
  -H "X-API-Key: flux_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "network": "ERC20",
    "amount": "50",
    "dest_currency": "USD",
    "method": "ach",
    "destination": {
      "account_owner_name": "Jane Doe",
      "account_number": "000123456789",
      "routing_number": "110000000",
      "account_type": "checking"
    }
  }'

FluxRail handles compliance, sanctions screening, and settlement.

Conclusion

You've built a cross-chain wallet with BIP39 mnemonic generation, HD derivation, transaction monitoring, gas-free transfers, swaps, and fiat off-ramps—all in under 10 minutes. No SDKs, no complex libraries, just curl and the FluxRail API. Start building today at fluxrail.io.