> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rach.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet-as-a-Service (WaaS)

> A programmable HD wallet per customer across 9 chains.

WaaS gives each of your customers a hierarchical-deterministic (HD) wallet with derived
addresses across **BTC, BCH, LTC, ETH, BSC, POL, TRX, SOL and XRP**, live on-chain
balances, transfers, and [24/7 deposit monitoring](/products/wallet-monitoring).
Authenticate with your Payments API key (`X-API-Key`).

<Info>
  Base URL: `https://api.rach.finance/api/v1/` · Auth: `X-API-Key`
</Info>

## 1. Create a customer wallet

One wallet per customer (idempotent per `customer_id`).

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.rach.finance/api/v1/wallet/customers \
    -H "X-API-Key: $RACH_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "customer_id": "cust_001", "word_count": 12 }'
  ```

  ```js Node theme={null}
  const w = await (await fetch("https://api.rach.finance/api/v1/wallet/customers", {
    method: "POST",
    headers: { "X-API-Key": process.env.RACH_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ customer_id: "cust_001", word_count: 12 }),
  })).json();
  ```

  ```python Python theme={null}
  import requests, os
  w = requests.post("https://api.rach.finance/api/v1/wallet/customers",
      headers={"X-API-Key": os.environ["RACH_KEY"]},
      json={"customer_id": "cust_001", "word_count": 12}).json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "wallet_id": 42,
  "customer_id": "cust_001",
  "mnemonic": ["...", "..."],
  "created_at": "2026-08-14T12:00:00Z"
}
```

<Warning>
  The `mnemonic` is returned **once** at creation. It is the customer's recovery phrase —
  store it securely (or hand it to the customer) and never log it.
</Warning>

## 2. Derive a deposit address

Create a receive address on a specific chain. Set `enable_monitoring: true` to have Rach
watch it for deposits and fire webhooks.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.rach.finance/api/v1/wallet/cust_001/derive \
    -H "X-API-Key: $RACH_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "network": "ETH", "enable_monitoring": true }'
  ```

  ```js Node theme={null}
  const addr = await (await fetch("https://api.rach.finance/api/v1/wallet/cust_001/derive", {
    method: "POST",
    headers: { "X-API-Key": process.env.RACH_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ network: "ETH", enable_monitoring: true }),
  })).json();
  ```
</CodeGroup>

```json Response theme={null}
{
  "address": "0xAbC123...",
  "network": "ETH",
  "derivation_path": "m/44'/60'/0'/0/0",
  "index": 0,
  "is_testnet": false,
  "monitored": true,
  "customer_id": "cust_001"
}
```

`network` is one of `BTC BCH LTC ETH BSC POL TRX SOL XRP`. Share `address` with your
customer to receive funds.

## 3. Read live balances

```bash theme={null}
curl https://api.rach.finance/api/v1/wallet/cust_001/balances \
  -H "X-API-Key: $RACH_KEY"
```

```json Response theme={null}
{
  "customer_id": "cust_001",
  "live": true,
  "total": 2,
  "addresses": [
    { "network": "ETH", "address": "0xAbC123...", "currency": "USDT", "balance": "125.50" }
  ]
}
```

## 4. Send crypto out

`amount` is a string; `unit` is `decimal` (whole coins, default) or `base` (wei/satoshi).

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.rach.finance/api/v1/wallet/cust_001/transfer \
    -H "X-API-Key: $RACH_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "network": "ETH",
      "currency": "USDT",
      "to_address": "0xRecipient...",
      "amount": "25.00",
      "unit": "decimal"
    }'
  ```

  ```python Python theme={null}
  import requests, os
  tx = requests.post("https://api.rach.finance/api/v1/wallet/cust_001/transfer",
      headers={"X-API-Key": os.environ["RACH_KEY"]},
      json={"network": "ETH", "currency": "USDT",
            "to_address": "0xRecipient...", "amount": "25.00", "unit": "decimal"}).json()
  print(tx["tx_hash"])
  ```
</CodeGroup>

```json Response theme={null}
{
  "tx_hash": "0x9f8e...",
  "status": "submitted",
  "network": "ETH",
  "currency": "USDT",
  "amount": "25.00",
  "from_address": "0xAbC123...",
  "to_address": "0xRecipient...",
  "fee_amount": "0.42",
  "gas_fee": "0.0003",
  "timestamp": "2026-08-14T12:05:00Z"
}
```

<Note>
  XRP transfers accept a `destination_tag`. For chains that need it, gas/fees are handled
  by Rach and reported back in `fee_amount` / `gas_fee`.
</Note>

## More endpoints

| Endpoint                        | Purpose                                           |
| ------------------------------- | ------------------------------------------------- |
| `GET /wallet/customers`         | List your customer wallets                        |
| `GET /wallet/{id}/addresses`    | All derived addresses for a customer              |
| `GET /wallet/{id}/transactions` | Transaction history                               |
| `POST /wallet/estimate-gas`     | Estimate a transfer's gas before sending          |
| `GET /wallet/{id}/export-key`   | Export a customer's private key (guard carefully) |
| `GET /wallet/earnings`          | Fees you've earned on WaaS transfers              |

Full schemas are in the [Payments API Reference](/api-reference/introduction) under
**WaaS**. Deposits are detected automatically — see [24/7 Monitoring](/products/wallet-monitoring).