API Documentation v2 — 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/v2/wallets → Returns: wallet_id, mnemonic, address 2. Derive Address for Order #12345 POST /api/v2/wallet/{wallet_id}/derive Body: { "external_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 external_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/v2/

The v1 base URL (https://walletids.net/api/v1/) remains available for backward compatibility but is no longer recommended for new integrations.

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.

External IDs

Link each derived address to your order ID via external_id for automatic 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/v2/wallets
// Create one master wallet per currency
{
  "network_key": "ethereum",
  "currency_symbol": "USDT",
  "mode": "master",
  "wallet_name": "My Store - USDT Payments"
}

Step 2: Derive Address for Each Order

POST /api/v2/wallet/{wallet_id}/derive
// Called when customer initiates checkout
{
  "external_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_address": "0x5678...efgh",
    "wallet_name": "Order Payment Wallet",
    "external_id": "order_12345",  // Your order ID!
    "currency": "USDT",
    "network": "ethereum",
    "amount": "99.99",
    "new_balance": "99.99",
    "tx_hash": "0xabc...def",
    "confirmations": 1,
    "amount_usd_estimate": "99.98"
  }
}

Step 5: Update Order & Ship

Use the external_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 external_id links payments to orders automatically.

Create Wallet

Create a new wallet (standalone or HD master) for a specific network and currency.

POST /api/v2/wallets

Request Parameters

Parameter	Type	Required	Description
`network_key`	string	Required	Network identifier: `ethereum`, `polygon`, `bitcoin`, `bsc`, `solana`, `tron`, `xrp`
`currency_symbol`	string	Required	Currency symbol: `ETH`, `USDT`, `BTC`, `USDC`, `EURC`, etc.
`mode`	string	Optional	Wallet mode: `standalone` (single address), `master` (HD parent for derivation). Default: `standalone`
`wallet_name`	string	Optional	Friendly wallet name
`external_id`	string	Optional	Your reference ID for correlation (e.g., account_id, order_id)
`metadata`	object	Optional	Arbitrary JSON metadata stored with the wallet

Example Request (Standalone Wallet)
curl -X POST https://walletids.net/api/v2/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/v2/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": "6b2da51fc74d62c9...",
    "name": "My Store ETH Wallet",
    "address": "0x1234...abcd",
    "network": "ethereum",
    "currency": "ETH",
    "mode": "standalone",
    "status": "active",
    "created_at": "2026-01-15T14:30:00Z",
    "credentials": {
      "private_key": "0xabc...",
      "mnemonic": "word word word ... word"
    }
  }
}

Store Credentials Securely

The mnemonic and private keys are only returned once at creation time. Use POST /api/v2/wallet/{id}/recover to retrieve them later.

Derive Address

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

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

Request Parameters

Parameter	Type	Required	Description
`external_id`	string	Optional	Your order/reference ID for tracking (recommended). Makes the call idempotent — submitting the same `external_id` again returns the existing address.
`wallet_name`	string	Optional	Friendly name for this derived address
`metadata`	object	Optional	Custom metadata (order details, customer info)

Example Request
curl -X POST https://walletids.net/api/v2/wallet/{wallet_id}/derive \
  -H "X-API-Key: wid_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345",
    "metadata": { "amount": "99.99", "customer_email": "customer@example.com" }
  }'

Success Response (200)
{
  "success": true,
  "data": {
    "wallet_id": "addr_def456...",
    "address": "0x5678...efgh",
    "network": "ethereum",
    "currency": "USDT",
    "mode": "derived",
    "status": "active",
    "external_id": "order_12345",
    "parent_wallet_id": "6b2da51fc74d62c9...",
    "derivation_index": 42,
    "derivation_path": "m/44'/60'/0'/0/42",
    "created_at": "2026-01-15T14:32:00Z"
  }
}

Idempotent by external_id

If you call derive with the same external_id, the existing derived address is returned instead of creating a duplicate. The response will include "idempotent": true at the top level.

List Derived Addresses

List all child addresses derived from a master HD wallet, with pagination.

GET /api/v2/wallet/{wallet_id}/derived

Query Parameters

Parameter	Type	Description
`limit`	integer	Results per page (default: 50, max: 100)
`offset`	integer	Pagination offset (default: 0)

