#Simple Summary
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 home_domain 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.
#Specification
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 can have a maximum file size of 100KB.
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.
#General Information
These are global fields in the stellar.toml file.
| Field | Requirements | Description |
|---|---|---|
| VERSION | string | The version of SEP-1 your stellar.toml adheres to. This helps parsers know which fields to expect. |
| NETWORK_PASSPHRASE | string | The passphrase for the specific Stellar network this infrastructure operates on |
| 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:// | (deprecated) The endpoint used for SEP-3 Compliance Protocol |
| TRANSFER_SERVER | uses https:// | The server used for SEP-6 Anchor/Client interoperability |
| TRANSFER_SERVER_SEP0024 | uses https:// | The server used for SEP-24 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 |
| WEB_AUTH_FOR_CONTRACTS_ENDPOINT | uses https:// | The endpoint used for SEP-45 Web Authentication |
| WEB_AUTH_CONTRACT_ID | Stellar contract ID | The web authentication contract ID for SEP-45 Web Authentication |
| SIGNING_KEY | Stellar public key | The signing key is used for SEP-3 Compliance Protocol (deprecated) and SEP-10/SEP-45 Authentication Protocols |
| 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 |
| URI_REQUEST_SIGNING_KEY | Stellar public key | The signing key is used for SEP-7 delegated signing |
| DIRECT_PAYMENT_SERVER | uses https:// | The server used for receiving SEP-31 direct fiat-to-fiat payments. Requires SEP-12 and hence a KYC_SERVER TOML attribute. |
| ANCHOR_QUOTE_SERVER | uses https:// | The server used for receiving SEP-38 requests. |
#Organization Documentation
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 | A PNG image of your organization's logo on a transparent background |
| 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 that business partners such as wallets, exchanges, or anchors can use to contact your organization. Must be hosted at your ORG_URL domain. |
| ORG_SUPPORT_EMAIL | string | An email that users can use to request support regarding your Stellar assets or applications. |
| ORG_LICENSING_AUTHORITY | string | Name of the authority or agency that issued a license, registration, or authorization to your organization, if applicable |
| ORG_LICENSE_TYPE | string | Type of financial or other license, registration, or authorization your organization holds, if applicable |
| ORG_LICENSE_NUMBER | string | Official license, registration, or authorization number of your organization, if applicable |
Issuers that list verified information including phone/address attestations and Keybase verifications will be prioritized by Stellar clients.
#Point of Contact Documentation
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.
#Currency Documentation
These fields go in the stellar.toml [[CURRENCIES]] list, one set of fields
for each currency supported. Complete all applicable fields, and exclude any
that don't apply.
Currencies can be Stellar Assets that have been issued by a Stellar account and share the same common behaviors, or custom token contracts that satisfy the SEP-0041 interface but implementation and behavior is customizable.
| Field | Requirements | Description |
|---|---|---|
| code | string (<= 12 char) | Token code. Required. |
| issuer | G... string | Stellar public key of the issuing account. Required for tokens that are Stellar Assets. Omitted if the token is not a Stellar asset. |
| contract | C... string | Contract ID of the token contract. The token must be compatible with the SEP-41 Token Interface to be defined here. Required for tokens that are not Stellar Assets. Omitted if the token is a Stellar Asset. |
| 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. |
| 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 a PNG image on a transparent background 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, nft, stock, bond, commodity, realestate, or other. |
| anchor_asset | string | If anchored token, code / symbol for asset that token is anchored to. E.g. USD, BTC, SBUX, Address of real-estate investment property. |
| attestation_of_reserve | url | URL to attestation or other proof, evidence, or verification of reserves, such as third-party audits. |
| 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.
#Validator Information
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 |
#Testing
#Tools
Use the Stellar
Anchor Validator or the
community-supported stellar.toml checker to
validate your info file.
#Manual
- 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.
#Example
# Sample stellar.toml
VERSION="2.0.0"
NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015"
FEDERATION_SERVER="https://api.domain.com/federation"
TRANSFER_SERVER="https://api.domain.com"
SIGNING_KEY="GBBHQ7H4V6RRORKYLHTCAWP6MOHNORRFJSDPXDFYDGJB2LPZUFPXUEW3"
HORIZON_URL="https://horizon.domain.com"
ACCOUNTS=[
"GD5DJQDDBKGAYNEAXU562HYGOOSYAEOO6AS53PZXBOZGCP5M2OPGMZV3",
"GAENZLGHJGJRCMX5VCHOLHQXU3EMCU5XWDNU4BGGJFNLI2EL354IVBK7",
"GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWA6L7U"
]
[DOCUMENTATION]
ORG_NAME="Organization Name"
ORG_DBA="Organization DBA"
ORG_URL="https://www.domain.com"
ORG_LOGO="https://www.domain.com/awesomelogo.png"
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="+14155552671"
ORG_PHONE_NUMBER_ATTESTATION="https://www.domain.com/phone_attestation.jpg"
ORG_KEYBASE="accountname"
ORG_TWITTER="orgtweet"
ORG_GITHUB="orgcode"
ORG_OFFICIAL_EMAIL="support@domain.com"
[[PRINCIPALS]]
name="Jane Jedidiah Johnson"
email="jane@domain.com"
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://static.thenounproject.com/png/2292360-200.png"
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