---
title: "4. dApp Definition and Wallet Verification"
url: "https://radix-wiki.miow.me/developers/frontend/04-dapp-definition-and-verification"
updated: 2026-10-03
description: "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…"
---

# 4. dApp Definition and Wallet Verification

|  |  |
| --- | --- |
| What it is | An account whose metadata registers your dApp |
| Key metadata | `account_type`, `claimed_websites`, `claimed_entities` |
| Website proof | `/.well-known/radix.json` at the claimed origin |
| Required on | Mainnet – the wallet rejects unverified requests |
| Set up with | [Developer Console](https://console.radixscan.io) (Mainnet) or [ShardSpace](https://shardspace.app/) (both networks) |

# 4. dApp Definition and Wallet Verification

## Introduction

You have a [component](/contents/tech/core-concepts/components) deployed and a front end wired up with the [Radix dApp Toolkit](/developers/frontend/01-radix-dapp-toolkit). You click Connect, and the [Radix Wallet](/contents/tech/core-protocols/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](/contents/tech/core-concepts/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](/contents/tech/core-concepts/metadata-module) 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](https://console.radixscan.io) 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](/developers/getting-started/03-deploying).
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](https://shardspace.app/) 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](https://t.me/radix_dlt/998662); terms on the [Stokenet](/contents/tech/releases/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](/contents/tech/core-protocols/radix-gateway-api), 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](/contents/tech/core-protocols/personas) 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](/developers/infrastructure/02-radix-apis) – choose the right API once your dApp needs a backend
- [Building on Radix](/developers) – the wider index of tooling, SDKs, and community services

## External Links

- [dApp Definition Setup – Radix Documentation](https://docs.radixdlt.com/docs/dapp-definition-setup)
- [Metadata for Verification – Radix Documentation](https://docs.radixdlt.com/docs/metadata-for-verification)
- [RadixScan Developer Console](https://console.radixscan.io/) – the Mainnet console; `console.radixdlt.com` answers HTTP 302 to it (checked 21 September 2026)
- [ShardSpace – community dApp definition manager](https://shardspace.app/)