> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streambird.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets Overview

MoonKey provides wallet infrastructure that empowers users to transact on Ethereum, Solana, and all EVM- and SVM-compatible blockchains. Create self-custodial embedded wallets for your users that are directly integrated into your application—no browser extensions or separate wallet apps required.

These embedded wallets can be automatically created during user authentication or manually created when needed, giving you complete flexibility in how you onboard users to web3. Users maintain full custody of their wallets without needing to manage seed phrases or private keys, though they can export their keys at any time for maximum portability.

<Info>
  MoonKey embedded wallets use distributed key sharding to ensure only the rightful owner can control their wallet or access its keys. Neither MoonKey nor your application ever sees the user's complete private key.
</Info>

## Embedded wallets

MoonKey's embedded wallet system lets you build self-custodial wallets directly into your app. Users get a seamless blockchain experience without the technical complexity of traditional wallet management.

### How it works

When a user authenticates with your app, MoonKey can automatically create an embedded wallet for them based on your configuration. The wallet's private key is securely sharded across multiple locations using distributed key management, ensuring that:

* **Users maintain full custody** - Only the user can access their complete private key
* **No seed phrase management** - Users don't need to write down or remember recovery phrases
* **Seamless experience** - Wallets work instantly without any setup
* **Maximum portability** - Users can export their private key at any time

### Key features

<CardGroup cols={2}>
  <Card title="Multi-chain Support" icon="link">
    Create and manage wallets on Ethereum, Solana, and all EVM/SVM-compatible chains including Base, Polygon, Arbitrum, and more.
  </Card>

  <Card title="Self-custodial" icon="shield-check">
    Users have complete control over their wallets. Private keys are securely sharded and only reconstituted for signing operations.
  </Card>

  <Card title="Automatic Creation" icon="sparkles">
    Configure wallets to be created automatically when users log in, or create them manually when needed.
  </Card>

  <Card title="Easy Transactions" icon="paper-plane">
    Simple APIs for sending transactions, signing messages, and interacting with smart contracts.
  </Card>

  <Card title="Export Keys" icon="key">
    Users can export their private keys to use their wallet in other applications like MetaMask or Phantom.
  </Card>

  <Card title="UI Components" icon="window-maximize">
    Pre-built UI components for signing, transactions, and key export with full customization options.
  </Card>
</CardGroup>

## User wallets

MoonKey specializes in creating self-custodial embedded wallets for your users. This means users have a blockchain wallet experience that feels native to your application.

### Benefits for users

**No technical complexity**

* No seed phrases to write down or store
* No browser extensions to install
* No separate apps to download
* Seamless authentication and wallet access

**Full ownership**

* Complete control over their assets
* Ability to export private keys
* Freedom to move to other wallets
* Self-custodial by default

**Instant onboarding**

* Wallets created in seconds
* No blockchain knowledge required
* Start transacting immediately
* Familiar login methods (email, OAuth)

### Benefits for developers

**Simple integration**

* Easy-to-use React SDK
* Pre-built UI components
* Comprehensive REST API
* TypeScript support

**Flexible configuration**

* Automatic or manual wallet creation
* Customizable UI components
* Multiple authentication methods
* Support for multiple chains

**Production ready**

* Secure key management
* High uptime and reliability
* Transaction broadcasting
* Error handling

## Wallet creation

MoonKey offers two approaches to wallet creation:

### Automatic wallet creation

Configure MoonKey to automatically create wallets when users authenticate:

```tsx theme={null}
import { MoonKeyProvider } from '@moon-key/react-auth';

<MoonKeyProvider
  publishableKey="your_publishable_key"
  config={{
    embeddedWallets: {
      createOnLogin: 'always' // Automatically create wallet for every user
    }
  }}
>
  {children}
</MoonKeyProvider>
```

**When to use:**

* Your app requires all users to have a wallet
* You want the simplest onboarding experience
* Users will interact with blockchain features immediately

Learn more about [automatic wallet creation](/get-started/frontend-sdks/react/advance/automatic-wallet-creation).

### Manual wallet creation

Create wallets programmatically when needed:

```tsx theme={null}
import { useCreateWallet } from '@moon-key/react-auth/ethereum';

function CreateWalletButton() {
  const { createWallet } = useCreateWallet();
  
  const handleCreate = async () => {
    const wallet = await createWallet();
    console.log('Wallet created:', wallet.address);
  };
  
  return <button onClick={handleCreate}>Create Wallet</button>;
}
```

**When to use:**

* Not all users need a wallet
* Users opt-in to blockchain features
* You want to delay wallet creation for UX reasons

## Multi-chain support

MoonKey wallets work across multiple blockchain ecosystems:

### Ethereum and EVM chains

Create wallets compatible with:

