Launch a request

A safe launch has three steps: create a typed request, wrap it in a v2 envelope, and open the generated glyph:// URL. Choose the delivery route before creating the envelope. Relay v2 does not require a callback page or public callback route in the dApp; a direct callback and browser redirect flow do.

Direct callback delivery

Use a callback when your server should receive a POST from Glyph Wallet:

import {
  createEnvelope,
  createTransferRequest,
  launchGlyphRequest,
} from "@glyph-oss/connect";

const request = createTransferRequest({
  type: "transfer",
  dapp: { name: "Example", origin: "https://example.app" },
  to: recipientIdentity,
  amount: "1000",
});

const envelope = createEnvelope(request, {
  callback: "https://example.app/api/glyph/callback",
});

const deepLink = launchGlyphRequest(envelope);
console.log(deepLink);

The callback URL must use HTTPS, contain no credentials, target a global address, and match dapp.origin. The SDK computes request_hash over the request, delivery fields, and network before encoding the envelope.

At the callback endpoint, read JSON and use verifyCallbackEnvelope() with the original request and envelope bindings. See strict callback verification.

Browser promise flow

For a browser-only flow, glyphRequest() opens the wallet and waits on a BroadcastChannel:

import { k12, verify } from "@qubic.org/crypto";
import {
  createConnectRequest,
  glyphRequest,
  handleRedirect,
} from "@glyph-oss/connect";

const result = await glyphRequest(
  createConnectRequest({
    type: "connect",
    dapp: { name: "Example", origin: "https://example.app" },
    permissions: ["transfer", "sign_message"],
  }),
  {
    onStatus(status) {
      if (status.state === "awaiting_approval") {
        showStatus("Continue in Glyph Wallet");
      }
    },
  },
);

Mount handleRedirect() at /__glyph__, or set callbackPath to the route you serve:

await handleRedirect({
  verification: {
    requireSigned: true,
    verifySignature: ({ algorithm, payload, signature, publicKey }) => {
      if (algorithm !== "qubic-schnorrq-sha256") return false;
      return verify(k12(payload, 32), signature, publicKey);
    },
  },
});

glyphRequest() creates a redirect envelope, opens the wallet, and waits for the result broadcast. It always requires a signed callback envelope when resolving the promise. The redirect page should call handleRedirect() before the page closes.

The callback verifier is dApp-side verification using @qubic.org/crypto. Glyph Wallet remains responsible for signing after the user approves the request. The browser example therefore contains no seed, private key, or custom wallet signer.

Request status

Both browser and Relay flows can report transport state through onStatus:

• opening_wallet: the SDK is opening the deep link.
• awaiting_approval: the wallet or stream is waiting for user action.
• completed: a parsed and accepted result is available.
• failed: the request or verification failed with an Error.

Transport completion is not a substitute for checking the result's status. A completed request may be an explicit rejected result.