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

# Introduction

> Create and manage users with custodial wallets on the Polkadot network

The Users API lets you create, manage, and query users associated with your project. Each user is automatically provisioned a custodial wallet on the Polkadot network using Shamir's Secret Sharing, enabling them to interact with web3 applications through a familiar web2 experience.

## Key Concepts

### User Lifecycle

1. **Creation** — Register users by email (individually or in bulk up to 1,500 per request). A custodial wallet is asynchronously generated for each user.
2. **Activation** — Activate users to enable wallet features such as holding assets, redeeming products, and attending events.
3. **Engagement** — Once active, users can receive product items, register for events, check in at venues, and hold on-chain assets.

### User Identification

Users can be identified in API requests using three methods, applied in the following priority order:

| Priority | Identifier    | Description                                    |
| -------- | ------------- | ---------------------------------------------- |
| 1        | `email`       | The user's unique email address                |
| 2        | `referenceId` | A custom ID to link users to your own database |
| 3        | `id`          | The Mufi-generated UUID                        |

This flexible lookup system means you can integrate seamlessly with your existing user database by mapping your internal IDs via the `referenceId` field.

### Wallets

Each user receives a custodial Polkadot wallet upon creation. Users can also connect their own non-custodial wallets for additional security. Wallets support:

* **On-chain asset balances** — Query token holdings and locked amounts across supported chains
* **Custodial and non-custodial** — Both custody types are returned when fetching user profiles
* **Project-level queries** — Retrieve all wallets across your entire project for reporting

### Batch Operations

The Create User endpoint supports batch creation of up to **1,500 users per request**. Wallet generation happens asynchronously after creation, so users are immediately available in the system while their wallets are being provisioned in the background.

## Available Endpoints

### Users Endpoints

<CardGroup cols={2}>
  <Card title="Create User" icon="user-plus" href="/docs/endpoint/wallets/create-user">
    Register new users (1–1,500 per request) with automatic wallet provisioning.
  </Card>

  <Card title="Fetch User" icon="user" href="/docs/endpoint/wallets/fetch-user">
    Retrieve a single user's profile including wallet addresses and custody types.
  </Card>

  <Card title="Fetch Users" icon="users" href="/docs/endpoint/wallets/fetch-users">
    List multiple users with pagination and optional filtering by email, reference ID, or user ID.
  </Card>

  <Card title="Activate User" icon="user-check" href="/docs/endpoint/wallets/activate-user">
    Activate a user to enable wallet features and product interactions.
  </Card>

  <Card title="Activation Status" icon="circle-check" href="/docs/endpoint/wallets/user-activation-status">
    Check whether a user has been activated and when.
  </Card>

  <Card title="Wallet Balances" icon="wallet" href="/docs/endpoint/wallets/get-wallet-balances">
    Query on-chain asset balances across all of a user's wallets.
  </Card>

  <Card title="User Count" icon="hashtag" href="/docs/endpoint/wallets/get-user-count">
    Get the total number of active users in your project.
  </Card>
</CardGroup>

### Projects Endpoints

<CardGroup cols={2}>
  <Card title="Fetch Wallets" icon="rectangle-list" href="/docs/endpoint/wallets/fetch-wallets">
    Retrieve all wallets across your entire project with wallet type and custody details.
  </Card>
</CardGroup>