* **Ethereum** - Mainnet and testnets
* **Layer 2s** - Base, Arbitrum, Optimism, Polygon
* **Sidechains** - Polygon, Gnosis Chain, and more
* **Custom EVMs** - Any EVM-compatible network

```tsx theme={null}
import { MoonKeyProvider } from '@moon-key/react-auth';
import { base, polygon, arbitrum } from 'viem/chains';

<MoonKeyProvider
  publishableKey="your_publishable_key"
  config={{
    supportedChains: [base, polygon, arbitrum]
  }}
>
  {children}
</MoonKeyProvider>
```

### Solana and SVM chains

Create wallets compatible with:

* **Solana** - Mainnet, Devnet, Testnet
* **Custom SVM** - SVM-compatible networks

```tsx theme={null}
import { MoonKeyProvider } from '@moon-key/react-auth';

<MoonKeyProvider
  publishableKey="your_publishable_key"
  config={{
    solana: {
      rpcs: {
        'solana:mainnet': {
          rpc: 'https://api.mainnet-beta.solana.com',
          rpcSubscriptions: 'wss://api.mainnet-beta.solana.com'
        }
      }
    }
  }}
>
  {children}
</MoonKeyProvider>
```

Learn more about [configuring networks](/get-started/frontend-sdks/react/advance/configure-evm-networks).

## Wallet operations

MoonKey provides simple APIs for common wallet operations:

### Sign messages

Sign arbitrary messages for authentication or verification:

```tsx theme={null}
import { useSignMessage } from '@moon-key/react-auth/ethereum';

const { signMessage } = useSignMessage();

const result = await signMessage({
  message: 'Welcome to MyApp!',
  wallet: user.wallet
});
```

### Sign transactions

Sign transactions without broadcasting them:

```tsx theme={null}
import { useSignTransaction } from '@moon-key/react-auth/ethereum';

const { signTransaction } = useSignTransaction();

const result = await signTransaction({
  transaction: {
    to: '0xRecipient...',
    value: '0x38d7ea4c68000'
  },
  wallet: user.wallet
});
```

### Send transactions

Sign and broadcast transactions in one step:

```tsx theme={null}
import { useSendTransaction } from '@moon-key/react-auth/ethereum';

const { sendTransaction } = useSendTransaction();

const result = await sendTransaction({
  transaction: {
    to: '0xRecipient...',
    value: '0x38d7ea4c68000'
  },
  wallet: user.wallet
});

console.log('Transaction hash:', result.transactionHash);
```

### Export private key

Allow users to export their private key:

```tsx theme={null}
import { useExportPrivateKey } from '@moon-key/react-auth/ethereum';

const { exportPrivateKey } = useExportPrivateKey();

await exportPrivateKey({
  wallet: user.wallet,
  uiConfig: {
    title: 'Export Private Key',
    privateKeyDescription: 'Your private key provides full access to your wallet'
  }
});
```

Learn more about [wallet operations](/authentication/user-authentication/ui-components/overview).

## UI components

MoonKey provides pre-built UI components for all wallet operations:

<CardGroup cols={3}>
  <Card title="Sign Message" icon="signature" href="/authentication/user-authentication/ui-components/sign-message">
    Message signing interface
  </Card>

  <Card title="Sign Transaction" icon="file-signature" href="/authentication/user-authentication/ui-components/sign-transaction">
    Transaction signing UI
  </Card>

  <Card title="Send Transaction" icon="paper-plane" href="/authentication/user-authentication/ui-components/send-transaction">
    Transaction sending interface
  </Card>

  <Card title="Export Key" icon="key" href="/authentication/user-authentication/ui-components/export-key">
    Private key export UI
  </Card>
</CardGroup>

All UI components are fully customizable to match your brand. Learn more about [UI components](/authentication/user-authentication/ui-components/overview).

## Headless wallet operations

For complete control over your UI, use MoonKey's headless wallet operations. Build custom interfaces while MoonKey handles the security and blockchain complexity.

Learn more about [whitelabel wallet operations](/wallet-as-a-service/whitelabel/overview).

## Security and custody

MoonKey wallets are designed with security as the top priority:

### Distributed key sharding

Private keys are split into multiple shards that are distributed across different secure locations. The complete key is only reconstituted in a secure environment when needed for signing operations.

**Benefits:**

* No single point of failure
* Neither MoonKey nor your app sees complete keys
* Users maintain full custody
* Resistant to common attack vectors

### User control

Users have complete control over their wallets:

* **Self-custodial** - Users own their keys, not MoonKey or your app
* **Exportable** - Users can export private keys at any time
* **Portable** - Use exported keys in any compatible wallet
* **No lock-in** - Users can leave your platform with their assets

### Secure operations

All wallet operations follow security best practices:

