Complete TOML Hosting Guide

Learn different methods to host your XRP Ledger TOML file

What is a TOML file?

A TOML (Tom's Obvious, Minimal Language) file is a configuration file format that's easy for humans to read and write. In the context of the XRP Ledger (XRPL), a TOML file is used to provide metadata about your token, including information about the issuer, token properties, and more.

For XRPL tokens, the TOML file needs to be hosted at a specific location: https://yourdomain.com/.well-known/xrp-ledger.toml

Why is it important?

Hosting a proper TOML file provides several benefits:

Verifies the authenticity of your token
Provides essential information about your token to wallets and explorers
Builds trust with your community and potential token holders
Required for getting listed on some exchanges and marketplaces

TOML File Structure

A basic XRP Ledger TOML file structure looks like this:

[[ISSUERS]]
address = "rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr"
name = "CasinoCoin"

[[TOKENS]]
issuer = "rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr"
currency = "CSC"
name = "CasinoCoin"
desc = "CasinoCoin (CSC) is a digital currency, developed specifically for the regulated gaming industry."
icon = "https://xumm.app/assets/icons/currencies/ex-csc-3.png"

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

[[TOKENS.WEBLINKS]]
url = "https://casinocoin.info"
type = "website"
title = "Token Info Dashboard"

[[TOKENS.WEBLINKS]]
url = "https://twitter.com/CasinoCoin"
type = "socialmedia"

You can customize this template with your token's details:

address: Your XRPL account address
name: Your issuer name
currency: Your token's currency code
desc: A description of your token
icon: URL to your token's icon
weblinks: Links to your project's resources

Hosting Methods

There are several free and easy methods to host your TOML file. Choose the one that works best for you:

GitHub Pages

GitHub Pages is a free hosting service provided by GitHub that allows you to host websites directly from your GitHub repository.

Create a GitHub account if you don't already have one.
Create a new repository for your TOML file.
Create a folder named .well-known in your repository.
Inside the .well-known folder, create a file named xrp-ledger.toml.
Add your TOML content to this file.
Create a file named _config.yml in the root of your repository with the following content:
```
include: [".well-known"]
```
Go to repository Settings > Pages and enable GitHub Pages for your repository.
Select the branch you want to deploy (usually "main").
Wait for the deployment to complete.
Your TOML file will be accessible at https://yourusername.github.io/yourrepository/.well-known/xrp-ledger.toml

Vercel

Vercel is a cloud platform for static sites and serverless functions that's very easy to use.

Create a Vercel account at vercel.com.
Create a new GitHub repository or use an existing one.
In your repository, create a folder named public.
Inside the public folder, create a folder named .well-known.
Inside the .well-known folder, create a file named xrp-ledger.toml.
Add your TOML content to this file.
Connect your GitHub repository to Vercel.
Deploy your project.
Your TOML file will be accessible at https://your-project-name.vercel.app/.well-known/xrp-ledger.toml

Netlify

Netlify is another excellent platform for hosting static websites.

Create a Netlify account at netlify.com.
Create a new GitHub repository or use an existing one.
In your repository, create a folder named .well-known.
Inside the .well-known folder, create a file named xrp-ledger.toml.
Add your TOML content to this file.
Create a file named _redirects in the root of your repository with the following content:
```
/*    /index.html   200
```
Connect your GitHub repository to Netlify.
Deploy your project.
Your TOML file will be accessible at https://your-site-name.netlify.app/.well-known/xrp-ledger.toml

Cloudflare Pages

Cloudflare Pages is a JAMstack platform for front-end developers to collaborate and deploy websites.

Create a Cloudflare account at cloudflare.com.
Go to the Pages section in your Cloudflare dashboard.
Create a new project and connect it to your GitHub repository.
In your repository, create a folder named .well-known.
Inside the .well-known folder, create a file named xrp-ledger.toml.
Add your TOML content to this file.
Create a file named _headers in the root of your repository with the following content:
```
/*
  Access-Control-Allow-Origin: *
```
Deploy your project.
Your TOML file will be accessible at https://your-project-name.pages.dev/.well-known/xrp-ledger.toml

Custom Domain

If you want to use your own domain, you can connect it to any of the above platforms:

Purchase a domain from a domain registrar (e.g., Namecheap, GoDaddy).
Go to your hosting platform's settings (GitHub Pages, Vercel, Netlify, or Cloudflare Pages).
Add your custom domain in the settings.
Follow the platform's instructions to configure your domain's DNS settings.
Once configured, your TOML file will be accessible at https://yourdomain.com/.well-known/xrp-ledger.toml

Hosting Token Icons for Free

Your token's icon URL is an important part of the TOML file. Here are several free ways to host your token's icon:

GitHub Repository

You can host your token icon in the same GitHub repository where you host your TOML file.

Add your icon image (preferably PNG format) to your GitHub repository.
Get the raw URL by navigating to your image, clicking "Raw", and copying the URL.
The URL will look like: https://raw.githubusercontent.com/yourusername/yourrepository/main/youricon.png
Use this URL in your TOML file's icon field.

Imgur

Imgur is a free image hosting service that's easy to use.

Go to imgur.com and create an account if you don't have one.
Upload your token icon (preferably a square PNG image).
Right-click on the uploaded image and select "Copy image address".
Use this URL in your TOML file's icon field.

GitLab Pages

Similar to GitHub Pages, GitLab also provides free hosting.

Create a GitLab repository and upload your icon.
Enable GitLab Pages for your repository.
Your icon will be accessible at https://yourusername.gitlab.io/yourrepository/youricon.png

Cloudinary

Cloudinary offers a free tier with image optimization features.

Sign up for a free account at cloudinary.com.
Upload your icon image.
Cloudinary will provide you with a URL for your image.
Use this URL in your TOML file's icon field.

Icon Best Practices

Use PNG format with transparency for best results
Make your icon square with dimensions of at least 200x200 pixels
Keep the file size under 100KB for faster loading
Ensure the hosting service allows hot-linking (direct image access from other sites)
Test your icon URL by opening it directly in your browser before adding it to your TOML file

Example TOML Entry with Icon

[[TOKENS]]
issuer = "rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr"
currency = "CSC"
name = "CasinoCoin"
desc = "CasinoCoin (CSC) is a digital currency, developed specifically for the regulated gaming industry."
icon = "https://raw.githubusercontent.com/yourusername/yourrepository/main/token-icon.png"

Verifying Your TOML File

After hosting your TOML file, you should verify that it's accessible and correctly formatted:

Open a web browser and navigate to https://yourdomain.com/.well-known/xrp-ledger.toml
You should see the raw content of your TOML file.
Check for any errors or formatting issues.

Troubleshooting

If your TOML file isn't accessible, try these common solutions:

File not found: Make sure the file is in the correct location (.well-known/xrp-ledger.toml).
CORS issues: Ensure your hosting platform allows cross-origin requests. Add the proper headers if needed.
Case sensitivity: Some servers are case-sensitive. Make sure all folders and files use the exact case as specified.
Hidden folders: Some platforms might treat folders starting with a dot (.) as hidden. Use the configuration files mentioned above to ensure they're accessible.

Additional Resources

For more information about XRPL TOML files, check out these resources:

Get Your MEME NFT