API Documentation — WalletIDs.net

Overview

WalletIDs.net is a Wallet Factory + Monitoring Service — non-custodial infrastructure that enables you to programmatically generate blockchain wallets and track payments for customer orders.

What We Do

Generate HD seeds, derive child addresses, deliver private keys, monitor balances, send webhooks on payment detection.

What We Don't Do

Hold keys for spending, execute transactions, sweep funds, manage gas, or custody funds.

E-Commerce & Order Tracking Use Case

Create a master HD wallet for your business. For each customer order, derive a unique payment address linked to the order ID. When the customer pays, receive a webhook notification with the order reference to automatically update shipping status and fulfill the order.

1. Create Master Wallet POST /api/v1/wallet/create → Returns: wallet_id, mnemonic, xpub 2. Derive Address for Order #12345 POST /api/v1/wallet/{wallet_id}/derive Body: { "session_id": "order_12345" } → Returns: unique address + private key 3. Customer Pays to Derived Address → WalletIDs monitors the address 4. Webhook Notification → POST to your webhook URL with session_id: "order_12345" → You update order status and ship the product

Authentication

All API requests require authentication using your account's API key. Include the key in the X-API-Key header with every request.

Request Headers
X-API-Key: wid_sk_live_your_api_key_here
Content-Type: application/json

Keep Your API Key Secret

Never expose your API key in client-side code, public repositories, or logs. Regenerate immediately if compromised.

Base URL

All API endpoints are relative to the following base URL:

Production
https://walletids.net/api/v1/

Rate Limits

API requests are rate-limited based on your subscription tier:

Tier	Requests/min	Burst
Free	10	20
Starter	60	120
Growth	300	600
Scale	1,000	2,000
Enterprise	Custom	Custom

Rate limit information is included in response headers:

Response Headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705329180

HD Wallets (Hierarchical Deterministic)

HD wallets allow you to derive unlimited unique addresses from a single master seed. This is ideal for tracking individual customer orders — each order gets its own payment address, all controlled by one master wallet.

How It Works

Master Wallet

Created with a mnemonic seed and xpub. Can derive billions of child addresses.

Derived Addresses

Each derived address has its own private key but shares the master wallet's xpub.

Session IDs

Link each derived address to your order/session ID for easy payment tracking.

BIP44 Derivation Paths

Network	Derivation Path
Ethereum/Polygon/BSC	`m/44'/60'/0'/0/{index}`
Bitcoin	`m/44'/0'/0'/0/{index}`
Tron	`m/44'/195'/0'/0/{index}`
Solana	`m/44'/501'/0'/0/{index}`
XRP	`m/44'/144'/0'/0/{index}`

Order & Shipping Tracking

WalletIDs.net is designed for businesses that need to track cryptocurrency payments for customer orders. Here's how to implement a complete order tracking workflow:

Step 1: Create a Master Wallet (Once)

POST /api/v1/wallet/create
// Create one master wallet per currency
{
  "network": "ethereum",
  "currency": "USDT",
  "mode": "master",
  "name": "My Store - USDT Payments"
}

Step 2: Derive Address for Each Order

POST /api/v1/wallet/{wallet_id}/derive
// Called when customer initiates checkout
{
  "session_id": "order_12345",
  "metadata": {
    "customer_email": "customer@example.com",
    "amount": "99.99",
    "shipping_address": "123 Main St, City"
  }
}

Step 3: Customer Pays to Derived Address

Display the derived address to your customer. They send payment to this unique address.

Step 4: Receive Webhook Notification

Webhook Payload (payment_detected)
{
  "event": "payment_detected",
  "timestamp": "2026-01-15T14:32:00Z",
  "data": {
    "wallet_id": "wal_abc123",
    "address_id": "addr_def456",
    "session_id": "order_12345",  // Your order ID!
    "transaction": {
      "hash": "0xabc...def",
      "amount": "99.99",
      "currency": "USDT",
      "confirmations": 1
    }
  }
}

Step 5: Update Order & Ship

Use the session_id from the webhook to find the order in your database, mark it as paid, and initiate shipping.

Perfect for E-Commerce

