SEP: 0001 Title: stellar.toml Author: stellar.org Status: Approved Created: 2017-10-30 Updated: 2018-09-11 Version: 1.4.0
stellar.toml file is used to provide a common place where the Internet can find information about your domain’s Stellar integration. Any website can publish Stellar network information. You can announce your validation key, your federation server, peers you are running, your quorum set, if you are an anchor, etc.
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.
Given the domain
stellar.toml will be searched for at the following location:
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 a HTTP response for
/.well-known/stellar.toml file request.
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
||The endpoint for clients to resolve stellar addresses for users on your domain via SEP-2 federation protocol|
||The endpoint used for SEP-3 Compliance Protocol|
||The server used for SEP-6 Anchor/Client interoperability|
||The server used for SEP-12 Anchor/Client customer info transfer|
||The endpoint used for SEP-10 Web Authentication|
|SIGNING_KEY||Stellar public key||The signing key is used for the compliance protocol|
||convenience mapping of common names to node IDs. You can use these common names in sections below instead of the less friendly nodeID. This is provided mainly to be compatible with the stellar-core.cfg|
||A list of Stellar accounts that are controlled by this domain. Names defined in
||A list of validator public keys that are declared to be used by this domain for validating ledgers. They are authorized signers for the domain. Names defined in
||The validator through which the issuer pledges to honor redemption transactions, and which therefore maintains the authoritative ownership records for assets issued by this organization. Specified as a public key
|DESIRED_BASE_FEE||int||Your preference for the Stellar network base fee, expressed in stroops|
|DESIRED_MAX_TX_PER_LEDGER||int||Your preference for max number of transactions per ledger close|
|KNOWN_PEERS||list of strings||List of known Stellar core servers, listed from most to least trusted if known. Can be
|HISTORY||list of URL strings||List of history archives maintained by this domain|
These fields go in the
|ORG_NAME||string||Legal name of your organization|
|ORG_DBA||string||(may not apply) DBA of your organization|
||Your organization's official URL. Your
|ORG_LOGO||url||Your organization's logo|
|ORG_DESCRIPTION||string||Short description of your organization|
|ORG_PHYSICAL_ADDRESS||string||Physical address for your organization|
||URL on the same domain as your
|ORG_PHONE_NUMBER||string||Your organization's phone number|
||URL on the same domain as your
|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_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.
Point of Contact Documentation
These fields go in the
[[PRINCIPALS]] list. It contains identifying information for the primary point of contact or principal(s) of the organization.
|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
$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
[[CURRENCIES]] list, one set of fields for each currency issued. Complete all applicable fields, and exclude any that don't apply.
|code||string (<= 12 char)||Token code|
|code_template||string (<= 12 char)||A pattern with
||Token issuer Stellar public key|
|status||string||Status of token. One of
|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
|is_unlimited||bool||The number of tokens is dilutable at the issuer's discretion|
|anchor_asset_type||string||Type of asset anchored. Can be
|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_address_signatures||list of signature strings||These prove you control the
|regulated||boolean||indicates whether or not this is a sep0008 regulated asset. If missing,
|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
The assets in the account $PUBLIC_KEY are reserved to back $CODE issued by $ISSUER_ADDRESS on Stellar. Valid from $START to $END.
$PUBLIC_KEY with the account's public key,
$CODE with your asset code,
$ISSUER_ADDRESS with the issuing Stellar address and
$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.
is_unlimited are mutually exclusive issuance policies. Include exactly one of those fields.
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
||List of authoritative validators for organization. This can potentially be a quorum set. Names defined in
- Run a curl command in your terminal similar to the following (replace stellar.org with the hosting location of your
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" DEPOSIT_SERVER="https://api.domain.com" SIGNING_KEY="GBBHQ7H4V6RRORKYLHTCAWP6MOHNORRFJSDPXDFYDGJB2LPZUFPXUEW3" NODE_NAMES=[ "GD5DJQDDBKGAYNEAXU562HYGOOSYAEOO6AS53PZXBOZGCP5M2OPGMZV3 lab1", "GB6REF5GOGGSEHZ3L2YK6K4T4KX3YDMWHDCPMV7MZJDLHBDNZXEPRBGM donovan", "GBGR22MRCIVW2UZHFXMY5UIBJGPYABPQXQ5GGMNCSUM2KHE3N6CNH6G5 nelisky1", "GDXWQCSKVYAJSUGR2HBYVFVR7NA7YWYSYK3XYKKFO553OQGOHAUP2PX2 jianing", "GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWA6L7U anchor" ] ACCOUNTS=[ "$lab1", "GAENZLGHJGJRCMX5VCHOLHQXU3EMCU5XWDNU4BGGJFNLI2EL354IVBK7" ] OUR_VALIDATORS=[ "$nelisky1", "GCGB2S2KGYARPVIA37HYZXVRM2YZUEXA6S33ZU5BUDC6THSB62LZSTYH" ] DESIRED_BASE_FEE=100 DESIRED_MAX_TX_PER_LEDGER=400 KNOWN_PEERS=[ "192.168.0.1", "core-testnet1.stellar.org", "core-testnet2.stellar.org:11290", "2001:0db8:0100:f101:0210:a4ff:fee3:9566" ] HISTORY=[ "http://history.stellar.org/prd/core-live/core_live_001/", "http://history.stellar.org/prd/core-live/core_live_002/", "http://history.stellar.org/prd/core-live/core_live_003/" ] [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 St., New York, NY, 12345" 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@example.com" [[PRINCIPALS]] name="Jane Jedidiah Johnson" email="firstname.lastname@example.org" 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 # Potential quorum set of this domain's validators. [QUORUM_SET] VALIDATORS=[ "$self", "$lab1", "$nelisky1","$jianing", "$eno","$donovan" ] # 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