Skip to main content

Linking to Walrus Sites from External Sources

You address a Walrus Site through a portal. The portal resolves the site from an onchain object and serves its content. To link to a Walrus Site from an external source, you construct a URL that the portal can resolve. There are 2 ways to identify a site in that URL: by its SuiNS name, or by its Sui object ID.

What does a Walrus Sites URL look like?​

Walrus Sites URLs follow this pattern:

https://IDENTIFIER.PORTAL_HOST/PATH
  • IDENTIFIER: Either a SuiNS name or a Base36-encoded Sui object ID.
  • PORTAL_HOST: The hostname of the portal serving the site. The default public Mainnet portal is wal.app.
  • PATH: An optional path to a specific resource within the site.

If a site owner has registered a SuiNS name and pointed it at their site object, you can link using that name as the subdomain.

https://SUINS_NAME.wal.app

For example, a site registered under the name myproject is reachable at:

https://myproject.wal.app

SuiNS names are human-readable and stable as long as the owner maintains the registration and it continues to point at the correct site object. If the owner transfers the site object or re-registers the name to a different object, links using the SuiNS name resolve to the new target.

info

The portal performs SuiNS name resolution onchain at request time. A name that is expired, not registered, or not pointed at a site object returns an error.

Every Walrus Site has a Sui object ID. You can use the object ID as the subdomain in place of a SuiNS name. Because subdomain labels are case-insensitive and limited to 63 characters, you must encode the object ID as Base36 rather than use it as a hex string. The site-builder tool outputs the Base36-encoded subdomain URL for you when you deploy a site, and you can also convert a hex object ID to Base36 using the site-builder convert command.

https://BASE36_OBJECT_ID.wal.app

For example:

https://58gr4pinoayuijgdixud23441t55jd94ugep68fsm72b8mwmq2.wal.app

Object ID links are permanent. They resolve to the same site object regardless of whether the SuiNS name changes or the owner transfers it. Use object ID links when stability matters, such as in documentation, bookmarks, or application configurations.

tip

Prefer object ID links in any context where you expect the URL to remain valid long-term. SuiNS name links are more readable but depend on the name registration staying current.

How to link to a specific page or resource​

Append a path after the portal hostname to link directly to a resource within the site. The path resolves against the site object's stored resources.

https://IDENTIFIER.wal.app/PATH

For example, to link to the /docs/getting-started page of a site:

https://myproject.wal.app/docs/getting-started

Or using a Base36 object ID:

https://BASE36_OBJECT_ID.wal.app/docs/getting-started

The path must match a resource stored in the site object. If the path does not match any resource and the site does not define a custom 404 resource, the portal returns a default error.

The public Mainnet portal at wal.app is the default, but other portals exist and site owners might host their own. To link through a specific portal, replace wal.app with that portal's hostname.

https://IDENTIFIER.PORTAL_HOST

The portal you link through does not change which site object it resolves. Any portal that supports Walrus Sites resolves the same onchain object for a given identifier. The choice of portal affects availability and trust, not content.

When building applications or tools that generate links to Walrus Sites, use the object ID rather than a SuiNS name to avoid resolution failures caused by name changes.

A basic pattern in JavaScript:

const PORTAL_HOST = "wal.app";
 
function walrusSiteUrl(base36ObjectId, path = "") {
  return `https://${base36ObjectId}.${PORTAL_HOST}${path}`;
}
 
// Example: link to the /blog page of a site
const url = walrusSiteUrl("58gr4pinoayuijgdixud23441t55jd94ugep68fsm72b8mwmq2", "/blog");

If you want to support both identifiers, accept either a SuiNS name or an object ID as the subdomain segment and pass it through directly.

Common patterns​

The following examples cover typical inbound linking scenarios. In these examples, replace BASE36_OBJECT_ID with the site's Base36 object ID (for example, 58gr4pinoayuijgdixud23441t55jd94ugep68fsm72b8mwmq2) and SUINS_NAME with its SuiNS name (for example, myproject).

Linking from a README​

[View the live site](https://BASE36_OBJECT_ID.wal.app)

Linking from an HTML page​

<a href="https://SUINS_NAME.wal.app">Visit the project site</a>

Linking to a specific resource from an HTML page​

<a href="https://SUINS_NAME.wal.app/docs">Read the documentation</a>

Embedding a Walrus Site in an iframe​

<iframe src="https://BASE36_OBJECT_ID.wal.app" width="100%" height="600"></iframe>

Prefer object IDs in embedded contexts because the framed content does not change if a SuiNS name is updated.