- Get Started
- Stellar Attachment Convention
- Compliance Protocol
- Add Stellar To Your Exchange
- Hardware Requirements
- Issuing Assets
- Build Stellar Apps
- Contribution Guide
If you are interested in issuing a token on the Stellar network, but haven’t yet, start by consulting our step-by-step instructions for custom asset creation.
Hello! We made this short guide to help you, an asset issuer, put your token in the best possible place to succeed on Stellar.
Mostly, we want to make sure you know how to provide information to the network about yourself
and your asset, so that potential buyers and apps, like exchanges and wallets, will trust your
asset. You provide this necessary information by completing your
The best asset on Stellar already follow the guidelines below, and apps and buyers will expect your token to do the same.
The most successful asset issuers give exchanges and potential buyers lots of information about
themselves in order to establish trust. On Stellar, they do this in the
stellar.toml file. More
information in your asset’s stellar.toml will mean:
For example, StellarX, uses the stellar.toml file to decide how your asset is presented to traders in its markets view. If you don’t provide enough information, your asset may be hidden from many traders. Other Stellar exchanges like Stellarport and StellarTerm make similar decisions.
If you are a validator, the stellar.toml file allows you to declare your node(s) to other network participants, which improves discoverability, and contributes to the health and decentralization of the network as a whole.
Many exchanges and wallets will not list your asset without a robust stellar.toml.
stellar.toml file is used to provide a common place where the Internet can find information
about your organization’s Stellar integration. By setting the homedomain of your Stellar account to
the domain that hosts your
stellar.toml, you can create a definitive link between this information
and that account. Any website can publish Stellar network information, and the
designed to be readable by both humans and machines.
stellar.toml file is written in TOML, a
simple and widely used configuration file format, and ultimately published at
Anyone can look it up, and it proves that the owner of the HTTPS domain hosting the stellar.toml claims responsibility for the accounts and assets listed in it. It’s where you can legitimize your assets, and announce vital information about your organization.
You can find the complete specification for your
stellar.toml file in SEP-0001.
However, we’ll discuss how to best complete your
stellar.toml file for usage throughout the
Stellar ecosystem below.
SEP-0001 specifies five sections you can add to your stellar.toml:
Within those sections, some fields only apply to specialized assets, but the majority apply to all organizations and their assets. These guidelines will outline which fields are:
There is one field in the Account Information section required for all token issuers:
ACCOUNTS: A list of public keys for all the Stellar accounts associated with your asset.
Listing your public keys lets users confirm that you, in fact, own them. For example, when https://google.com hosts a stellar.toml file, users can be sure that only the accounts listed on it belong to Google. If someone then says, “You need to pay your Google bill this month, send payment to address GIAMGOOGLEIPROMISE”, but that key is not listed on Google’s stellar.toml, then users know to not trust it.
Here’s an example of a completed
ACCOUNTS field listing three public keys:
ACCOUNTS=[ "GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWA6L7U", "GAENZLGHJGJRCMX5VCHOLHQXU3EMCU5XWDNU4BGGJFNLI2EL354IVBK7", "GB6REF5GOGGSEHZ3L2YK6K4T4KX3YDMWHDCPMV7MZJDLHBDNZXEPRBGM" ]
Basic information about your organization goes into a TOML table called
Issuer Documentation is your chance to inform exchanges and buyers about your business, and to
demonstrate that your business is legitimate and trustworthy.
ORG_NAME), and if your business has one, its official dba (
ORG_URL). In order to prove the website is yours, you must host your stellar.toml on the same domain you list here. That way, exchanges and buyers can view the SSL certificate on your website, and feel reasonably confident that you are who you say you are.
ORG_LOGO), which will show up next to your organization on exchanges. This image should be a square aspect ratio transparent PNG, ideally of size 128x128. If you fail to provide a logo, the icon next to your organization will appear blank on many exchanges.
ORG_PHYSICAL_ADDRESS). We understand you might want to keep your work address private. At the very least, you should put the city and country in which you operate. A street address is ideal and provides a higher level of trust and transparency to your potential asset holders. You can also link to the attestation of your physical address via the
ORG_PHONE_NUMBER) in E.164 format. See also this guide.
ORG_OFFICIAL_EMAIL). This should be hosted at the same domain as your official website.
Issuers that list verified information including phone/address attestations and Keybase verifications will be prioritized by Stellar clients.
ORG_KEYBASE). Your Keybase account should contain proof of ownership of any public online accounts you list here, including your organization’s domain.
ORG_DESCRIPTION). This is fairly open-ended, and you can write as much as you want. It’s a great place to distinguish yourself by describing what it is that you do.
Exchanges might desire additional verifiable information when deciding how to present your token to traders and asset holders, and prioritize tokens that include it:
ORG_PHYSICAL_ADDRESS_ATTESTATION). This is a URL to an image on your organization’s domain of an official third party document (such as a utility bill) that shows your organization’s name and address.
ORG_PHONE_NUMBER_ATTESTATION). This is a URL to an image on your domain showing a phone bill listing both your phone number and your organization’s name.
Here’s an example of completed Issuer Documentation:
VERSION="2.0.0" [DOCUMENTATION] ORG_NAME="Organization Name" ORG_DBA="Organization DBA" ORG_URL="https://www.domain.com" ORG_LOGO="https://www.domain.com/awesomelogo.jpg" ORG_DESCRIPTION="Description of issuer" ORG_PHYSICAL_ADDRESS="123 Sesame Street, New York, NY 12345, United States" ORG_PHYSICAL_ADDRESS_ATTESTATION="https://www.domain.com/address_attestation.jpg" ORG_PHONE_NUMBER="1 (123)-456-7890" ORG_PHONE_NUMBER_ATTESTATION="https://www.domain.com/phone_attestation.jpg" ORG_KEYBASE="accountname" ORG_TWITTER="orgtweet" ORG_GITHUB="orgcode" ORG_OFFICIAL_EMAIL="[email protected]"
Information about the primary point(s) of contact for your organization goes into a TOML array of
[[PRINCIPALS]]. You need to
put contact information for at least one person at your organization. If you don’t, exchanges
can’t verify your offering, and it is unlikely that buyers will be interested. Multiple principals
can be added with additional
keybase). This account should contain proof of ownership of any public online accounts listed here and may contain proof of ownership of your organization’s domain.
Again, the more information you provide, the better. Exchanges might desire additional verifiable information when deciding how to present your token to traders, and prioritize tokens that include it:
The photo hashes allow exchanges and wallets to confirm the identity of your point of contact. Those services can contact you privately to request ID and verification photos, then check those photos against the hashes listed here to make sure they match. If the hashes match, they will let their clients know that your contact information is verified.
Here’s an example of completed Point of Contact Documentation for one principal:
[[PRINCIPALS]] name="Jane Jedidiah Johnson" email="[email protected]" keybase="crypto_jane" twitter="crypto_jane" github="crypto_jane" id_photo_hash="be688838ca8686e5c90689bf2ab585cef1137c999b48c70b92f67a5c34dc15697b5d11c982ed6d71be1e1e7f7b4e0733884aa97c3f7a339a8ed03577cf74be09" verification_photo_hash="016ba8c4cfde65af99cb5fa8b8a37e2eb73f481b3ae34991666df2e04feb6c038666ebd1ec2b6f623967756033c702dde5f423f7d47ab6ed1827ff53783731f7"
Information about your token(s) goes into a TOML array of
[[CURRENCIES]]. If you are
issuing multiple assets, you can include them all in one stellar.toml. Each asset should have its
code). This is one of two key pieces of information that identify your token. Without it, your token cannot be listed anywhere. You can also use the
code_templatefield to represent multiple assets with very similar assets — for example, futures contracts where the asset code remains the same besides the date of the contract.
issuer). This is the second key piece of information that identifies your token. Without it, your token cannot be listed anywhere.
status): live, dead, or test. Marking your token live means you are ready for exchanges to list it. If your token is ready to trade, and you fail to list its status, it may not appear on exchanges.
name). If you fail to name your token, exchanges may not be able to display it properly.
trueif your token can be redeemed for an asset outside the Stellar network,
falseif it can’t. Exchanges use this information to sort tokens by type in listings. If you fail to provide it, your token is unlikely to show up in filtered market views.
You also need to describe your token issuance policy by filling in exactly one of the following mutually exclusive fields:
fixed_number, which you should specify if you are issuing a set number of tokens, and that number will never increase.
max_number, which you should specify if there is an upper limit to the number of tokens you will issue.
is_unlimited, which you should specify if you reserve the right to create more tokens at your discretion.
Finally, if you’re issuing anchored (tethered, stablecoin, asset-backed) tokens, there are several additional fields required. Anchored assets are specialized assets in the Stellar ecosystem because they can be redeemed outside of the network for other assets. If you are issuing an anchored token, you need to provide additional information about those assets, and about how to redeem your token for them.
In addition to Currency Documentation listed above, the following fields are required for anchored tokens:
anchor_asset_type). The possible categories are
For assets that are anchored to other cryptocurrencies, exchanges are unlikely to list them without the following verifiable information:
collateral_address_signatures). SEP 0001 contains a template for these signatures, and instructions for tailoring them to your token.
Exchanges use the collateral address signatures to verify that the accounts you list belong to you, and will look at the reserve in those accounts. If you cannot prove 100% reserve, it is unlikely they will list your token.
desc). This is a good place to clarify what your token does, and why someone might want to own it.
image). Without it, your token will appear blank on many exchanges.
Here’s what an example of completed Currency Documentation for an organization:
[[CURRENCIES]] code="USD" issuer="GCZJM35NKGVK47BB4SPBDV25477PZYIYPVVG453LPYFNXLS3FGHDXOCM" display_decimals=2 [[CURRENCIES]] code="BTC" issuer="GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWA6L7U" display_decimals=7 anchor_asset_type="crypto" anchor_asset="BTC" redemption_instructions="Use SEP6 with our federation server" collateral_addresses=["2C1mCx3ukix1KfegAY5zgQJV7sanAciZpv"] collateral_address_signatures=["304502206e21798a42fae0e854281abd38bacd1aeed3ee3738d9e1446618c4571d10"] # Asset with meta info [[CURRENCIES]] code="GOAT" issuer="GD5T6IPRNCKFOHQWT264YPKOZAWUMMZOLZBJ6BNQMUGPWGRLBK3U7ZNP" display_decimals=2 name="goat share" desc="1 GOAT token entitles you to a share of revenue from Elkins Goat Farm." conditions="There will only ever be 10,000 GOAT tokens in existence. We will distribute the revenue share annually on Jan. 15th" image="https://static.thenounproject.com/png/2292360-200.png" fixed_number=10000
Alternately, stellar.toml can link out to a separate TOML file for each currency by specifying
toml="https://DOMAIN/.well-known/CURRENCY.toml as the currency’s only field.
If your organizations runs any nodes as validators for the network, you should list them in the
[[VALIDATORS]] array of tables. Each table
should represent one node that your organization runs. Combined with the steps outlined in
SEP-0020, this section allows you to declare your node(s), and to let others know the
location of any public archives you maintain. Complete all applicable fields, and exclude any that
ALIAS). It should conform to the regex
Here’s an example of completed Validator Documentation for an organization.
[[VALIDATORS]] ALIAS="domain-us" DISPLAY_NAME="Domain United States" HOST="core-us.domain.com:11625" PUBLIC_KEY="GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWA6L7U" HISTORY="http://history.domain.com/prd/core-live/core_live_003/"
After you’ve followed the steps above to complete your stellar.toml, post it at the following location:
Enable CORS so people can access this
file from other sites, and set the following header for an HTTP response for a
/.well-known/stellar.toml file request.
Once you’ve done that, you’re all set! Now apps and buyers can access all the information you’ve provided with a simple HTTP request.
If you want to see a stellar.toml done well, take a look at AnchorUSD’s. You can easily find out everything you need to know about the company, their Stellar accounts, their points of contact, and their tokens, and you can take steps to verify that information.