RADIX WikiRADIX Wiki

Introduction

You have a component deployed and a front end wired up with the Radix dApp Toolkit. You click Connect, and the Radix Wallet either shows your dApp as unknown or refuses the request outright. Nothing is broken: you have not yet told the ledger that this website and these entities belong to the same dApp.

That registration is a dApp Definition – an ordinary account whose metadata has been set to describe your application. It is the hub that ties your packages, components, resources, and website together, and it is what lets the wallet tell a user that the site asking for their account is the one that owns the component it claims to own. On Mainnet it is not optional.

What the Metadata Does

A dApp Definition account carries a handful of metadata entries:

  • account_type set to dapp definition – the flag that makes the account a dApp Definition rather than a normal one.
  • name, description, tags, icon_url – the display fields the wallet shows whenever your dApp sends a request. These are what turn "an unknown site wants your account" into a recognisable prompt.
  • claimed_websites – the origins you assert this dApp runs on.
  • claimed_entities – the packages, components, and resources that belong to this dApp.

The claims are two-way. The account states that it owns a website, and the website has to state that it belongs to the account – which is what stops anyone from claiming your domain by writing your URL into their own metadata.

Setting One Up

Do this once your components and front end exist, since you need their addresses and origin to claim them.

  1. Create a fresh account in the Radix Wallet – this one becomes the dApp Definition, so keep it separate from an account you hold funds in.
  2. Open the Developer Console and connect your wallet, sharing that account. Note that it sets Mainnet definitions only: there is no hosted Stokenet console (stokenet-console.radixdlt.com returns HTTP 530, checked 14 August 2026), so use ShardSpace below while you are learning, or run a Stokenet console of your own as described in Deploying to Stokenet and Mainnet.
  3. On Configure Metadata, enter the account address and search for it.
  4. Set account_type to dapp definition, then fill in name, description, tags, and icon URL.
  5. Fill in claimed_websites with your dApp's origin, and claimed_entities with your component, package, and resource addresses.
  6. Send the transaction to the wallet and approve it. The metadata is now on-ledger.

ShardSpace is a community-built alternative to the console for creating and managing dApp definitions on both networks.

Proving the Website Side

Claiming an origin in metadata is only half the handshake. The wallet then fetches /.well-known/radix.json from that origin and expects to find the dApp Definition account address listed there:

{
  "dApps": [
    { "dAppDefinitionAddress": "account_rdx12y..." }
  ]
}

Serve that file at the exact origin you claimed – scheme, host, and port all have to match, and www.example.com is not example.com. Until both directions agree, Mainnet requests from your dApp will not reach the wallet.

When Verification Fails

  • Origin mismatch – the most common cause. Check the claimed string against what the browser actually sends.
  • File not served as JSON – some hosts return the SPA shell for unknown paths, so the wallet receives HTML instead of the manifest. Fetch the URL yourself and check the response body.
  • Wrong network – a Stokenet dApp Definition does not verify a Mainnet dApp. They are separate accounts on separate ledgers.
  • Address typo in claimed_entities – the wallet will connect, but your component will not display as part of the dApp.

The 29 August 2026 Stokenet reset breaks one half of this

Stokenet is wiped at 07:00 UTC on Saturday 29 August 2026 (announced 18 August; terms on the Stokenet page). The handshake described above is two-sided, and the reset takes exactly one side:

  • The ledger side is destroyed. dApp Definition accounts keep their addresses – those are derived from your keys – but the metadata that makes one a definition is stored state, so account_type, name, claimed_websites and claimed_entities are all gone. The account reverts to an ordinary one. The packages and components it claimed are gone too, and re-publishing gives them new addresses, so claimed_entities cannot simply be re-entered from your notes.
  • The website side survives. /.well-known/radix.json lives on your own origin, not on the ledger, and nothing touches it. If you keep the same dApp Definition account, the file stays correct and needs no edit – which is a reason to reuse that account rather than create a fresh one after the reset.

On-ledger persona data is destroyed as well, so a tester who had connected to your dApp recreates their persona before they can connect again. Mainnet definitions are untouched.

Next Steps

  • Radix APIs – choose the right API once your dApp needs a backend
  • Building on Radix – the wider index of tooling, SDKs, and community services
HydrateLast updated 2d agov1.3.38 revisionsVerified Aug 14, 2026