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 — the Stokenet console while you are learning, the Mainnet one when you ship — and connect your wallet, sharing that account.
  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.

Next Steps