Deposit Addresses - XentFi API Documentation

Overview

Why Use Deposit Addresses?

🎯 Payment Tracking

Each address is unique per customer or invoice, making it easy to identify who paid and for what

🔄 Automated Reconciliation

Match incoming payments to specific customers automatically without manual intervention

🔒 Privacy & Security

Customers don’t share addresses; each transaction uses a unique address for better privacy

📊 Analytics

Track payment behavior per customer, identify trends, and optimize your payment flow

How It Works

Use Cases

Per-Customer Addresses

Assign a permanent deposit address to each customer for recurring payments:

Use Case	Benefit
Subscription billing	Same address for all subscription payments
VIP customers	Faster checkout experience
Business accounts	Easy reconciliation per client

Per-Invoice Addresses

Generate a unique address for every invoice:

Use Case	Benefit
One-time payments	Clear payment-to-invoice mapping
Marketplace settlements	Track which order paid
Event tickets	Match payment to specific attendee

Refund Addresses

Whitelist addresses for processing refunds:

Use Case	Benefit
Customer refunds	Pre-verified addresses only
Exchange withdrawals	Secure withdrawal destinations
Partner payouts	Automated distribution

Creating Deposit Addresses

Basic Creation

curl -X POST https://api.xentfi.com/v1/addresses \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "masterId": "your-master-wallet-id",
    "name": "Customer: john@example.com"
  }'

{
    "data": {
        "id": "addr_123e4567-e89b-12d3-a456-426614174000",
        "name": "Customer: john@example.com",
        "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
        "masterWalletId": "your-master-wallet-id",
        "blockchain": {
            "id": "eth-mainnet",
            "name": "Ethereum",
            "chainId": 1
        },
        "createdAt": "2024-01-15T10:30:00.000Z"
    }
}

Address Lifecycle

Whitelisting External Addresses

For addresses you own (exchange accounts, other wallets), you can whitelist them:

curl -X POST https://api.xentfi.com/v1/addresses/whitelist \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "masterId": "your-master-wallet-id",
    "walletAddress": "0xExternalAddress...",
    "name": "Binance Withdrawal Address"
  }'

Benefits of Whitelisting

Benefit	Description
✅ Security	Prevents sending to unauthorized addresses
✅ Faster withdrawals	Pre-approved addresses skip verification
✅ Audit trail	Track all withdrawal destinations
✅ Compliance	Meet regulatory requirements

Address Monitoring

Enable Monitoring

Get real-time notifications when your deposit address receives funds:

curl -X POST https://api.xentfi.com/v1/addresses/{addressId}/monitoring/enable \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "blockchainId": "eth-mainnet"
  }'

What Gets Tracked

Event	Description	Webhook Event
Payment received	First confirmation	`payment.detected`
Payment confirmed	Block confirmation	`payment.confirmed`
Payment completed	Settlement finalized	`payment.completed`
Payment failed	Transaction failed	`payment.failed`

Transaction History

View all transactions for a specific deposit address:

curl -X GET https://api.xentfi.com/v1/addresses/{addressId}/transfers \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -G \
  -d "pageSize=20" \
  -d "order=DESC"

Address Management Best Practices

Naming Convention: Use consistent naming like customer_{email} or invoice_{id}
Metadata: Store additional info (customer ID, order ID) in metadata field
Monitoring: Enable for all production addresses
Retention: Keep address records for audit purposes
Cleanup: Deactivate unused addresses periodically

Address vs Payment Link

Feature	Deposit Address	Payment Link
Best for	Recurring customers, API integration	One-time payments, marketing campaigns
Customer experience	Copy/paste address	Hosted payment page
Payment methods	Crypto only	Crypto + Wallet Connect
Tracking	Per address	Per link
QR code	Can generate manually	Auto-generated
Expiration	Permanent	Configurable

Reconciliation Strategies

Per-Customer Strategy

Per-Invoice Strategy