* **Transaction signing** - Performed in secure environments
* **Key storage** - Encrypted and sharded across locations
* **API authentication** - Secure session tokens and API keys
* **User confirmation** - Clear UI for approving operations

## Common use cases

### Gaming

Create wallets for gamers to own in-game assets:

* Automatically create wallets on signup
* Seamless NFT minting and trading
* In-game token transactions
* Cross-game asset portability

### DeFi applications

Enable users to interact with DeFi protocols:

* Swap tokens
* Provide liquidity
* Stake assets
* Yield farming

### NFT marketplaces

Let users buy, sell, and trade NFTs:

* Mint NFTs directly in your app
* List items for sale
* Make offers and bids
* Transfer NFTs between wallets

### Social applications

Add blockchain features to social apps:

* Token-gated communities
* Reward systems
* Tipping and micropayments
* Proof of ownership

### E-commerce

Accept crypto payments seamlessly:

* Checkout with crypto
* Issue refunds
* Loyalty tokens
* Gift cards and vouchers

## REST API

For server-side wallet management, MoonKey provides a comprehensive REST API:

```bash theme={null}
# Create a wallet
curl -X POST https://api.moonkey.fun/v1/wallets/create \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_type": "ethereum",
    "user_id": "user_123"
  }'
```

Learn more about the [REST API](/get-started/rest-api/setup).

## Comparison with external wallets

| Feature             | MoonKey Embedded Wallets      | External Wallets (MetaMask, Phantom) |
| ------------------- | ----------------------------- | ------------------------------------ |
| **Setup**           | Automatic, no installation    | Requires browser extension or app    |
| **User experience** | Seamless, built into your app | Separate popup/app                   |
| **Custody**         | Self-custodial by user        | Self-custodial by user               |
| **Seed phrases**    | Optional (can export key)     | Required for user to manage          |
| **Onboarding**      | Instant, with email/OAuth     | Must have wallet already             |
| **UX control**      | Full control over UI          | Limited customization                |
| **Cross-device**    | Works anywhere user logs in   | Requires extension on each device    |

<Tip>
  You can support both embedded and external wallets in the same app. Let users choose their preferred wallet experience.
</Tip>

## Best practices

<AccordionGroup>
  <Accordion title="Choose the right creation strategy">
    * Use automatic creation for apps where all users need wallets
    * Use manual creation for apps with optional blockchain features
    * Consider user onboarding flow and experience
  </Accordion>

  <Accordion title="Communicate wallet ownership">
    * Clearly explain that users own their wallets
    * Show how to export private keys
    * Explain what self-custodial means
    * Provide wallet security education
  </Accordion>

  <Accordion title="Handle errors gracefully">
    * Show clear error messages for failed transactions
    * Explain insufficient balance errors
    * Guide users on how to fund wallets
    * Provide transaction status updates
  </Accordion>

  <Accordion title="Test on testnets first">
    * Use Sepolia (Ethereum) or Devnet (Solana) for development
    * Test all transaction flows thoroughly
    * Verify gas estimation and fees
    * Check error handling scenarios
  </Accordion>

  <Accordion title="Optimize for mobile">
    * Test wallet operations on mobile devices
    * Ensure UI is responsive
    * Consider mobile network speeds
    * Provide mobile-friendly interfaces
  </Accordion>
</AccordionGroup>

## Get started

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/get-started/frontend-sdks/react/installation">
    Install the MoonKey React SDK
  </Card>

  <Card title="Setup" icon="gear" href="/get-started/frontend-sdks/react/setup">
    Configure MoonKey in your app
  </Card>

  <Card title="Quickstart" icon="rocket" href="/get-started/frontend-sdks/react/quick-start">
    Build your first wallet integration
  </Card>

  <Card title="Automatic Wallet Creation" icon="sparkles" href="/get-started/frontend-sdks/react/advance/automatic-wallet-creation">
    Configure automatic wallet creation
  </Card>

  <Card title="UI Components" icon="window-maximize" href="/authentication/user-authentication/ui-components/overview">
    Use pre-built wallet UI components
  </Card>

  <Card title="REST API" icon="code" href="/get-started/rest-api/setup">
    Manage wallets from your backend
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Configure Networks" icon="globe" href="/get-started/frontend-sdks/react/advance/configure-evm-networks">
    Set up custom networks and RPC providers
  </Card>

  <Card title="Wallet Operations" icon="screwdriver-wrench" href="/authentication/user-authentication/ui-components/overview">
    Learn about signing and transactions
  </Card>

  <Card title="Headless Wallets" icon="code" href="/wallet-as-a-service/whitelabel/overview">
    Build custom wallet UIs
  </Card>

  <Card title="Security Best Practices" icon="shield-check" href="/authentication/overview">
    Secure your wallet integration
  </Card>
</CardGroup>