For issuers
Asset metadata
The stellar.toml file, what LumosCore reads from it, and how to publish a logo.
Stellar's convention for asset metadata is a file called stellar.toml, published on
the issuer's own domain at /.well-known/stellar.toml. It is where an issuer states, in
public and under their own control, what their asset is.
LumosCore reads it for two purposes: to display your asset properly, and to verify it.
#The two halves of the handshake
Metadata only means something if both ends agree, so two things must be true at once:
- The issuing account names your domain. Set the account's home domain on the
ledger to the domain hosting your
stellar.toml. - The domain names the asset back. Your
stellar.tomllists the asset code and the exact issuing account address.
Either one alone proves nothing. A home domain can be set to any domain by anyone, and a file can claim any asset. It is the two matching that makes the link real.
#What LumosCore reads
| Field | Used for |
|---|---|
code | Matching the entry to the asset. |
issuer |
The identity check. Must match the account that actually issued the asset. |
name | The display name shown beside the ticker. |
desc |
The description on the asset's page. Write it for someone who has never heard of your project. |
image | The logo shown in lists, pools and the trade view. |
#Hosting it
- Serve it at
https://yourdomain/.well-known/stellar.tomlover HTTPS. - It must be reachable by a browser from another origin — a file behind a login, a firewall or a strict CORS policy cannot be read, and verification will not complete.
- Use the same domain you set as the account's home domain, exactly. A redirect from one host to another is a common reason a handshake does not resolve.
Logos
Use a square image with a transparent background, served over HTTPS from a stable URL. Assets without a usable logo fall back to a generated mark, which works but looks like what it is.
#Changing it later
The file is yours and you can edit it whenever you like. Updates to the description or logo are picked up on the next read; changes are not instant, because responses are cached for a period.
If you change the issuing account, everything changes: it is a different asset as far as Stellar is concerned, and it needs its own entry and its own verification.
Keep control of the domain
Whoever controls the domain controls what your asset appears to be. Letting it lapse hands that to whoever registers it next — and the handshake will keep resolving for them.
Last updated 29 August 2026