Success Response (200)
{
  "success": true,
  "data": {
    "master_wallet": {
      "wallet_id": "6b2da51f...",
      "name": "My Store HD Master",
      "next_derivation_index": 3
    },
    "derived_wallets": [
      {
        "wallet_id": "addr_def456...",
        "address": "0x5678...efgh",
        "external_id": "order_12345",
        "derivation_index": 0,
        "derivation_path": "m/44'/60'/0'/0/0",
        "status": "active",
        "created_at": "2026-01-15T14:32:00Z"
      }
    ],
    "pagination": { "total": 3, "limit": 50, "offset": 0 }
  }
}

Get Wallet

Retrieve details about a specific wallet.

GET /api/v2/wallet/{wallet_id}

Success Response (200) — Standalone wallet
{
  "success": true,
  "data": {
    "wallet_id": "6b2da51f...",
    "name": "My Wallet",
    "address": "HavFB1kL...",
    "network": "solana",
    "currency": "USDC",
    "mode": "standalone",
    "status": "active",
    "external_id": null,
    "created_at": "2026-05-27T21:19:56+00:00"
  }
}

For mode: "derived" wallets the response also includes parent_wallet_id, derivation_index, and derivation_path. For mode: "master" wallets the response also includes next_derivation_index.

List Wallets

List all wallets for your account.

GET /api/v2/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

Success Response (200)
{
  "success": true,
  "data": {
    "wallets": [
      {
        "wallet_id": "6b2da51f...",
        "name": "My Store HD Master",
        "address": "0x1234...abcd",
        "network": "ethereum",
        "currency": "ETH",
        "mode": "master",
        "status": "active",
        "external_id": null,
        "created_at": "2026-01-15T14:30:00Z"
      }
    ],
    "counts": { "active": 5, "disabled": 1 }
  }
}

Get Balance

Trigger an on-demand balance check for a wallet.

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

Success Response (200)
{
  "success": true,
  "data": {
    "balance": "0.05",
    "changed": true
  }
}

Update Wallet

Enable or disable a wallet. Disabling stops monitoring but retains all data. A disabled wallet can be re-enabled by setting status back to active.

POST /api/v2/wallets/update

Request Body

Parameter	Type	Required	Description
`wallet_id`	string	Required	The wallet ID to update
`status`	string	Required	`active` or `disabled`

Example Request
curl -X POST https://walletids.net/api/v2/wallets/update \
  -H "X-API-Key: wid_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "6b2da51f...",
    "status": "disabled"
  }'

Success Response (200)
{
  "success": true,
  "data": { "message": "Wallet updated" }
}

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/v2/wallet/{wallet_id}/recover

Success Response (200) — standalone wallet
{
  "success": true,
  "data": {
    "wallet_id": "6b2da51f...",
    "key_type": "private_key",
    "private_key": "f14bcea17b9ec916...",
    "warning": "Store this securely. It will not be shown again unless you request another recovery."
  }
}

Success Response (200) — master wallet
{
  "success": true,
  "data": {
    "wallet_id": "6b2da51f...",
    "key_type": "mnemonic",
    "mnemonic": "very tiny message girl endless theory ...",
    "warning": "Store this securely. It will not be shown again unless you request another recovery."
  }
}

Success Response (200) — derived wallet
{
  "success": true,
  "data": {
    "wallet_id": "addr_def456...",
    "key_type": "private_key",
    "private_key": "3333d12b...",
    "derivation_path": "m/44'/60'/0'/0/42",
    "derivation_index": 42,
    "warning": "Store this securely. It will not be shown again unless you request another recovery."
  }
}

Security Notice

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

Response by Wallet Type

Wallet Mode	key_type	Fields returned
`standalone`	`private_key`	`private_key`
`master`	`mnemonic`	`mnemonic` (can derive all children)
`derived`	`private_key`	`private_key`, `derivation_path`, `derivation_index`

List Networks

Get a list of all active supported blockchain networks.

GET /api/v2/networks

Success Response (200)
{
  "success": true,
  "data": {
    "networks": [
      { "network": "ethereum", "name": "Ethereum" },
      { "network": "solana",   "name": "Solana" }
    ]
  }
}

List Currencies

Get currencies available across all networks, with an optional filter by network.

GET /api/v2/currencies

Query Parameters

Parameter	Type	Description
`network`	string	Filter to currencies available on a specific network (e.g., `?network=solana`)

Example — filter by network
GET /api/v2/currencies?network=solana

Success Response (200)
{
  "success": true,
  "data": {
    "currencies": [
      { "symbol": "USDC", "name": "USD Coin", "decimals": 6 },
      { "symbol": "USDT", "name": "Tether USD", "decimals": 6 }
    ]
  }
}

Balance History

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

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

Query Parameters

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

