Record specification
How xlm.sh finds the content of https://<name>.xlm.sh.
Resolution
Take
<name>. It must be 1 to 15 lettersa-z. Any other host name, including one with a hyphen or a period, returns 404.Look up
<name>.xlmin the Soroban Domains registry v1 (CATRNPHYKNXAPNLHEYH55REB6YSAJLGCPA4YM6L3WUKSZOPI77M2UMKI). A missing or expired domain returns 404.The domain must point to a Stellar account (
G...). A contract address (C...) returns 501.Read the account's data entries, in this order of precedence:
Data entry name Meaning app.xlm_sh.ipfsIPFS record app.xlm_sh.ipnsIPNS record ipfsIPFS record (legacy name) ipnsIPNS record (legacy name) The first one present is used. If none is present, the response is 404.
Serve the content from IPFS.
A site whose name, CID or root CID has been blocked returns 451 at whichever step it is found. Every error page links to Troubleshooting.
The app.xlm_sh.* names follow the SEP-18 data entry namespacing convention. Prefer them over the legacy names, and remove entries you no longer use so the precedence never surprises you.
Values
A data entry value is at most 64 bytes. It must be one of:
- An IPFS CID (in
app.xlm_sh.ipfs), for examplebafybeifq2rzpqnqrsdupncmkmhs3ckxxjhuvdcbvydkgvch3ms24k5lo7qorQmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB. - An IPNS key (in
app.xlm_sh.ipns), for examplek51qzi5uqu5dlvj2baxnqndepeb86cbk3ng7n3i46uzyxzyqj2xjonzllnv0v8. - A domain name with a DNSLink record, for example
ipfs.web.example.com(in either entry). xlm.sh then reads the TXT record_dnslink.ipfs.web.example.com:dnslink=/ipfs/<cid>ordnslink=/ipns/<key>;- if there is one
/ipfs/record and one/ipns/record, the/ipfs/one wins; - several records of the same kind are an error (503).
Only the bare value: no /ipfs/ prefix, no ipfs:// and no URL.
Setting the record
Use a Manage Data operation from the account the domain points to:
Operation: Manage Data
Name: app.xlm_sh.ipfs
Value: bafybeifq2rzpqnqrsdupncmkmhs3ckxxjhuvdcbvydkgvch3ms24k5lo7qEach data entry raises the account's minimum balance by one base reserve (0.5 XLM) for as long as it exists. To remove an entry, send Manage Data with the same name and no value. The form in How to set up a site builds this transaction for you, and removes the other xlm.sh entries at the same time.
Checking the record
Any Stellar explorer shows an account's data entries. With Horizon, for example:
GET https://horizon.stellar.org/accounts/<account>/data/app.xlm_sh.ipfsreturns the value base64-encoded:
{ "value": "YmFmeWJlaWZxMnJ6cHFucXJzZHVwbmNta21oczNja3h4amh1dmRjYnZ5ZGtndmNoM21zMjRrNWxvN3E=" }Responses from xlm.sh carry an x-ipfs-roots header with the CID being served, which tells you whether a new record has been picked up.
Caching
- The domain and the record are cached for 30 seconds on each gateway.
- Pages are sent with
Cache-Control: public, max-age=60, so browsers and Cloudflare may keep a page for up to a minute.
A change usually shows up within two minutes. IPNS and DNSLink updates can take longer, because IPFS nodes cache an IPNS record and DNS resolvers cache a TXT record for their own TTLs. If Stellar RPC is unreachable, the gateway keeps serving the last known record for up to an hour.