Master Wallets - XentFi API Documentation

Overview

Key Features

🏦 Central Treasury

Single point of control for all your crypto funds with multi-chain support

🔐 Enterprise Security

Bank-grade security with AES-256 encryption and HSM integration

📊 Real-time Analytics

Live transaction monitoring and comprehensive reporting dashboard

🔄 Auto Settlement

Automated fund distribution based on configurable rules

🌐 Multi-chain

Support for 7+ major blockchains including Ethereum, Base, and Solana

📈 Scalable

Handle thousands of transactions with enterprise-grade infrastructure

Dashboard Overview

The master wallet dashboard provides a comprehensive view of your treasury operations.

Supported Blockchains

Blockchain	Network	Chain ID	Native Token	Avg Block Time	Status
Ethereum	Mainnet	1	ETH	12-15 sec	✅ Live
Base	Mainnet	8453	ETH	2 sec	✅ Live
Polygon	Mainnet	137	POL	2-3 sec	✅ Live
Arbitrum	Mainnet	42161	ETH	0.25 sec	✅ Live
Optimism	Mainnet	10	ETH	2 sec	✅ Live
BNB Chain	Mainnet	56	BNB	3 sec	✅ Live
Solana	Mainnet	1	SOL	0.4 sec	✅ Live

Prerequisites

Before creating a master wallet, ensure you have:

✅ A verified XentFi account
✅ API key and App ID from the dashboard
✅ Selected target blockchain
✅ Understanding of gas fees for your chosen network

Creating a Master Wallet

Via API

curl -X POST https://api.xentfi.com/v1/master-wallets \
-H "apiKey: your-api-key" \
-H "orgId: your-org-id" \
-H "Content-Type: application/json" \
-d '{
"name": "Main Treasury",
"blockchainId": "eth-mainnet",
"description": "Primary business treasury",
"enableMonitoring": true,
"enableGaslessWithdraw": false
}'

Via Dashboard

Navigate to Wallets

Log into your dashboard and click Wallets in the left sidebar.

Create New Wallet

Click the Create Wallet button in the top right corner.

Configure Wallet

Fill in the wallet details:

Name: A descriptive name (e.g., “Production Treasury”)
Blockchain: Select your target blockchain
Description: Optional description
Enable Monitoring: Toggle for transaction alerts

Review and Create

Review your settings and click Create Wallet.

Response Example

{

"data": {
"id": "wallet_123e4567-e89b-12d3-a456-426614174000",
"name": "Main Treasury",
"walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
"description": "Primary business treasury",
"blockchain": {
"id": "eth-mainnet",
"name": "Ethereum",
"symbol": "ETH",
"chainId": 1,
"logoUrl": "https://assets.xentfi.com/chains/eth.svg"
},
"configurations": {
"monitoringConfig": {
"enabledChains": ["eth-mainnet"],
"defaultEnabled": true
}
},
"isActive": true,
"analytics": {
"addressCount": 0,
"paymentLinksCount": 0,
"totalVolume": "0",
"transactionCount": 0
},
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
}

Wallet Management

List All Wallets

curl -X GET https://api.xentfi.com/v1/master-wallets \
-H "apiKey: your-api-key" \
-H "orgId: your-org-id" \
-G \
-d "limit=50" \
-d "offset=0" \
-d "order=DESC"

Get Wallet Details

curl -X GET https://api.xentfi.com/v1/master-wallets/{walletId} \
-H "apiKey: your-api-key" \
-H "orgId: your-org-id"

Update Wallet Configuration

curl -X PUT https://api.xentfi.com/v1/master-wallets/{walletId} \
-H "apiKey: your-api-key" \
-H "orgId: your-org-id" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Treasury Name",
"description": "New description",
"isActive": true
}'

Wallet Analytics Dashboard

The analytics dashboard provides real-time insights:

Metric	Description	Update Frequency
Total Volume	Cumulative transaction volume	Real-time
Transaction Count	Number of processed transactions	Real-time
Active Addresses	Count of active deposit addresses	Daily
Average Transaction Size	Average payment amount	Hourly
Fee Analytics	Gas fees and platform fees	Per transaction
Settlement Activity	Auto-settlement executions	Real-time

Monitoring & Alerts

Enable Monitoring

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

Disable Monitoring

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

Gasless Withdrawals

Enable gasless withdrawals to allow users to withdraw without paying gas fees:

curl -X POST https://api.xentfi.com/v1/master-wallets/{walletId}/gasless/enable \
-H "apiKey: your-api-key" \
-H "orgId: your-org-id"

Gas fees are sponsored by XentFi and billed separately to your account.

Best Practices

Naming Convention: Use descriptive names like “Production Treasury” or “Development Fund”
Monitoring: Enable monitoring for all production wallets
Security: Rotate API keys every 90 days
Backup: Store wallet information securely; we don’t store private keys
Testing: Always test on testnet before mainnet deployment

Wallet Security

Security Feature	Description	Implementation
Private Key Storage	AES-256-GCM encrypted	AWS KMS
Access Control	API key + App ID authentication	Required for all requests
IP Whitelisting	Restrict API access to trusted IPs	Enterprise feature
Audit Logging	Complete transaction history	Automatic
2FA	Two-factor authentication	Dashboard setting

Development vs Production