Success Response (200)
{
  "success": true,
  "data": {
    "wallet_id": "6b2da51f...",
    "history": [
      {
        "balance": "0.05",
        "balance_usd": "125.50",
        "block_number": null,
        "snapshot_source": "monitor",
        "datetime_created": "2026-01-15T14:32:00Z"
      }
    ],
    "count": 1
  }
}

Monitoring Settings

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

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

Request Body

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

Success Response (200)
{
  "success": true,
  "data": {
    "monitoring_enabled": true,
    "monitoring_interval_seconds": 300,
    "last_balance": "0.05",
    "last_balance_check": "2026-01-15T14:35:00Z"
  }
}

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/v2/wallet/lookup?external_id={your_order_id}

Query Parameters

Parameter	Type	Required	Description
`external_id`	string	Required	Your order/reference ID set during wallet creation or derive
`master_wallet`	string	Optional	Filter to a specific master wallet ID

Success Response (200)
{
  "success": true,
  "data": {
    "wallet_id": "addr_def456...",
    "address": "0x5678...efgh",
    "network": "ethereum",
    "currency": "USDT",
    "mode": "derived",
    "status": "active",
    "external_id": "order_12345",
    "parent_wallet_id": "6b2da51f...",
    "derivation_index": 42,
    "created_at": "2026-01-15T14:32:00Z"
  }
}

Idempotent Derive

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

Webhook Settings

Retrieve or update your account-level webhook configuration. Webhooks are delivered to the URL set here for all monitored wallets unless overridden per-wallet.

GET /api/v2/account/webhook

GET Response (200)
{
  "success": true,
  "data": {
    "webhook_url": "https://yoursite.com/webhook",
    "webhook_enabled": true,
    "webhook_events": ["payment_detected", "balance_changed"]
  }
}

PUT /api/v2/account/webhook

Request Body Fields

Field	Type	Description
`webhook_url`	string	Delivery endpoint. Must be HTTPS.
`webhook_enabled`	boolean	Enable or disable webhook delivery globally
`webhook_events`	array	Events to subscribe to: `payment_detected`, `balance_changed`, `test`
`regenerate_secret`	boolean	If `true`, rotates the HMAC signing secret. New secret returned in the response only — store it immediately.

Example PUT Request
curl -X PUT https://walletids.net/api/v2/account/webhook \
  -H "X-API-Key: wid_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://yoursite.com/walletids-webhook",
    "webhook_enabled": true,
    "webhook_events": ["payment_detected", "balance_changed"]
  }'

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/reference ID (if set during derive or create)
`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 return a consistent envelope with "success": false and a plain-string "error" message:

Error Response
{
  "success": false,
  "error": "Invalid API key"
}

HTTP Status	Condition	Typical error string
401	API key missing	`API key required. Use X-API-Key header.`
401	API key invalid	`Invalid API key`
403	Account inactive	`Account is not active`
400	Unsupported or inactive network	`Invalid or inactive network`
400	Currency not on network	`Currency ETH not available on Solana`
400	Network does not support HD	`Network xrp does not support HD derivation`
400	No key stored for wallet	`No private key stored (watch-only)`
400	Derive on non-master wallet	`Wallet not found` or derive error
404	Wallet ID not found	`Wallet not found`
429	Rate limit exceeded (global)	`Rate limit exceeded`
429	Key recovery rate limit (100/hr)	`Rate limit exceeded. Key recovery is limited to 100 per hour.`
405	Wrong HTTP method	`Use GET` / `Use POST` / `Use PUT`
500	Server-side error	`Server error`

Supported Chains

Chain	HD Support	Wallet Creation	Native Metadata	Notes
Solana	✅ Yes	✅ Live	❌ None	Fully operational
Bitcoin	✅ Yes	✅ Live	❌ None	Fully operational
XRP	❌ Single	✅ Live	✅ Destination Tag	One wallet + tags
Ethereum	✅ Yes	⚠️ Pending	❌ None	Key generation not yet implemented
Polygon	✅ Yes	⚠️ Pending	❌ None	Key generation not yet implemented
BSC	✅ Yes	⚠️ Pending	❌ None	Key generation not yet implemented
Tron	✅ Yes	⚠️ Pending	❌ None	Key generation not yet implemented

EVM & Tron Wallet Creation — Not Yet Available

Ethereum, Polygon, BSC, and Tron wallet creation currently returns an "Unsupported network" error. Key generation for EVM-compatible and Tron networks is not yet implemented in the key generation layer. Solana, Bitcoin, and XRP are fully operational. EVM support is on the roadmap.

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.