Derive a blockchain address

curl --request POST \
  --url https://api.rach.finance/api/v1/wallet/{customerID}/derive \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "enable_monitoring": false,
  "index": 0,
  "is_testnet": false
}
'

import requests

url = "https://api.rach.finance/api/v1/wallet/{customerID}/derive"

payload = {
    "enable_monitoring": False,
    "index": 0,
    "is_testnet": False
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({enable_monitoring: false, index: 0, is_testnet: false})
};

fetch('https://api.rach.finance/api/v1/wallet/{customerID}/derive', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.rach.finance/api/v1/wallet/{customerID}/derive",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'enable_monitoring' => false,
    'index' => 0,
    'is_testnet' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rach.finance/api/v1/wallet/{customerID}/derive"

	payload := strings.NewReader("{\n  \"enable_monitoring\": false,\n  \"index\": 0,\n  \"is_testnet\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.rach.finance/api/v1/wallet/{customerID}/derive")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"enable_monitoring\": false,\n  \"index\": 0,\n  \"is_testnet\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.rach.finance/api/v1/wallet/{customerID}/derive")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"enable_monitoring\": false,\n  \"index\": 0,\n  \"is_testnet\": false\n}"

response = http.request(request)
puts response.read_body

{
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "customer_id": "<string>",
  "derivation_path": "m/84'/0'/0'/0/0",
  "index": 123,
  "is_testnet": true,
  "monitored": true
}

{
  "error": "subscription expired — please renew your plan to continue"
}

WaaS (Wallet-as-a-Service)

Derive a blockchain address

Derives a blockchain address for the specified network at the given BIP-44 index. Set enable_monitoring: true to have the payment monitor watch this address for incoming deposits and push webhooks.

Requires an active subscription. Returns 402 if the plan has expired. Deriving additional addresses for an existing customer wallet does not count against the wallet cap — only creating a new customer wallet does.

Deposit lifecycle (when enable_monitoring: true):

Event	When	Notes
`wallet.deposit.detected`	deposit first seen on-chain	may carry `hash_pending: true`
`wallet.deposit.hash_resolved`	real on-chain tx hash resolved	same `deposit_id`, `tx_hash` now real
`wallet.deposit.confirmed`	block depth / settlement delay met	safe to credit

Idempotency — dedup on deposit_id, NOT tx_hash. Every deposit webhook carries a stable deposit_id; record it and ignore repeats. tx_hash may initially be a placeholder (pending_…) when the real on-chain hash isn’t indexable yet — then hash_pending is true, and a follow-up wallet.deposit.hash_resolved (same deposit_id) arrives later with the real tx_hash. Update the hash on your existing record; never credit a second time.

Addresses are always EIP-55 checksummed for EVM chains (ETH/BSC/POL), matching the casing returned by GET /balances and list addresses. The native BSC coin is BNB (never BSC).

The confirmations field behaviour differs by network:

Network	Confirmation method	`confirmations` value
ETH, BSC, POL	Block depth via `eth_getTransactionReceipt`	Real block count (e.g. `12`)
BTC	Block depth via Esplora API	Real block count (e.g. `6`)
TRX, SOL, LTC, BCH, XRP	Time-based settlement delay	Always `0` even when confirmed

TRX/SOL/LTC/BCH/XRP always emit "confirmations": 0 in the webhook payload — even when status is "confirmed". This is expected: these networks use a settlement delay instead of block depth. Do not treat confirmations: 0 as an error on these networks. Use status === "confirmed" as the authoritative signal, not the confirmations count.

Do not credit customer funds until you receive wallet.deposit.confirmed.

Webhook payload shape:

{
  "event": "wallet.deposit.detected",
  "data": {
    "deposit_id": 4821,             // STABLE idempotency key — dedup on THIS, not tx_hash
    "customer_id": "cus_abc123",
    "network": "TRX",
    "address": "TV8f...",           // EVM addresses are EIP-55 checksummed
    "amount": "8.152212",
    "currency": "USDT",             // native BSC coin is "BNB"
    "tx_hash": "pending_a1b2c3...", // may be a placeholder until resolved
    "hash_pending": true,           // true ⇒ the real hash arrives via hash_resolved
    "confirmations": 0,
    "status": "detected",
    "detected_at": "2026-07-21T04:41:30Z",
    "detected_by": "custom",
    "safe_to_credit": false
  }
}