Each customer order gets a unique address. The session_id links payments to orders automatically.

Create Wallet

Create a new master HD wallet for a specific network and currency.

POST /api/v1/wallets

Request Parameters

Parameter	Type	Required	Description
`network`	string	Required	Network: ethereum, polygon, bitcoin, bsc, solana, tron, xrp
`currency`	string	Required	Currency: ETH, USDT, BTC, USDC, EURC, etc.
`mode`	string	Optional	Wallet mode: `standalone` (single address), `master` (HD parent for derivation). Default: standalone
`name`	string	Optional	Friendly wallet name
`external_id`	string	Optional	Your reference ID for correlation (e.g., account_id, order_id)
`webhook_url`	string	Optional	Override account-level webhook URL

Example Request (Standalone Wallet)
curl -X POST https://walletids.net/api/v1/wallets \
  -H "X-API-Key: wid_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "network_key": "ethereum",
    "currency_symbol": "ETH",
    "mode": "standalone",
    "wallet_name": "My Store ETH Wallet"
  }'

Example Request (HD Master Wallet)
curl -X POST https://walletids.net/api/v1/wallets \
  -H "X-API-Key: wid_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "network_key": "ethereum",
    "currency_symbol": "ETH",
    "mode": "master",
    "wallet_name": "My Store HD Master",
    "external_id": "account_12345"
  }'

Success Response (200)
{
  "success": true,
  "data": {
    "wallet_id": "wal_abc123",
    "address": "0x1234...abcd",
    "network": "ethereum",
    "currency": "ETH",
    "wallet_mode": "standalone",
    "credentials": {
      "mnemonic": "word word word ... word",
      "private_key": "0xabc...",
      "xpub": "xpub6CUGRUo...",
      "derivation_path": "m/44'/60'/0'/0/0"
    },
    "created_at": "2026-01-15T14:30:00Z"
  }
}

Store Credentials Securely

The mnemonic and private keys are only returned once at creation time. Store them securely.

Derive Address

Derive a new unique address from an HD wallet. Perfect for generating a payment address for each customer order.

POST /api/v1/wallet/{wallet_id}/derive

Request Parameters

Parameter	Type	Required	Description
`session_id`	string	Optional	Your order/session ID for tracking (recommended)
`metadata`	object	Optional	Custom metadata (order details, customer info)

Success Response (200)
{
  "success": true,
  "data": {
    "address_id": "addr_def456",
    "parent_wallet_id": "wal_abc123",
    "address": "0x5678...efgh",
    "derivation_index": 42,
    "derivation_path": "m/44'/60'/0'/0/42",
    "session_id": "order_12345",
    "credentials": {
      "private_key": "0xdef..."
    },
    "created_at": "2026-01-15T14:32:00Z"
  }
}

Get Wallet

Retrieve details about a specific wallet.

GET /api/v1/wallet/{wallet_id}

List Wallets

List all wallets for your account with optional filters.

GET /api/v1/wallets

Query Parameters

Parameter	Type	Description
`network`	string	Filter by network
`currency`	string	Filter by currency
`limit`	integer	Results per page (default: 50, max: 100)
`offset`	integer	Pagination offset

Get Balance

Get the current balance of a wallet or derived address.

GET /api/v1/wallet/{wallet_id}/balance

Success Response (200)
{
  "success": true,
  "data": {
    "wallet_id": "wal_abc123",
    "address": "0x1234...abcd",
    "balances": [
      {"currency": "ETH", "amount": "0.05", "usd_value": "150.00"},
      {"currency": "USDT", "amount": "100.00", "usd_value": "100.00"}
    ],
    "last_checked": "2026-01-15T14:35:00Z"
  }
}

Disable Wallet

Archive a wallet. Stops monitoring but retains data for records.

DELETE /api/v1/wallet/{wallet_id}

Lookup by External ID

Find a wallet by your external reference ID (e.g., order ID). Useful for checking if a payment address already exists for an order.

GET /api/v1/wallet/lookup?external_id={your_order_id}

Query Parameters

Parameter	Type	Required	Description
`external_id`	string	Required	Your order/session ID set during derive
`parent_wallet_hash`	string	Optional	Filter to specific master wallet

