Message Contracts

All six messages are listed below, grouped by direction. For enums (WEB3_KIT_MESSAGE_TYPES, AUTH_FAILED_REASON, TWeb3Networks, TConnectorName) and wallet payload types, see Reference.

iframe → parent

WEB3_KIT_INIT

Emitted once when the iframe mounts and has read authToken from its URL.

{
  type: 'WEB3_KIT_INIT',
  payload: {
    authToken: string;     // echo of the authToken from the URL
    connectionId: string;  // UUID generated by the iframe
  }
}

Host action: save connectionId, mark the iframe as ready.

WEB3_KIT_SIGNATURE_MSG

Reply to WEB3_KIT_GET_SIGNATURE_MSG. Carries the data the wallet has to sign.

{
  type: 'WEB3_KIT_SIGNATURE_MSG',
  payload: {
    connectionId: string;
    nonce: string;     // single-use, short-lived (~5 min) identifier from the backend
    message: string;   // the string to feed into personal_sign (or equivalent)
  }
}

Host action: ask the wallet to sign message, keep nonce for the next step.

If the backend /web3/signature call fails, the iframe sends WEB3_KIT_AUTH_FAILED with reason: 'unknown' instead.

WEB3_KIT_AUTH_DATA

Successful authentication — either a plain login or a register-and-login (when the wallet is new).

{
  type: 'WEB3_KIT_AUTH_DATA',
  payload: {
    connectionId: string;
    token: string;          // JWT auth token
    refreshToken: string;   // JWT refresh token
    isNew: boolean;         // true if this call registered a brand-new user, false for a returning login
  }
}

Host action: persist token / refreshToken and close or hide the iframe. Use isNew to branch the host UX — e.g. send a first-time user through onboarding/welcome screens vs. dropping a returning user straight into the app. The flag reflects whether the underlying register-and-login path was taken; it does not change the shape of token / refreshToken.

WEB3_KIT_AUTH_FAILED

Any non-success outcome anywhere in the flow.

{
  type: 'WEB3_KIT_AUTH_FAILED',
  payload: {
    connectionId: string;
    reason: AUTH_FAILED_REASON; // 'banned' | 'deleted' | 'unknown'
    message?: string;            // free-form text from the originating error, when available
  }
}

Reason mapping:

reason	Origin	Suggested host reaction
banned	POST /web3/authenticate returned 400 with body { error: 'User is banned' }.	Show a "banned" screen.
deleted	POST /web3/authenticate returned 400 with body { error: 'User is deleted' }.	Show an "account deleted" screen.
unknown	Network failure, signature endpoint failure, failed register+login, unexpected 400/500 bodies.	Show a generic error and offer retry.

parent → iframe

WEB3_KIT_GET_SIGNATURE_MSG

Asks the iframe to fetch a fresh signing payload from the backend.

{
  type: 'WEB3_KIT_GET_SIGNATURE_MSG',
  payload: {
    connectionId: string;
    network: TWeb3Networks;  // 'eth' | 'sol' | 'ton'
  }
}

The iframe responds with WEB3_KIT_SIGNATURE_MSG or WEB3_KIT_AUTH_FAILED.

WEB3_KIT_AUTH_BY_WALLET

Submits the wallet-signed payload to the iframe for authentication.

{
  type: 'WEB3_KIT_AUTH_BY_WALLET',
  payload: {
    connectionId: string;
    nonce: string;                  // from the previous SIGNATURE_MSG
    payload: WalletPayload;         // wallet-specific signed payload (see Reference)
    cryptoProvider: TConnectorName; // 'meta_mask' | 'wallet_connect' | ...
    network: TWeb3Networks;         // 'eth' | 'sol' | 'ton'
  }
}

Note the nested payload.payload. The inner payload is the wallet payload itself (for ETH this is { address, signature }); the outer payload is the message envelope. The shape { nonce, payload, cryptoProvider, network } is identical to the parameters of WalletsPage.loginAction in the standard web flow, so the host can reuse the same construction logic.

The iframe responds with WEB3_KIT_AUTH_DATA on success or WEB3_KIT_AUTH_FAILED on failure.