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 still returns HTTP 530, re-checked 21 September 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 took one half of this

Stokenet was wiped at 07:00 UTC on Saturday 29 August 2026 (announced 18 August; terms on the Stokenet page), and the ledger serving Stokenet today begins there rather than carrying anything across. Its first timestamped round is 11:47:06 UTC on 29 August 2026, at epoch 3, and the network stood at epoch 6,876 and state version 11,740,045 at 08:52:38 UTC on 21 September 2026 – both read from the Gateway, the first from /stream/transactions ordered ascending and the second from /status/gateway-status. The handshake described above is two-sided, and the reset took exactly one side:

  • The ledger side went. 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 did not survive. Such an account is an ordinary one again. The packages and components it claimed went too, and re-publishing gives them new addresses, so claimed_entities cannot simply be re-entered from your notes.
  • The website side survived. /.well-known/radix.json lives on your own origin, not on the ledger, and nothing touched it. If you kept the same dApp Definition account, the file is still correct and needs no edit – which was the reason to reuse that account rather than create a fresh one.

On-ledger persona data went as well, so a tester who had connected to your dApp before the reset recreates their persona first. Mainnet definitions were 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 4d agov1.4.09 revisionsVerified Sep 21, 2026