XRPL toml file

A TOML (Tom's Obvious, Minimal Language) file is a configuration file format that's easy for humans to read and write. You can use a TOML file for your XRP Ledger token(s) in order to provide meta data about your token(s). You can include things such as Name, Issuer(wallet), Description, Weblinks, a URL link to your token icon and more.

In order for a TOML file to function it needs to be hosted at a specific location: Eg. https://yourdomain.com/.well-known/xrp-ledger.toml

It is required that your toml file is hosted with SSL (ie. https not http). Most web hosts now provide SSL certificates for free as standard but you should always check before buying hosting in order to avoid hidden charges.

Why should I use a TOML file for my token?

There are a number of good reasons to use a toml file. Firstly, it allows others to find information about your token such as your web domain or social media links etc (If nothing else it's almost free advertising). Using a toml file builds trust as people can see it's not just a spam token on the ledger and actually has genuine effort behind it. If you want an icon image to appear against your token in XRPL wallets and exchanges a toml file is the only way to do it. Also, some exchanges and marketplaces will not list XRP Ledger tokens that do not have a toml file.

Example of a basic TOML file for one issuer with one token:
[[ISSUERS]]
address = "rBitcoiNXev8VoVxV7pwoQx1sSfonVP9i3"
name = "BITx"
desc = "BITx - Bitcoin ideology with XRP Ledger utility"

[[TOKENS]]
issuer = "rBitcoiNXev8VoVxV7pwoQx1sSfonVP9i3"
currency = "BITx"
name = "BITx"
desc = "BITx - Bitcoin ideology with XRP Ledger utility"
icon = "https://bitx.fyi/bitx-images/bitx-logo.png"

[[TOKENS.WEBLINKS]]
url = "https://bitx.fyi"
type = "website"
title = "Official Website"

[[TOKENS.WEBLINKS]]
url = "https://x.com/getbitx"
type = "socialmedia"

Using something like Notepad simply customise the above example with your own token details, save the file as xrp-ledger.toml and upload it into the folder .well-known (yes you need to have the . infront of the folder name). The .well-known folder needs to be in the same directory folder a your website index.html file.

Do I have to have my own website to host a TOML file?

No, although we encourage all those who are serious about developing a token on the XRP Ledger to have their own web presence. If you dont yet have a domain or web hosting you can order both via: https://websites.bitx.fyi, ordering via ourselves will also give your site highly relevant xrpl.host DNS.
If you would like to host a TOML file elsewhere for free it can be done a few ways, essentially all you need is somewhere to host your toml file that meets the criteria mentioned previously. One way is to use Github Pages, simply create an account if you don't already have one, create a new repository for your toml file, create a folder called .well-known and save your xrp-ledger.toml in that folder. You will then also need to create a file called _config.yml and save it in the root diretory of you repository, the _config.yml file should contain the following: include: [".well-known"]. Next go to you repository Settings > Pages and enable Github Pages for your repository, select the branch you want to enable (usually 'main') and wait for the deployment to complete. You TOML file will be accessible after a short time. In order to use your Github TOML file for a token icon you'll need to add your icon (.png format is best) to your Github repository then copy the icon URL into your TOML file icon field, the URL should look something like: https://raw.githubusercontent.com/yourusername/yourrepository/main/yourtokenicon.png

Are there filesize requirements etc for a token icon?

It is best pratice to use the .png format with transparency (for better looking results), 200x200 pixels, filesize under 100KB and that the host allows hotlinking (also known as inline linking). Test your icon URL by opening it directly in a web browser.

Learn more about the XRP Ledger toml file: XRP Ledger TOML