Skip to content

Record specification ​

How xlm.sh finds the content of https://<name>.xlm.sh.

Resolution ​

  1. Take <name>. It must be 1 to 15 letters a-z. Any other host name, including one with a hyphen or a period, returns 404.

  2. Look up <name>.xlm in the Soroban Domains registry v1 (CATRNPHYKNXAPNLHEYH55REB6YSAJLGCPA4YM6L3WUKSZOPI77M2UMKI). A missing or expired domain returns 404.

  3. The domain must point to a Stellar account (G...). A contract address (C...) returns 501.

  4. Read the account's data entries, in this order of precedence:

    Data entry nameMeaning
    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.

  5. 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 example bafybeifq2rzpqnqrsdupncmkmhs3ckxxjhuvdcbvydkgvch3ms24k5lo7q or QmPK1s3pNYLi9ERiq3BDxKa4XosgWwFRQUydHUtz4YgpqB.
  • An IPNS key (in app.xlm_sh.ipns), for example k51qzi5uqu5dlvj2baxnqndepeb86cbk3ng7n3i46uzyxzyqj2xjonzllnv0v8.
  • 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> or dnslink=/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:     bafybeifq2rzpqnqrsdupncmkmhs3ckxxjhuvdcbvydkgvch3ms24k5lo7q

Each 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.ipfs

returns the value base64-encoded:

json
{ "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.