Follow-up once the real on-chain hash is known (same deposit_id — update, don’t re-credit):

{
  "event": "wallet.deposit.hash_resolved",
  "data": { "deposit_id": 4821, "tx_hash": "9644c5c5...", "hash_pending": false, "status": "detected" }
}

Note: on TRX/SOL/LTC/BCH/XRP confirmations stays 0 even when status is "confirmed" (settlement-delay networks) — use status, not the count.

Reconciling / normalizing your recorded balances: the authoritative source is the chain. To (re)sync one customer, call GET /api/v1/wallet/{customerID}/balances (live, per-currency, with confirmed/spendable) and set your stored balance to it; for a full sweep of every customer use GET /api/v1/wallet/addresses. This corrects both any past double-count and any previously-missed deposit in a single pass. Dedup historical deposits by deposit_id.

Verify webhook authenticity using HMAC-SHA256(rawRequestBody, whsec_secret), hex-encoded — the signature is in the X-Webhook-Signature header (we also send X-Webhook-Event and X-Webhook-ID).

POST

api

wallet

{customerID}

derive

Derive a blockchain address

curl --request POST \
  --url https://api.rach.finance/api/v1/wallet/{customerID}/derive \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "enable_monitoring": false,
  "index": 0,
  "is_testnet": false
}
'

import requests

url = "https://api.rach.finance/api/v1/wallet/{customerID}/derive"

payload = {
    "enable_monitoring": False,
    "index": 0,
    "is_testnet": False
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({enable_monitoring: false, index: 0, is_testnet: false})
};

fetch('https://api.rach.finance/api/v1/wallet/{customerID}/derive', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.rach.finance/api/v1/wallet/{customerID}/derive",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'enable_monitoring' => false,
    'index' => 0,
    'is_testnet' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rach.finance/api/v1/wallet/{customerID}/derive"

	payload := strings.NewReader("{\n  \"enable_monitoring\": false,\n  \"index\": 0,\n  \"is_testnet\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.rach.finance/api/v1/wallet/{customerID}/derive")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"enable_monitoring\": false,\n  \"index\": 0,\n  \"is_testnet\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.rach.finance/api/v1/wallet/{customerID}/derive")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"enable_monitoring\": false,\n  \"index\": 0,\n  \"is_testnet\": false\n}"

response = http.request(request)
puts response.read_body

{
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "customer_id": "<string>",
  "derivation_path": "m/84'/0'/0'/0/0",
  "index": 123,
  "is_testnet": true,
  "monitored": true
}

{
  "error": "subscription expired — please renew your plan to continue"
}

Authorizations

X-API-Key

string

header

required

Business API key for server-to-server integrations. Key prefix determines the environment — no separate flag needed: test_sk_* = sandbox/testnet, live_sk_* = production/mainnet.

Path Parameters

customerID

string

required

Body

application/json

network

enum<string>

required

Available options:

BTC,

BCH,

LTC,

BSC,

ETH,

POL,

TRX,

SOL,

XRP

enable_monitoring

boolean

default:false

Subscribe this address to the payment monitor for deposit detection

index

integer

default:0

is_testnet

boolean

default:false

Response

Derived address

address

string

Example:

"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"

customer_id

string

derivation_path

string

Example:

"m/84'/0'/0'/0/0"

index

integer

is_testnet

boolean

monitored

boolean

network

enum<string>

Available options:

BTC,

BCH,

LTC,

ETH,

BSC,

POL,

TRX,

SOL,

XRP

⌘I

Overview

Checkout (Crypto Gateway)

Swap

WaaS (Wallet-as-a-Service)

Market Data

Derive a blockchain address

Authorizations

Path Parameters

Body

Response