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"
    }
}

Best Practices

Address Management

Naming Convention

Use consistent naming patterns to easily identify addresses:

customer_{customerId} for recurring customers
invoice_{invoiceId} for one-time invoices
order_{orderId} for e-commerce orders
refund_{transactionId} for refund addresses

Metadata Usage

Store additional information in the metadata field:

Customer email or ID
Order or invoice reference
Product or service details
Tags for categorization
Internal tracking codes

Address Lifecycle

Monitor address activity regularly
Deactivate addresses that are no longer in use
Keep inactive addresses for audit purposes
Archive old addresses after 12 months of inactivity
Never reuse the same address for different customers

Security

Enable monitoring for all production addresses
Set up webhook alerts for large transactions
Validate all addresses before whitelisting
Regularly audit address configurations
Implement IP whitelisting for API access

Monitoring Best Practices

Enable Monitoring

Always enable monitoring for production addresses:

curl -X POST https://api.xentfi.com/v1/addresses/{addressId}/monitoring/{blockchainId}/enable \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id"

Alert Configuration

Set up notifications for large transactions
Monitor for unusual activity patterns
Configure alerts for failed transactions
Track address balance thresholds

Get Address Balance

Check the token balance of any deposit address:

curl -X GET https://api.xentfi.com/v1/addresses/{addressId}/balance \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -G \
  -d "blockchainIds[]=8a864e95-4b86-423d-9ba4-f4e692ec121e"

const balance = await client.getAddressTokenBalance({
  addressId: 'addr_123e4567',
  blockchainIds: ['8a864e95-4b86-423d-9ba4-f4e692ec121e']
});

console.log('Balance:', balance.data);

balance = client.get_address_token_balance(
  address_id='addr_123e4567',
  blockchain_ids=['8a864e95-4b86-423d-9ba4-f4e692ec121e']
)

print(f"Balance: {balance['data']}")

Balance Response Example

{
    "data": [
        {
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
            "balance": 100.5,
            "usdValue": 100.5,
            "asset": {
                "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "name": "Euro Coin",
                "symbol": "EURC",
                "decimals": 6,
                "address": "0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4"
            },
            "blockchain": {
                "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
                "name": "Base",
                "symbol": "ETH"
            }
        }
    ]
}

Balance Query Parameters

Parameter	Type	Description
`addressId`	string (path)	ID of the deposit address
`blockchainIds`	array (query)	Optional list of blockchain IDs to filter balances

Get 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 "txType=incoming" \
  -d "pageSize=20" \
  -d "order=DESC"

const transfers = await client.listAddressTransfers({
  addressId: 'addr_123e4567',
  txType: 'incoming',
  pageSize: 20,
  order: 'DESC'
});

console.log('Transfers:', transfers.transfer);
console.log('Total:', transfers.totalCount);

transfers = client.list_address_transfers(
  address_id='addr_123e4567',
  tx_type='incoming',
  page_size=20,
  order='DESC'
)

print(f"Transfers: {transfers['transfer']}")
print(f"Total: {transfers['totalCount']}")

Transaction History Response

{
    "transfer": [
        {
            "category": "erc20",
            "blockNum": "18500000",
            "from": "0xSenderAddress...",
            "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
            "value": 100.5,
            "symbol": "EURC",
            "hash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
            "timestamp": "2024-01-15T10:30:00Z",
            "asset": {
                "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "symbol": "EURC",
                "decimals": 6
            }
        }
    ],
    "pageInfo": {
        "hasMore": true,
        "nextCursor": "next_page_token"
    },
    "totalCount": 150
}

Transaction Filtering Options

Parameter	Type	Description
`txType`	string	`incoming` or `outgoing` (default: `to`)
`pageSize`	integer	Number of results per page (default: 10)
`pageKey`	string	Pagination cursor for next page
`order`	string	`ASC` or `DESC` ordering

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": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
    "name": "Binance Withdrawal Address",
    "disableAutoSweep": false,
    "enableGaslessWithdraw": false,
    "enableMonitoring": true,
    "metadata": {
      "source": "exchange",
      "platform": "binance"
    }
  }'

const whitelisted = await client.whitelistDepositAddress({
  masterId: 'your-master-wallet-id',
  walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
  name: 'Binance Withdrawal Address',
  disableAutoSweep: false,
  enableGaslessWithdraw: false,
  enableMonitoring: true,
  metadata: {
    source: 'exchange',
    platform: 'binance'
  }
});

console.log('Address whitelisted:', whitelisted.data);

whitelisted = client.whitelist_deposit_address(
  master_id='your-master-wallet-id',
  wallet_address='0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
  name='Binance Withdrawal Address',
  disable_auto_sweep=False,
  enable_gasless_withdraw=False,
  enable_monitoring=True,
  metadata={
    'source': 'exchange',
    'platform': 'binance'
  }
)

print(f"Address whitelisted: {whitelisted['data']}")

Whitelist Request Parameters

Parameter	Type	Required	Description
`masterId`	string	✅	ID of the master wallet to associate the address with
`walletAddress`	string	✅	Existing blockchain wallet address (EVM format or Solana)
`privatekey`	string	❌	Optional private key for the wallet (EVM or Solana format)
`name`	string	❌	Optional custom name for the deposit address
`disableAutoSweep`	boolean	❌	Disable automatic sweeping of funds to master wallet (default: false)
`enableGaslessWithdraw`	boolean	❌	Enable gasless withdrawals for this address (default: false)
`enableMonitoring`	boolean	❌	Enable blockchain monitoring (default: false)
`metadata`	object	❌	Additional metadata for the address

Whitelist Benefits

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/{blockchainId}/enable \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id"

const result = await client.enableAddressMonitoring({
  addressId: 'addr_123e4567',
  blockchainId: '8a864e95-4b86-423d-9ba4-f4e692ec121e'
});

console.log('Monitoring enabled:', result.message);

result = client.enable_address_monitoring(
  address_id='addr_123e4567',
  blockchain_id='8a864e95-4b86-423d-9ba4-f4e692ec121e'
)

print(f"Monitoring enabled: {result['message']}")

Disable Monitoring

curl -X POST https://api.xentfi.com/v1/addresses/{addressId}/monitoring/{blockchainId}/disable \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id"

What Gets Tracked

Event	Description	Webhook Event
Payment detected	First confirmation	`DEPOSITE_INCOMING_DETECTED`
Swap executed	Swap completed	`SWAP_EXECUTED`
Transfer executed	Transfer completed	`TRANSFER_EXECUTED`
Address created	New deposit address	`DEPOSITE_ADDRESS_CREATED`

Address Lifecycle

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

​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

​Best Practices

​Address Management

​Monitoring Best Practices

​Get Address Balance

​Balance Response Example

​Balance Query Parameters

​Get Transaction History

​Transaction History Response

​Transaction Filtering Options

​Whitelisting External Addresses

​Whitelist Request Parameters

​Whitelist Benefits

​Address Monitoring

​Enable Monitoring

​Disable Monitoring

​What Gets Tracked

​Address Lifecycle

​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

Best Practices

Address Management

Monitoring Best Practices

Get Address Balance

Balance Response Example

Balance Query Parameters

Get Transaction History

Transaction History Response

Transaction Filtering Options

Whitelisting External Addresses

Whitelist Request Parameters

Whitelist Benefits

Address Monitoring

Enable Monitoring

Disable Monitoring

What Gets Tracked

Address Lifecycle

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