gamechanger.wallet

Universal Dapp Connector / URL Patterns

Wallet URL patterns, routing and returning data

You already know what the Universal Dapp Connector is and why it exists. Now it is time to look at the actual thing that travels between apps, devices and wallets: the URL itself.

This page explains:

Later sections will teach how to write these scripts yourself in GCScript DSL, how to inspect and edit them in Playground IDE, and how to use them for actual transactions, workspaces, frontends, backends and hardware flows.

These patterns are useful for:

These can be represented as:

The base pattern

With the current single-domain release there is one wallet domain for all supported networks and DLTs:

https://wallet.gamechanger.finance/

A wallet request URL (a “dapp connection”, or the result of a “dapp connection”) is usually built from:

A common example looks like this:

https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA

And that same URL may also include router and attribution query parameters:

https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?networkTag=preprod&ref=addr_test1q...

The encoded payload may change length and shape depending on encoding, compression and script size, but the surrounding URL pattern stays the same.

If you are curious about the script living inside that payload, the next documentation sections will show how to write it manually using GCScript DSL.

The Network Router

The Network Router is the feature that allows a dapp, agent, backend, QR code, NFC tag, device or plain URL to request that the wallet opens on a specific DLT and network.

It uses these query parameters:

dltTag=<dlt>
networkTag=<network>

Current defaults are:

dltTag=cardano
networkTag=mainnet

That means all of these are valid patterns:

https://wallet.gamechanger.finance/

https://wallet.gamechanger.finance/?networkTag=mainnet
https://wallet.gamechanger.finance/?dltTag=cardano&networkTag=mainnet
https://wallet.gamechanger.finance/?networkTag=preprod
https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?networkTag=preprod
https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?dltTag=cardano&networkTag=preprod

When the requested DLT or network is different from the current wallet state, the wallet may show a confirmation screen with:

If the requested values are invalid, an error screen is expected.

Why this matters now

Older documentation and examples may still show subdomain-based wallet links. The official v2 release uses one single production wallet domain, so routing is now expressed through query parameters instead of subdomain selection.

This makes links more portable:

If you were using CIP-30 dapp connectors: get ready to think outside the box! You are not targetting desktop-only use cases anymore with UDC, RPCs and real-time bidirectional channels give many assumptions for granted regarding connections. When aiming for real world use-cases beyond desktop requirements differ.

Important default behavior

For wallet-facing v2 handlers, the recommended default is to include:

networkTag=<network>

unless explicitly disabled.

This makes generated links and QRs deterministic under the single-domain wallet and avoids relying on the current user wallet state.

This makes links, QRs and URLs more predictable for dapps and automation, especially under the single-domain design.

This being said, if you are not sure about enforcing network and DLT flavor for example if you just want to share a casual link to the wallet, just don’t do it. Don’t force network and DLT switches for no good reason.

When to use it

Use the Network Router when:

Avoid relying on the current user wallet state when the request is network-sensitive.

The referrer parameter

Wallet URLs may also include a referrer address using:

ref=<address>

Example:

https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?networkTag=mainnet&ref=addr1q...

This is a generic referrer feature. It can be used by present or future campaigns, integrations, affiliate systems, attribution flows or reward programs without changing the core wallet URL pattern.

A few practical notes:

Combining router and referrer

A common pattern is:

https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?networkTag=preprod&ref=addr_test1q...

This requests:

URL patterns can vary

The exact URL varies depending on intent.

1) Open the wallet home on a network

https://wallet.gamechanger.finance/?networkTag=preprod

2) Open a specific wallet request

https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?networkTag=mainnet

3) Open a request with explicit DLT and network

https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?dltTag=cardano&networkTag=preprod

4) Open a request with a referrer

https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?networkTag=mainnet&ref=addr1q...

5) Open the wallet home and request only a network switch

https://wallet.gamechanger.finance/?dltTag=cardano&networkTag=preprod

This is useful when the goal is only to place the wallet on the desired environment before the next manual action.

6) Return data to an external site after execution

https://my-dapp.example/returnURL?result=1-H4sIAAAAA...AAAA

In this case the wallet has already processed the DSL script, and results are being exported back to the dapp using a query string. You can customize this behaviour and also pass the response payload using URL sub paths.

Returning data from the wallet