Success Response (200)
{
  "success": true,
  "data": {
    "wallet": {
      "hash": "wal_abc123",
      "wallet_address": "0x5678...efgh",
      "external_id": "order_12345",
      "parent_wallet_hash": "wal_master123",
      "derivation_index": 42
    }
  }
}

Idempotent Derive

The derive endpoint is also idempotent — if you call derive with the same external_id, it returns the existing wallet instead of creating a duplicate.

Balance History

Get historical balance snapshots for a wallet. Useful for tracking payment activity over time.

GET /api/v1/wallet/{wallet_id}/history

Query Parameters

Parameter	Type	Description
`limit`	integer	Max results (default: 50, max: 100)

Success Response (200)
{
  "success": true,
  "data": {
    "wallet_hash": "wal_abc123",
    "history": [
      {
        "balance": "0.05",
        "previous_balance": "0.00",
        "change": "0.05",
        "datetime_recorded": "2026-01-15T14:32:00Z"
      }
    ],
    "count": 1
  }
}

Monitoring Settings

Enable/disable balance monitoring and set polling interval for a wallet.

PUT /api/v1/wallet/{wallet_id}/monitoring

Request Body

Parameter	Type	Description
`enabled`	boolean	Enable or disable monitoring
`interval_seconds`	integer	Polling interval (min: 60, default: 300)

Key Recovery

Recover the private key or mnemonic for a wallet. POST only — GET is not supported. Rate limited to 100 recoveries per hour.

POST /api/v1/wallet/{wallet_id}/recover

Success Response (200)
{
  "success": true,
  "data": {
    "wallet_hash": "wal_abc123",
    "wallet_mode": "master",
    "key_type": "mnemonic",
    "mnemonic": "word word word ... word"
  }
}

Security Notice

Key recovery is logged for audit purposes. Rate limit: 1 recovery per hour per account.

Response by Wallet Type

Wallet Mode	Returns
`standalone`	`private_key`
`master`	`mnemonic` (can derive all children)
`derived`	`private_key` (computed from parent mnemonic)

List Networks

Get a list of all supported blockchain networks.

GET /api/v1/networks

List Currencies

Get currencies available on a specific network.

GET /api/v1/networks/{network}/currencies

Webhook Events

WalletIDs.net sends webhooks for monitoring events (read-only observations):

payment_detected

Sent when balance increases (incoming payment detected).

Webhook Payload
{
  "event": "payment_detected",
  "timestamp": "2026-01-15T14:32:00Z",
  "data": {
    "wallet_address": "0x5678...efgh",
    "wallet_name": "Order Payment Wallet",
    "currency": "ETH",
    "network": "ethereum",
    "amount": "0.05",
    "new_balance": "0.05",
    "external_id": "order_4521",
    // Transaction details
    "tx_hash": "0xabc123def456...",
    "confirmations": 3,
    "from_address": "0x9999...aaaa",
    // USD estimate (informational)
    "amount_usd_estimate": "125.50",
    "fx_rate": "2510.00",
    "fx_source": "getmondo",
    "fx_timestamp": "2026-01-15T14:32:00Z"
  }
}

Note: The amount_usd_estimate is provided for convenience. Use your own FX provider for authoritative pricing.

balance_changed

Sent when balance changes in any direction (increase or decrease).

Webhook Payload
{
  "event": "balance_changed",
  "timestamp": "2026-01-15T14:32:00Z",
  "data": {
    "wallet_address": "0x5678...efgh",
    "wallet_name": "Master Wallet",
    "currency": "ETH",
    "network": "ethereum",
    "old_balance": "1.50",
    "new_balance": "1.55",
    "change": "0.05",
    "direction": "increase",
    // USD estimate (informational)
    "amount_usd_estimate": "125.50",
    "fx_rate": "2510.00",
    "fx_source": "getmondo",
    "fx_timestamp": "2026-01-15T14:32:00Z"
  }
}

Webhook Data Fields

