Developer-Controlled Wallets
Developer-controlled wallets are programmatic wallets you create and manage from your backend. Use them for automated payment processing, token distribution, smart contract interactions, AI-powered transactions, and any workflow that requires on-chain operations without manual user approval.
What can you build with developer-controlled wallets?
| Use Case | Description |
|---|---|
| Payment processing | Accept deposits and process payouts automatically |
| Token distribution | Distribute rewards, airdrops, or loyalty points at scale |
| Smart contract interactions | Execute transactions on behalf of your application |
| AI agents | Enable autonomous agents to make on-chain decisions |
| Gaming | Handle in-game asset transfers and NFT purchases |
| Subscriptions | Automate recurring blockchain payments |
| Transaction sponsorship | Pay fees on behalf of your users |
Key Benefits
| Benefit | Description |
|---|---|
| Full automation | No manual approval needed for transactions |
| Programmatic control | Create, retrieve, and use wallets via API |
| Secure key management | Private keys encrypted with your Entity Secret |
| Self-custody | You control all wallets; UTXOS cannot access funds |
| Multi-chain support | Cardano, Bitcoin, and Spark from a single API |
⚠️
Developer-controlled wallets must be integrated on your backend only. Never expose your Entity Secret or API keys to client-side code.
How are developer-controlled wallets secured?
Developer-controlled wallets use asymmetric encryption to protect private keys:
- You generate a public-private key pair (Entity Secret) in the dashboard
- Wallet creation encrypts each wallet’s private key with your public key
- UTXOS stores only the encrypted private key
- You decrypt using your private key when signing transactions
This means:
- UTXOS cannot access your wallet funds
- Only someone with your Entity Secret can sign transactions
- Losing your Entity Secret means losing access to all wallets
🚫
Critical: Store your Entity Secret private key securely. UTXOS cannot recover lost Entity Secrets. If compromised, an attacker can access all your wallets.
Quick Start
import { Web3Sdk } from "@utxos/sdk";
const sdk = new Web3Sdk({
projectId: process.env.NEXT_PUBLIC_UTXOS_PROJECT_ID,
apiKey: process.env.UTXOS_API_KEY,
privateKey: process.env.UTXOS_PRIVATE_KEY, // Entity Secret
network: "testnet",
});
// Create a new wallet
const walletInfo = await sdk.wallet.createWallet();
console.log(`Created wallet: ${walletInfo.id}`);
// Retrieve and use the wallet
const { cardanoWallet } = await sdk.wallet.getWallet(walletInfo.id, "cardano");
const address = await cardanoWallet.getChangeAddress();
console.log(`Wallet address: ${address}`);Comparison: Developer vs User Wallets
| Aspect | Developer-Controlled | User-Controlled |
|---|---|---|
| Key custody | Developer holds Entity Secret | User holds via Shamir shares |
| Transaction approval | Automatic (programmatic) | Requires user signature |
| Integration | Backend only | Frontend with SDK |
| Use case | Automation, backend services | End-user wallets |
| Recovery | Entity Secret backup | User recovery flow |