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

# Embed user wallets

> Give each of your users a wallet inside your product, operated by your backend under your policies, with keys held as MPC shares.

A fintech, exchange or wallet app can give every user a digital-asset wallet without ever holding a private key: each user gets an MPC wallet created by your backend, funds move only through your policies, and the user experience is entirely yours.

## What you'll need

* A backend service that owns the user-to-wallet mapping and calls the Wallet API.
* An API key for that service with `wallets:create`, `wallets:read`, `assets:attach`, `balances:read`, `withdrawals:create` and `withdrawals:read`.
* Policies appropriate to user-initiated transfers (limits, whitelists, approval above a threshold).

## Components to configure

| Component     | Role                                                                              |
| :------------ | :-------------------------------------------------------------------------------- |
| **Wallets**   | One MPC wallet per user, created on sign-up or first use.                         |
| **Assets**    | The networks and tokens your product supports, attached per wallet.               |
| **Policies**  | Workspace-level limits and destination rules that apply to every user withdrawal. |
| **Webhooks**  | Deposit and withdrawal events that update the user's view in your app.            |
| **Audit log** | Evidence of every wallet action for disputes and regulators.                      |

## Steps

<Steps>
  <Step title="Create the wallet when the user is onboarded">
    `POST /api/v1/wallets` with `name` set to your user identifier and an `X-Idempotency-Key` derived from it. Store `wallet_id` against the user. Show the user a "setting up" state until `wallet.created` arrives; key generation takes seconds.
  </Step>

  <Step title="Attach assets and show the deposit address">
    Attach the assets your product supports and display the address from the attach response or `GET /api/v1/wallets/{wallet_id}/deposit-address`. On EVM networks one address serves every supported token.
  </Step>

  <Step title="Reflect deposits in the app">
    Subscribe to `deposit.detected` and `balance.updated`; update the user's balance from the event's `wallet_id`. Read the authoritative balance from `GET /api/v1/wallets/{wallet_id}/balance/{asset_id}`.
  </Step>

  <Step title="Send on the user's behalf">
    When the user initiates a transfer in your app, your backend calls `POST /api/v1/wallets/{wallet_id}/request-withdrawal` with an idempotency key tied to the user's action. Policies apply exactly as they do for a treasury withdrawal: destination rules, limits, and approval above a threshold. Surface a rejection reason to the user and a pending state while an approval is outstanding.
  </Step>

  <Step title="Track completion">
    Drive the user-facing status from `withdrawal.submitted`, `withdrawal.confirmed` and `withdrawal.failed`, and show the transaction hash once available.
  </Step>
</Steps>

## Considerations

* These are **organisation-managed** wallets: your workspace, your policies, your backend's key. The user does not hold a key share and cannot transact outside your product. If your regulatory position requires the user to control the key, this solution does not apply.
* Limits and whitelists are configured at workspace level and apply to all wallets; design tiers of users as separate workspaces if they need different rules.
* Keep the wallet-creating service and the withdrawal-requesting service on separate keys where your architecture allows, so a compromise of one does not grant the other's capability.

## Related

* [Automate deposits](/solutions/payments/automate-deposits)
* [Automate payments](/solutions/payments/automate-payments)
* [Wallets & accounts](/wallets/wallets-and-accounts)