Aspect	Development	Production
Network	Testnet (Sepolia, Mumbai)	Mainnet
API Keys	Sandbox keys	Production keys
Funds	Faucet tokens (free)	Real cryptocurrency
Monitoring	Optional	Required
Gas Fees	Free	Real (paid by you)
Rate Limits	Higher limits	Standard limits
SLA	Best effort	99.9% uptime guaranteed

Transaction Volume Tiers

Tier	Monthly Volume	Features
Starter	< $10,000	Basic features, standard support
Professional	$10,000 -$ 100,000	Advanced features, priority support
Business	$100,000 -$ 1M	Premium features, dedicated support
Enterprise	> $1M	Custom features, SLA guarantees

Use Cases

E-commerce

Accept crypto payments for online stores with automatic settlement to your treasury

SaaS Subscriptions

Manage recurring crypto payments with subscription billing

Invoice Payments

Generate unique addresses per invoice for easy reconciliation

Crypto Treasury

Centralized management of corporate crypto assets

Integration Examples

E-commerce Checkout

// Example: Create wallet for e-commerce store
const storeWallet = await client.createMasterWallet({
name: 'Online Store Treasury',
blockchainId: 'base-mainnet', // Low gas fees
enableMonitoring: true
});

// Generate deposit address for each order
const orderAddress = await client.createDepositAddress({
masterId: storeWallet.id,
name: `Order #${orderId}`
});

// Display address to customer
return { depositAddress: orderAddress.walletAddress };

Crypto Payroll

// Example: Corporate treasury for payroll
const payrollWallet = await client.createMasterWallet({
name: 'Payroll Treasury',
blockchainId: 'polygon-mainnet', // Fast and cheap
enableMonitoring: true
});

// Set up auto-settlement for payroll
await client.createSettlementRule({
masterId: payrollWallet.id,
destination: employeeWallets,
schedule: 'monthly',
amount: '1000'
});

Troubleshooting

Wallet creation fails with 'Blockchain not supported'

Solution: Verify the blockchain ID is correct. Use list-supported-blockchains endpoint to get valid IDs.

Cannot find wallet

Solution:

Confirm wallet ID is correct
Check if wallet belongs to your app ID
Verify wallet hasn’t been deactivated

Monitoring not working

Solution:

Ensure blockchain webhook is configured
Check if monitoring was properly enabled
Verify webhook URL is accessible

High gas fees

Solution:

Consider using L2 solutions like Base or Polygon
Enable gasless withdrawals for users
Batch transactions when possible

Rate limit exceeded

Solution:

Implement exponential backoff
Cache responses when possible
Upgrade to higher tier plan

Migration to Production

Test on Testnet

Create test wallets on Sepolia or Mumbai testnets

Verify Functionality

Test all wallet operations with test tokens

Generate Production Keys

Create new API keys with production environment

Create Production Wallets

Deploy wallets on mainnet networks

Enable Monitoring

Turn on monitoring for all production wallets

Go Live

Update your application configuration and launch

API Reference

Endpoint	Method	Description
`/v1/master-wallets`	GET	List all master wallets
`/v1/master-wallets`	POST	Create a master wallet
`/v1/master-wallets/{id}`	GET	Get wallet details
`/v1/master-wallets/{id}`	PUT	Update wallet
`/v1/master-wallets/{id}/monitoring/enable`	POST	Enable monitoring
`/v1/master-wallets/{id}/monitoring/disable`	POST	Disable monitoring
`/v1/master-wallets/{id}/balance`	POST	Get token balances
`/v1/master-wallets/{id}/transfers`	GET	List transactions

Support Resources

📧 Email: support@xentfi.com
💬 Discord: Join our community
📚 API Reference: Complete documentation
🐛 Issues: GitHub Issues

Next Steps

Deposit Addresses

Create addresses for customer payments

Auto Settlement

Automate fund distribution

Payment Links

Generate hosted payment pages

Documentation Index

​Overview

​Key Features

🏦 Central Treasury

🔐 Enterprise Security

📊 Real-time Analytics

🔄 Auto Settlement

🌐 Multi-chain

📈 Scalable

​Dashboard Overview

​Supported Blockchains

​Prerequisites

​Creating a Master Wallet

​Via API

​Via Dashboard

​Response Example

​Wallet Management

​List All Wallets

​Get Wallet Details

​Update Wallet Configuration

​Wallet Analytics Dashboard

​Monitoring & Alerts

​Enable Monitoring

​Disable Monitoring

​Gasless Withdrawals

​Best Practices

​Wallet Security

​Development vs Production

​Transaction Volume Tiers

​Use Cases

E-commerce

SaaS Subscriptions

Invoice Payments

Crypto Treasury

​Integration Examples

​E-commerce Checkout

​Crypto Payroll

​Troubleshooting

​Migration to Production

​API Reference

​Support Resources

​Next Steps

Deposit Addresses

Auto Settlement

Payment Links

Overview

Key Features

Dashboard Overview

Supported Blockchains

Prerequisites

Creating a Master Wallet

Via API

Via Dashboard

Response Example

Wallet Management

List All Wallets

Get Wallet Details

Update Wallet Configuration

Wallet Analytics Dashboard

Monitoring & Alerts

Enable Monitoring

Disable Monitoring

Gasless Withdrawals

Best Practices

Wallet Security

Development vs Production

Transaction Volume Tiers

Use Cases

Integration Examples

E-commerce Checkout

Crypto Payroll

Troubleshooting

Migration to Production

API Reference

Support Resources

Next Steps