Stellar Development Foundation
Muxed accounts, a new type of Stellar account that makes it easy to map a single Stellar address to multiple users, are now live.
At this point, all products and services built on Stellar need to make sure they can validate and send payments to muxed accounts. Additionally, products and services that use a pooled account model should come up with a plan to implement muxed accounts on the receive side to improve user experience and eliminate missing memo problems.
The goal of this FAQ is to give a general overview of muxed accounts, to explain what they are, how they work, and why they're useful, and to outline what you need to do to support them. For technical details, please see the Muxed Accounts documentation.
A muxed account is an account that exists “virtually” under a traditional Stellar account address. It combines the familiar GABC... address with a 64-bit integer ID, and can be used to distinguish multiple “virtual” accounts that share an underlying “real” account. Custodial services generally use muxed accounts to map incoming payments to an internal customer database. Businesses may use muxed accounts to map incoming payments to an invoice or customer account.
Muxed accounts are created from — and act on — an underlying Stellar account. They share many characteristics with the underlying address, but they start with an M rather than a G, and they are 69 characters long rather than 56 (for more on the composition of Stellar addresses, see SEP-23). Once you incorporate muxed account validation into your code, you can use them just like traditional Stellar addresses to make payments or, if you're a cryptocurrency exchange, to handle XLM deposits and withdrawals.
To see how to create and work with muxed accounts, check out the Muxed Account documentation.
There are two different models that applications and services built on Stellar use to handle user accounts: the account-per-user model, in which each user has their own Stellar account, and the pooled account model, in which the application or service uses a single account for multiple users and keeps track of individual user balances in an internal database.
Most custodial services, including cryptocurrency exchanges, use the pooled account model: it's simpler, and reduces overhead since each Stellar account requires a minimum lumen balance. In the past, custodial services used the memo field of a Stellar transaction to map an incoming payment to the corresponding internal customer. Muxed accounts are a way to do the same thing without requiring users to enter a memo manually.
Muxed accounts were implemented back in Protocol 13, and they've existed at the protocol level since the July 2020 network upgrade. However, they were hidden behind a feature flag in the Stellar SDKs until January 10, 2022 to give ecosystem projects time to adjust their code to enable users to send payments to muxed accounts.
Now that muxed accounts are out from behind the feature flag, existing wallets, exchanges, and custodial services that use a pooled account model are introducing muxed accounts into their projects on the receive side, and new custodial products will be built with muxed accounts from day one.
Every product or service built on Stellar needs to allow users to send payments to muxed accounts. If your Stellar integration doesn't recognize muxed accounts, your users will be unable to interact with wallets, exchanges, and custodians that use them. They will want to know why, and you'll start to see a lot of support tickets. It is becoming increasingly important to support sending to them in order to continue to interoperate with the ecosystem.
To support sending to muxed accounts, first ensure that you have downloaded the latest version of any Stellar SDK you use. If you have custom code to validate addresses independent of the validation built into your SDK, make sure to adapt it to incorporate muxed accounts. Once you have done that, the composition and submission of most transactions is pretty much the same as it has always been and is mostly handled by your Stellar SDK.
To integrate muxed accounts on the receive side, you need to create muxed accounts from a primary Stellar account by embedding customer IDs, and map them to your internal customer database. For examples of both send- and receive-side integrations, see the Muxed Accounts documentation, or check out the relevant SDK documentation.
Before muxed accounts, exchanges and other custodial services that use pooled accounts required users to add memos to transactions in order to route payments to the correct account in their internal databases. The biggest problem with relying on memos: user error. People frequently forget to include required memos when submitting transactions, which resulted in lost funds or onerous support calls.
Muxed accounts eliminate the need for memos, and contain a checksum that can be validated like traditional Stellar addresses, so there is a reduced risk of typos. They also allow users or applications to apply memo-like functionality at the operation level, so they can bundle multiple payment operations to multiple muxed accounts into a single transaction, which may be beneficial to some applications.
And while memos can let an application know which sub-account a payment should go to, they can't let an application know which sub-account a payment came from. When a payment from a sub-account needs to be returned, for instance, there’s no way to navigate the last mile: the return may get to the custodial service, but they don't know whose account to credit. By making it possible to identify the sending sub-account, muxed accounts make those kinds of returns easy.
Yes. Traditional "G" accounts will continue to work, and transaction memos will continue to function as they always have. If you have a custodial product or service, you can continue to use the legacy "memo-required" method to map incoming payments to your internal customer database, although doing so means you will continue to deal with the customer confusion and panicked support requests, and that you will fall behind as the rest of the ecosystem improves user experience.
However, even if you decide to stick with the legacy method to handle incoming payments, you will need to enable send-side support for muxed accounts because at some point, your users will want to make outgoing payments (or, as many exchanges think of them, XLM withdrawals) to a wallet or exchange that has implemented muxed accounts on the receive side. If your product or service doesn't know how to work with muxed accounts, you may end up stranded, unable to connect to other Stellar products and services.