Security Considerations

Risk	Mitigation
Address reuse	Generate new addresses per customer/invoice
Typo errors	Validate addresses before whitelisting
Phishing	Use consistent naming and verification
Key compromise	Rotate API keys, monitor suspicious activity
Wrong network	Display network warnings to customers

Dashboard View

The deposit addresses dashboard shows all your addresses with real-time status.

Common Patterns

E-commerce Checkout

Customer places order
Create deposit address with order ID in name
Display address to customer
Monitor for payment
Update order status on webhook

Subscription Billing

Customer signs up
Create permanent deposit address for customer
Store address in customer profile
Customer uses same address for all payments
Webhook triggers subscription renewal

Crypto Payroll

Employee onboarded
Whitelist employee’s personal wallet
Set up auto-settlement to whitelisted address
Payroll automatically distributed

Troubleshooting

Address not receiving payments

Possible causes:

Wrong network selected
Address not activated
Blockchain congestion

Solutions:

Verify network matches sender’s network
Check address status in dashboard
Wait for block confirmations

Webhook not triggered

Possible causes:

Monitoring not enabled
Webhook URL not configured
Network issues

Solutions:

Enable monitoring for the address
Verify webhook configuration
Check webhook logs

Wrong amount received

Possible causes:

Sender sent wrong amount
Decimal place confusion
Gas fee deduction

Solutions:

Verify expected amount
Check token decimals
Review transaction details

Performance Metrics

Metric	Target	Description
Address creation time	< 1 second	Time to generate new address
Payment detection	< 10 seconds	Time to detect incoming payment
Confirmation time	Network dependent	Time for block confirmations
Webhook delivery	< 5 seconds	Time to send webhook notification

Pricing & Limits

Plan	Max Addresses	Monitoring	Support
Starter	100	Basic	Email
Professional	1,000	Advanced	Priority
Business	10,000	Premium	Dedicated
Enterprise	Unlimited	Custom	24/7

Master Wallets

Parent wallet management and treasury

Payment Links

Hosted payment pages for one-time payments

Webhooks

Real-time payment notifications

Next Steps

Set up webhooks for real-time payment notifications
Configure auto-settlement for automatic fund distribution
Review API Reference for complete endpoint documentation

Documentation Index

​Overview

​Why Use Deposit Addresses?

🎯 Payment Tracking

🔄 Automated Reconciliation

🔒 Privacy & Security

📊 Analytics

​How It Works

​Use Cases

​Per-Customer Addresses

​Per-Invoice Addresses

​Refund Addresses

​Creating Deposit Addresses

​Basic Creation

​Address Lifecycle

​Whitelisting External Addresses

​Benefits of Whitelisting

​Address Monitoring

​Enable Monitoring

​What Gets Tracked

​Transaction History

​Address Management Best Practices

​Address vs Payment Link

​Reconciliation Strategies

​Per-Customer Strategy

​Per-Invoice Strategy

​Security Considerations

​Dashboard View

​Common Patterns

​E-commerce Checkout

​Subscription Billing

​Crypto Payroll

​Troubleshooting

​Performance Metrics

​Pricing & Limits

​Related Products

Master Wallets

Payment Links

Webhooks

​Next Steps

Overview

Why Use Deposit Addresses?

How It Works

Use Cases

Per-Customer Addresses

Per-Invoice Addresses

Refund Addresses

Creating Deposit Addresses

Basic Creation

Address Lifecycle

Whitelisting External Addresses

Benefits of Whitelisting

Address Monitoring

Enable Monitoring

What Gets Tracked

Transaction History

Address Management Best Practices

Address vs Payment Link

Reconciliation Strategies

Per-Customer Strategy

Per-Invoice Strategy

Security Considerations

Dashboard View

Common Patterns

E-commerce Checkout

Subscription Billing

Crypto Payroll

Troubleshooting

Performance Metrics

Pricing & Limits

Related Products

Next Steps