Skip to main content
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

1

You create a user

Call the Create User endpoint with an email address. Mufi creates the user record immediately.
2

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

You activate the user

Call the Activate User endpoint. Once active, the user can hold assets, receive products, and attend events.
4

You interact through the API

Issue products, check balances, register for events — all through standard REST endpoints with your API key.

​
Base URLs

EnvironmentURL
Productionhttps://api.mufi.app
Staginghttps://dev.api.mufi.app
All API Playground examples in these docs use the staging URL. When going live, simply replace dev.api.mufi.app with api.mufi.app.

​
Authentication

All API endpoints require a Bearer token — your API key from the Mufi Dashboard. 
curl -H "Authorization: Bearer $MUFI_API_KEY" \
  https://api.mufi.app/v1/version
Store your API key in environment variables. Never hardcode it or expose it on the client side. See Authentication for more details.

​
API Key Permissions

API keys have one of two permission levels:
PermissionAccess
WriteFull access — create users, events, products, and modify resources
ReadQuery-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):
PriorityFieldDescription
1emailThe user’s unique email address
2referenceIdYour custom ID to link users to your own database
3idThe Mufi-generated UUID

​
Pagination

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

​
Standard Errors

StatusErrorDescription
400invalid_requestMissing or malformed parameter
401unauthorizedMissing or invalid API key
403forbiddenInsufficient permissions (e.g., read-only key on a write endpoint)
404not_foundResource does not exist
422unprocessable_entityValidation error (e.g., insufficient stock, user already activated)
500internal_server_errorSomething went wrong on our end

​
Deep Dive

Authentication

API key management, permission levels, and security best practices.

Security Architecture

How Shamir’s Secret Sharing, VPC isolation, and multi-region custodians protect wallet secrets.

Custodians

How secret parts are distributed, encrypted, and stored across isolated services.

Bring Your Own Wallet

Attach self-managed non-custodial wallets to Mufi accounts.