> ## 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.

# Wallets API

> Custodial and non-custodial wallet management for the Polkadot network

The Wallets API is the foundation of the Mufi platform. It provides custodial Polkadot wallets for your users — provisioned automatically, secured with Shamir's Secret Sharing, and managed entirely through a REST API. No blockchain knowledge required.

Users can also connect their own non-custodial wallets for an even more trustless experience.

## How It Works

<Steps>
  <Step title="You create a user">
    Call the [Create User](/docs/endpoint/wallets/create-user) endpoint with an email address. Mufi creates the user record immediately.
  </Step>

  <Step title="Mufi provisions a wallet">
    A custodial Polkadot wallet is generated asynchronously. The secret is split using Shamir's Secret Sharing and distributed across isolated custodians — no full secret is ever stored in one place.
  </Step>

  <Step title="You activate the user">
    Call the [Activate User](/docs/endpoint/wallets/activate-user) endpoint. Once active, the user can hold assets, receive products, and attend events.
  </Step>

  <Step title="You interact through the API">
    Issue products, check balances, register for events — all through standard REST endpoints with your API key.
  </Step>
</Steps>

## Base URLs

| Environment    | URL                        |
| -------------- | -------------------------- |
| **Production** | `https://api.mufi.app`     |
| **Staging**    | `https://dev.api.mufi.app` |

<Tip>
  All API Playground examples in these docs use the staging URL. When going live, simply replace `dev.api.mufi.app` with `api.mufi.app`.
</Tip>

## Authentication

All API endpoints require a Bearer token — your API key from the [Mufi Dashboard](https://my.mufi.app).

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer $MUFI_API_KEY" \
    https://api.mufi.app/v1/version
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.mufi.app/v1/version', {
    headers: { 'Authorization': `Bearer ${process.env.MUFI_API_KEY}` }
  });
  ```

  ```python Python theme={null}
  import os, requests

  response = requests.get('https://api.mufi.app/v1/version', headers={
      'Authorization': f'Bearer {os.getenv("MUFI_API_KEY")}'
  })
  ```
</CodeGroup>

<Warning>
  Store your API key in environment variables. Never hardcode it or expose it on the client side. See [Authentication](/docs/wallet-api/authentication) for more details.
</Warning>

## API Key Permissions

API keys have one of two permission levels:

| Permission | Access                                                             |
| ---------- | ------------------------------------------------------------------ |
| **Write**  | Full access — create users, events, products, and modify resources |
| **Read**   | Query-only — fetch users, list events, check balances              |

Write-only endpoints will return `403 Forbidden` if called with a read-only key.

## Conventions

### Request Format

* All request bodies use **JSON** with `Content-Type: application/json`
* V1 endpoints use **snake\_case** for field names
* Prices are **decimal strings** (e.g., `"49.99"`) to avoid floating point issues
* Timestamps are **Unix seconds** (integer)
* IDs are **UUIDs** (v4)

### User Identification

Users can be identified by any of these fields (in priority order):

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

### Pagination

List endpoints accept `page` (1-indexed) and `limit` parameters. Maximum limits vary by endpoint.

## Standard Errors

| Status | Error                   | Description                                                         |
| ------ | ----------------------- | ------------------------------------------------------------------- |
| `400`  | `invalid_request`       | Missing or malformed parameter                                      |
| `401`  | `unauthorized`          | Missing or invalid API key                                          |
| `403`  | `forbidden`             | Insufficient permissions (e.g., read-only key on a write endpoint)  |
| `404`  | `not_found`             | Resource does not exist                                             |
| `422`  | `unprocessable_entity`  | Validation error (e.g., insufficient stock, user already activated) |
| `500`  | `internal_server_error` | Something went wrong on our end                                     |

## Deep Dive

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/wallet-api/authentication">
    API key management, permission levels, and security best practices.
  </Card>

  <Card title="Security Architecture" icon="shield-halved" href="/docs/wallet-api/security">
    How Shamir's Secret Sharing, VPC isolation, and multi-region custodians protect wallet secrets.
  </Card>

  <Card title="Custodians" icon="server" href="/docs/wallet-api/custodians">
    How secret parts are distributed, encrypted, and stored across isolated services.
  </Card>

  <Card title="Bring Your Own Wallet" icon="vault" href="/docs/wallet-api/noncustodial">
    Attach self-managed non-custodial wallets to Mufi accounts.
  </Card>
</CardGroup>