Capturing a returned URL is optional, but it is one of the most useful integration patterns of the UDC.

A script may define a returnURLPattern, and after execution the wallet can redirect the user back to an external URL carrying the encoded result.

The important detail is that these URLs are generated in-wallet by the DSL code itself using the returnURLPattern argument. Is a simple string template. The script developer decides where {result} should be inserted.

Query-string style pattern

{
    "type":"script",
    "returnURLPattern":"https://my-dapp.example/returnURL?result={result}"
}

This produces something like:

https://my-dapp.example/returnURL?result=1-H4sIAAAAA...AAAA

Subpath style pattern

{
    "type":"script",
    "returnURLPattern":"https://my-dapp.example/returnURL/{result}/view"
}

This produces something like:

https://my-dapp.example/returnURL/1-H4sIAAAAA...AAAA/view

So the payload can travel:

Then the external app, frontend or backend can:

Typical return flow

  1. A dapp, device or backend generates a wallet URL
  2. The user opens it
  3. The wallet executes the request
  4. The wallet redirects back to the configured return URL
  5. The external app extracts the packed result and decodes it

Frontend-style example

const currentUrl = window.location.href;
const resultRaw = new URL(currentUrl).searchParams.get('result');
// decode resultRaw here

Backend-style example

app.get('/returnURL', async (req, res) => {
    const resultRaw = req.query.result;
    // decode resultRaw here
});

Returning data is not mandatory and user may intercept and reject a return URL by UDC design to preserve privacy. This encourage the design of systems where user is in full control of the shared data to dapps.

Also by customizing UDC transport layer you can receive action requests (DSL) and even return resulting data back to dapps or hardware all using QR codes embedding these URLs, for air-gapped connections and real world use cases.

You will see these scripts and return patterns again in upcoming GCScript DSL pages, and you can inspect them live in Playground IDE.

QR patterns

A QR code is not a different protocol. It is simply one of these same URL patterns encoded as a QR image.

That means:

Example QR pattern

This repository includes an example QR code generated from a wallet URL:

Example QR code

And the underlying idea is still just a URL like this:

https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?networkTag=mainnet&ref=addr1q...

The difference is only the transport:

Generating these URLs programmatically

You do not need to build these patterns by hand.

The recommended tools are:

The official library can help generate:

The CLI can help from scripts, shells, CI pipelines, backend jobs or device-side tooling.

This is specially useful when:

Multi-network scripts

Some scripts can be written to adapt themselves to the current wallet network and DLT instead of hardcoding parameters.

A common pattern is:

This is especially useful for:

We will cover GCScript DSL and ISL soon, but for now this code snippet shows how this can be implemented:

{
    "networkInfo": {
        "type": "getNetworkInfo"
    },
    "networkKey": {
        "type": "macro",
        "run": "{ join('-',get('cache.networkInfo.dltTag'),get('cache.networkInfo.networkTag')) }"
    }
}

That approach is often better than publishing separate scripts when the business logic is the same and only the parameters vary.

You will learn how to write these scripts properly on the next GCScript DSL pages.

Common integration patterns

💡 Click to explore common URL patterns and integration techniques... ### 🔵 Static link on HTML ```html Launch wallet request ``` ### 🔵 Popup launch on HTML ```html Launch GC in Popup Mode ``` ### 🔵 Static link on markdown ```md [Launch wallet request](https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?networkTag=preprod) ``` ### 🔵 Backend redirect ```js app.get('/url', async (req, res) => { const url = "https://wallet.gamechanger.finance/api/2/run/1-H4sIAAAAA...AAAA?networkTag=preprod"; res.redirect(url); }); ``` ### 🔵 Return URL pattern using query string ```json { "returnURLPattern":"https://my-dapp.example/returnURL?result={result}" } ``` ### 🔵 Return URL pattern using subpath ```json { "returnURLPattern":"https://my-dapp.example/returnURL/{result}/view" } ```

Kitchen Sink playground

For a practical way to try these patterns, render outputs, inspect snippets and preview different launch modes, check:

Kitchen Sink

It is a useful place to:

For embedded or iframe-based previews, keep in mind that wallet may restrict execution in embedded contexts. A preview frame may fail even when the generated method itself is valid.

Practical rules of thumb

Previous: Overview Home: General Documentation
This site is open source. Improve this page.