Wallet-as-a-Service (WaaS) Integration Guide

This guide details how to integrate with the Rach Finance Wallet-as-a-Service (WaaS) API. This API allows businesses to generate custodial HD wallets for their customers, derive addresses on multiple blockchains, and execute transfers.

Base URL: https://payments-api-dev-966260606560.europe-west2.run.app/api/v1

Authentication

All requests require a valid API Key in one of these headers:

• Primary: X-API-Key: <your_business_api_key>
• Alternative: Authorization: Bearer <your_business_api_key>
• Restriction: This API is available for Business Accounts only.

---

1. Create Customer Wallet

Creates a new HD Wallet (BIP-44) for a specific customer ID.

• Endpoint: POST /wallet/customer/create
• Description: Generates a master seed for the customer.

Request

{
  "customer_id": "cust_12345",
  "word_count": 12 // Optional: 12 or 24 (default: 12)
}

Response

{
  "customer_id": "cust_12345",
  "wallet_id": 1,
  "mnemonic": ["word1", "word2", "...", "word12"], // Returned ONLY once
  "created_at": "2024-01-01T12:00:00Z"
}

---

2. Derive Address

Derives a new blockchain address for a customer wallet at a specific index.

• Endpoint: POST /wallet/customer/:customerID/derive
• Description: Generates a deposit address for a supported network.

Request

{
  "network": "ETH", // Options: BTC, BCH, LTC, BSC, ETH, POL, TRX, SOL, XRP
  "index": 0,       // HD Wallet address index
  "testnet": false,  // Set true for testnet addresses
  "enable_monitoring": true // Optional: Auto-monitor for deposits
}

Response

{
  "customer_id": "cust_12345",
  "network": "ETH",
  "address": "0x71C...",
  "index": 0,
  "derivation_path": "m/44'/60'/0'/0/0",
  "is_testnet": false,
  "monitored": true
}

---

3. List Addresses

Lists all derived addresses for a customer.

• Endpoint: GET /wallet/customer/:customerID/addresses

Response

{
  "customer_id": "cust_12345",
  "addresses": [
    {
      "network": "ETH",
      "address": "0x71C...",
      "index": 0,
      "monitored": true
    }
  ],
  "total": 1
}

---

4. Get Seed Phrase

Retrieve the mnemonic seed phrase for a customer (Sensitive).

• Endpoint: GET /wallet/customer/:customerID/seed

Response

{
  "customer_id": "cust_12345",
  "mnemonic": ["word1", "word2", "..."],
  "word_count": 12
}

---

5. Estimate Gas

Estimate the gas fee for a transaction.

• Endpoint: POST /wallet/customer/estimate-gas

Request

{
  "network": "ETH",
  "currency": "ETH", // or USDT, USDC
  "from_address": "0x...",
  "to_address": "0x...",
  "amount": "1000000000000000000" // Amount in smallest unit (Wei/Satoshi)
}

Response

{
  "gas_limit": 21000,
  "gas_price": "20000000000",
  "estimated_fee": "0.00042",
  "currency": "ETH"
}

---

6. Execute Transfer

Send crypto from a customer's derived wallet.

• Endpoint: POST /wallet/customer/:customerID/transfer

Request

{
  "network": "ETH",
  "currency": "USDT",
  "to_address": "0xRecipient...",
  "amount": "50000000", // Amount in smallest unit (e.g. 50 USDT = 50 * 10^6)
  "index": 0            // The address index to send FROM
}

Response

{
  "tx_hash": "0x...",
  "status": "pending",
  "network": "ETH",
  "amount": "50.00",
  "fee": "0.002"
}

---

7. Get Transaction History

Retrieve transaction history for a customer wallet.

• Endpoint: GET /wallet/customer/:customerID/transactions?page=1&limit=20&network=ETH

Response

{
  "customer_id": "cust_12345",
  "transactions": [
    {
      "tx_hash": "0x...",
      "amount": "50.00",
      "currency": "USDT",
      "type": "transfer", // or deposit
      "status": "confirmed",
      "created_at": "2024-01-01T12:05:00Z"
    }
  ],
  "total": 10
}