Field	Type	Description
`wallet_address`	string	Blockchain address of the wallet
`wallet_name`	string	User-defined wallet name
`currency`	string	Currency symbol (ETH, BTC, USDT, etc.)
`network`	string	Blockchain network (ethereum, polygon, etc.)
`amount`	string	Payment amount (for payment_detected)
`external_id`	string\|null	Your order/session ID (if set during derive)
`tx_hash`	string\|null	Blockchain transaction hash
`confirmations`	int\|null	Number of block confirmations
`from_address`	string\|null	Sender's blockchain address
`amount_usd_estimate`	string\|null	Estimated USD value at time of detection
`fx_rate`	string\|null	Exchange rate used for USD calculation
`fx_source`	string	Source of FX rate (e.g., "getmondo", "stablecoin")
`fx_timestamp`	string	ISO 8601 timestamp when rate was fetched

Webhook Security

All webhooks include an HMAC-SHA256 signature for verification:

Webhook Headers
X-WalletIDs-Signature: sha256=a1b2c3d4e5f6...
X-WalletIDs-Timestamp: 1705329180

PHP Verification Example

PHP
function verifyWebhookSignature($payload, $signature, $timestamp, $secret) {
    // Reject old timestamps (> 5 minutes)
    if (abs(time() - $timestamp) > 300) {
        return false;
    }
    
    $signedPayload = $timestamp . '.' . $payload;
    $expectedSignature = 'sha256=' . hash_hmac('sha256', $signedPayload, $secret);
    
    return hash_equals($expectedSignature, $signature);
}

Retry Policy

Attempt	Delay	Total Time
1	Immediate	0s
2	30 seconds	30s
3	2 minutes	2m 30s
4	10 minutes	12m 30s
5	1 hour	1h 12m 30s

Error Codes

All errors follow a consistent format:

Error Response
{
  "success": false,
  "error": {
    "code": "INVALID_NETWORK",
    "message": "Network 'foochain' is not supported"
  }
}

Code	HTTP Status	Description
`INVALID_API_KEY`	401	API key missing or invalid
`RATE_LIMITED`	429	Too many requests
`INVALID_NETWORK`	400	Unsupported network
`INVALID_CURRENCY`	400	Currency not available on network
`WALLET_NOT_FOUND`	404	Wallet ID doesn't exist
`NOT_HD_WALLET`	400	Cannot derive from non-HD wallet
`KEY_NOT_STORED`	400	Key recovery unavailable for this wallet
`INSUFFICIENT_QUOTA`	402	Plan limits exceeded

Supported Chains

Chain	HD Support	Native Metadata	Default Mode	Notes
Ethereum	✅ Yes	❌ None	standalone	Use HD child addresses
Polygon	✅ Yes	❌ None	standalone	Use HD child addresses
Bitcoin	✅ Yes	❌ None	standalone	Use HD child addresses
Solana	✅ Yes	❌ None	standalone	Use HD child addresses
Tron	✅ Yes	❌ None	standalone	Use HD child addresses
BSC	✅ Yes	❌ None	standalone	Use HD child addresses
XRP	❌ Single	✅ Destination Tag	standalone	One wallet + tags

HD Wallets for Order Tracking

For e-commerce order tracking, we recommend using HD-capable chains (Ethereum, Polygon, Bitcoin, etc.) where each order gets a unique derived address.

XRP Destination Tags — Your Responsibility

WalletIDs.net issues unique XRP addresses only. Destination tag support is not implemented by WalletIDs.net — that's a payment-routing optimization for your application to handle.

If you want to share one XRP address across multiple customers (to avoid the 10 XRP reserve per address):

Create ONE XRP wallet via WalletIDs.net
Your app generates destination tags (e.g., order IDs)
Display: "Send to rXXX... with memo 12345"
Your app matches incoming payments by tag
WalletIDs.net reports "balance changed" — you handle the rest

Derive Address vs. Destination Tags — What's the Difference?

Derive Address (HD wallets) creates a real, unique blockchain address with its own private key. This is wallet issuance — WalletIDs.net's job.

Destination Tags (XRP/XLM) are just metadata on transactions to a single shared address. This is payment-routing logic — your application's job.

Both achieve the same goal (track payments per customer), but only Derive Address creates something on-chain. WalletIDs.net issues addresses; your app handles payment matching.