---
title: "4. dApp Definition and Wallet Verification"
path: "/developers/frontend/04-dapp-definition-and-verification"
version: "1.1.0"
author: "Hydrate"
createdAt: "2026-07-27T17:50:53.645Z"
updatedAt: "2026-07-27T17:54:25.996Z"
---

# 4. dApp Definition and Wallet Verification

<Infobox>
| 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.radixdlt.com/) or [ShardSpace](https://shardspace.app/) |
</Infobox>

## Introduction

You have a component 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, 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. $1

2. $1

3. $1

4. $1

5. $1

6. $1

[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.

## Next Steps

- [Radix APIs](/developers/infrastructure/02-radix-apis) — choose the right API once your dApp needs a backend

- [Radix Developer Resources](/developers/radix-developer-resources) — 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)

- [Radix Developer Console](https://console.radixdlt.com/)

- [ShardSpace — community dApp definition manager](https://shardspace.app/)