SEP: 0001
Title: stellar.toml
Author: stellar.org
Status: Active
Created: 2017-10-30
Updated: 2019-06-12
Version: 2.0.0
The 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 stellar.toml is designed to be readable by both humans and machines.
If you are an anchor or issuer, the stellar.toml file serves a very important purpose: it allows you to publish information about your organization and token(s) that help to legitimize your offerings. Clients and exchanges can use this information to decide whether a token should be listed. Fully and truthfully disclosing contact and business information is an essential step in responsible token issuance.
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.
Given the domain DOMAIN, the stellar.toml will be searched for at the following location:
https://DOMAIN/.well-known/stellar.toml
You must enable CORS on the stellar.toml so people can access this file from other sites. The following HTTP header must be set for an HTTP response for /.well-known/stellar.toml file request.
Access-Control-Allow-Origin: *
It is also recommended to set a text/plain content type so that browsers render the contents, rather than prompting for a download.
content-type: text/plain
stellar.toml is in TOML file format. The stellar.toml fields and sections are described below. You should complete as much of this as you can. Many Stellar apps, including important wallets and exchanges, make decisions on which tokens to support based on the completeness of their Account Information and Documentation sections.
These are global fields in the stellar.toml file.
| Field | Requirements | Description |
|---|---|---|
| FEDERATION_SERVER | uses https:// |
The endpoint for clients to resolve stellar addresses for users on your domain via SEP-2 Federation Protocol |
| AUTH_SERVER | uses https:// |
The endpoint used for SEP-3 Compliance Protocol |
| TRANSFER_SERVER | uses https:// |
The server used for SEP-6 Anchor/Client interoperability |
| KYC_SERVER | uses https:// |
The server used for SEP-12 Anchor/Client customer info transfer |
| WEB_AUTH_ENDPOINT | uses https:// |
The endpoint used for SEP-10 Web Authentication |
| SIGNING_KEY | Stellar public key | The signing key is used for SEP-3 Compliance Protocol |
| HORIZON_URL | url | Location of public-facing Horizon instance (if you offer one) |
| ACCOUNTS | list of G... strings |
A list of Stellar accounts that are controlled by this domain |
| VERSION | string | The version of SEP-1 your stellar.toml adheres to. This helps parsers know which fields to expect. |
These fields go in the stellar.toml [DOCUMENTATION] table.
| Field | Requirements | Description |
|---|---|---|
| ORG_NAME | string | Legal name of your organization |
| ORG_DBA | string | (may not apply) DBA of your organization |
| ORG_URL | uses https:// |
Your organization's official URL. Your stellar.toml must be hosted on the same domain. |
| ORG_LOGO | url | Your organization's logo |
| ORG_DESCRIPTION | string | Short description of your organization |
| ORG_PHYSICAL_ADDRESS | string | Physical address for your organization |
| ORG_PHYSICAL_ADDRESS_ATTESTATION | https:// url |
URL on the same domain as your ORG_URL that contains an image or pdf official document attesting to your physical address. It must list your ORG_NAME or ORG_DBA as the party at the address. Only documents from an official third party are acceptable. E.g. a utility bill, mail from a financial institution, or business license. |
| ORG_PHONE_NUMBER | string | Your organization's phone number in E.164 format, e.g. +14155552671. See also this guide. |
| ORG_PHONE_NUMBER_ATTESTATION | https:// url |
URL on the same domain as your ORG_URL that contains an image or pdf of a phone bill showing both the phone number and your organization's name. |
| ORG_KEYBASE | string | A Keybase account name for your organization. Should contain proof of ownership of any public online accounts you list here, including your organization's domain. |
| ORG_TWITTER | string | Your organization's Twitter account |
| ORG_GITHUB | string | Your organization's Github account |
| ORG_OFFICIAL_EMAIL | string | An email where clients can contact your organization. Must be hosted at your ORG_URL domain. |
| ORG_LICENSING_AUTHORITY | string | Name of the authority or agency that licensed your organization, if applicable |
| ORG_LICENSE_TYPE | string | Type of financial or other license your organization holds, if applicable |
| ORG_LICENSE_NUMBER | string | Official license number of your organization, if applicable |
Issuers that list verified information including phone/address attestations and Keybase verifications will be prioritized by Stellar clients.
These fields go in the stellar.toml [[PRINCIPALS]] list. It contains identifying information for the primary point of contact or principal(s) of the organization.
| Field | Requirements | Description |
|---|---|---|
| name | string | Full legal name |
| string | Business email address for the principal | |
| keybase | string | Personal Keybase account. Should include proof of ownership for other online accounts, as well as the organization's domain. |
| telegram | string | Personal Telegram account |
| string | Personal Twitter account | |
| github | string | Personal Github account |
| id_photo_hash | string | SHA-256 hash of a photo of the principal's government-issued photo ID |
| verification_photo_hash | string | SHA-256 hash of a verification photo of principal. Should be well-lit and contain: principal holding ID card and signed, dated, hand-written message stating I, $NAME, am a principal of $ORG_NAME, a Stellar token issuer with address $ISSUER_ADDRESS. |
$NAME is the principal's full legal name, $ORG_NAME is the name of the organization and must match the value in the stellar.toml file, and $ISSUER_ADDRESS is the Stellar address of the organization/issuer.
The photo hashes allow principals to provide proof of identity to businesses and important clients. The photos can be sent privately, and the recipient can verify that the hashes match. Wallets and Stellar exchanges may request this information from an issuer and add an "ID verified" badge to the issuer's tokens in their interface.
The public key in the verification photo should be the issuing public key for the issuer's assets. If there are multiple, please include the multiple keys in the statement.
These fields go in the stellar.toml [[CURRENCIES]] list, one set of fields for each currency issued. Complete all applicable fields, and exclude any that don't apply.
| Field | Requirements | Description |
|---|---|---|
| code | string (<= 12 char) | Token code |
| code_template | string (<= 12 char) | A pattern with ? as a single character wildcard. Allows a [[CURRENCIES]] entry to apply to multiple assets that share the same info. An example is futures, where the only difference between issues is the date of the contract. E.g. CORN???????? to match codes such as CORN20180604. |
| issuer | G... string |
Token issuer Stellar public key |
| status | string | Status of token. One of live, dead, test, or private. Allows issuer to mark whether token is dead/for testing/for private use or is live and should be listed in live exchanges. |
| display_decimals | int (0 to 7) | Preference for number of decimals to show when a client displays currency balance |
| name | string (<= 20 char) | A short name for the token |
| desc | string | Description of token and what it represents |
| conditions | string | Conditions on token |
| image | url | URL to image representing token |
| fixed_number | int | Fixed number of tokens, if the number of tokens issued will never change |
| max_number | int | Max number of tokens, if there will never be more than max_number tokens |
| is_unlimited | boolean | The number of tokens is dilutable at the issuer's discretion |
| is_asset_anchored | boolean | true if token can be redeemed for underlying asset, otherwise false |
| anchor_asset_type | string | Type of asset anchored. Can be fiat, crypto, stock, bond, commodity, realestate, or other. |
| anchor_asset | string | If anchored token, asset that token is anchored to. E.g. USD, BTC, SBUX, Address of real-estate investment property. |
| redemption_instructions | string | If anchored token, these are instructions to redeem the underlying asset from tokens. |
| collateral_addresses | list of crypto address strings | If this is an anchored crypto token, list of one or more public addresses that hold the assets for which you are issuing tokens. |
| collateral_address_messages | list of message strings | Messages stating that funds in the collateral_addresses list are reserved to back the issued asset. See below for details. |
| collateral_address_signatures | list of signature strings | These prove you control the collateral_addresses. For each address you list, sign the entry in collateral_address_messages with the address's private key and add the resulting string to this list as a base64-encoded raw signature. |
| regulated | boolean | indicates whether or not this is a sep0008 regulated asset. If missing, false is assumed. |
| approval_server | url | url of a sep0008 compliant approval service that signs validated transactions. |
| approval_criteria | string | a human readable string that explains the issuer's requirements for approving transactions. |
Message to put in collateral_address_messages for each entry in collateral_addresses:
The assets in the account $PUBLIC_KEY are reserved to back $CODE issued by $ISSUER_ADDRESS on Stellar. Valid from $START to $END.
Replace $PUBLIC_KEY with the account's public key, $CODE with your asset code, $ISSUER_ADDRESS with the issuing Stellar address and $START, $END with the date range in ISO 8601 for which the reserve is valid. $END cannot be more than a year in the future to ensure yearly renewals of the commitment. collateral_addresses can be used to externally validate that you hold a reserve for the crypto funds you are issuing on Stellar. Issuers that hold a provable 100% reserve are prioritized by wallets and clients. Issuers not meeting this standard may not be listed.
Note: fixed_number, max_number, and is_unlimited are mutually exclusive issuance policies. Include exactly one of those fields.
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.
These fields go in the stellar.toml [[VALIDATORS]] list, one set of fields for each node your organization runs. Combined with the steps outlined in SEP-20, 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 don't apply.
| Field | Requirements | Description |
|---|---|---|
| ALIAS | string | A name for display in stellar-core configs that conforms to ^[a-z0-9-]{2,16}$ |
| DISPLAY_NAME | string | A human-readable name for display in quorum explorers and other interfaces |
| PUBLIC_KEY | G... string |
The Stellar account associated with the node |
| HOST | string | The IP:port or domain:port peers can use to connect to the node |
| HISTORY | uri | The location of the history archive published by this validator |
- Run a curl command in your terminal similar to the following (replace stellar.org with the hosting location of your
stellar.tomlfile):
curl --head https://stellar.org/.well-known/stellar.toml- Verify the Access-Control-Allow-Origin header is present as shown below.
curl --head https://stellar.org/.well-known/stellar.toml
HTTP/1.1 200 OK
Accept-Ranges: bytes
Access-Control-Allow-Origin: *
Content-length: 482
...- Also run the command on a page that should not have it and verify the
Access-Control-Allow-Originheader is missing.
# Sample stellar.toml
FEDERATION_SERVER="https://api.domain.com/federation"
AUTH_SERVER="https://api.domain.com/auth"
TRANSFER_SERVER="https://api.domain.com"
SIGNING_KEY="GBBHQ7H4V6RRORKYLHTCAWP6MOHNORRFJSDPXDFYDGJB2LPZUFPXUEW3"
HORIZON_URL="https://horizon.domain.com"
ACCOUNTS=[
"GD5DJQDDBKGAYNEAXU562HYGOOSYAEOO6AS53PZXBOZGCP5M2OPGMZV3",
"GAENZLGHJGJRCMX5VCHOLHQXU3EMCU5XWDNU4BGGJFNLI2EL354IVBK7",
"GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWA6L7U"
]
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]"
[[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"
[[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://pbs.twimg.com/profile_images/666921221410439168/iriHah4f.jpg"
fixed_number=10000
[[VALIDATORS]]
ALIAS="domain-au"
DISPLAY_NAME="Domain Australia"
HOST="core-au.domain.com:11625"
PUBLIC_KEY="GD5DJQDDBKGAYNEAXU562HYGOOSYAEOO6AS53PZXBOZGCP5M2OPGMZV3"
HISTORY="http://history.domain.com/prd/core-live/core_live_001/"
[[VALIDATORS]]
ALIAS="domain-sg"
DISPLAY_NAME="Domain Singapore"
HOST="core-sg.domain.com:11625"
PUBLIC_KEY="GAENZLGHJGJRCMX5VCHOLHQXU3EMCU5XWDNU4BGGJFNLI2EL354IVBK7"
HISTORY="http://history.domain.com/prd/core-live/core_live_002/"
[[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/"
# optional extra information for humans
# Useful place for anchors to detail various policies and required info
###################################
# Required compliance fields:
# name=<recipient name>
# addr=<recipient address>
# Federation Format:
# <phone number>*anchor.com
# Forwarding supported by sending to: forward*anchor.com
# forward_type=bank_account
# swift=<swift code of receiving bank>
# acct=<recipient account number at receiving bank>
# Minimum Amount Forward: $2 USD
# Maximum Amount Forward: $10000 USD