Reference

The enums below are exported from src/pages/Web3KitPage/Web3KitPage.tsx. The wallet payload types live in src/modules/Web3/blockchains/{ETH,SOL,TON}/types.ts.

WEB3_KIT_MESSAGE_TYPES

enum WEB3_KIT_MESSAGE_TYPES {
  // iframe → parent
  INIT              = 'WEB3_KIT_INIT',
  SIGNATURE_MSG     = 'WEB3_KIT_SIGNATURE_MSG',
  AUTH_DATA         = 'WEB3_KIT_AUTH_DATA',
  AUTH_FAILED       = 'WEB3_KIT_AUTH_FAILED',

  // parent → iframe
  GET_SIGNATURE_MSG = 'WEB3_KIT_GET_SIGNATURE_MSG',
  AUTH_BY_WALLET    = 'WEB3_KIT_AUTH_BY_WALLET',
}

AUTH_FAILED_REASON

enum AUTH_FAILED_REASON {
  BANNED  = 'banned',
  DELETED = 'deleted',
  UNKNOWN = 'unknown',
}

TWeb3Networks

enum TWeb3Networks {
  ETH = 'eth',
  SOL = 'sol',
  TON = 'ton',
}

eth is the only network with a fully validated end-to-end iframe flow in the current version (see Limitations).

TConnectorName

export type TConnectorName =
  | 'meta_mask'
  | 'trust_wallet'
  | 'wallet_connect'
  | 'hero'
  | 'phantom'
  | 'ton_keeper';

Closed string-literal union identifying the wallet that produced the signature. The same value is sent in WEB3_KIT_AUTH_BY_WALLET.payload.cryptoProvider and is what the backend uses to pick the correct signature-verification path. Values are stable wire identifiers — do not localize or transform them on the host side.

Value	Wallet	Network (TWeb3Networks)	Typical host-side connector	Notes
'meta_mask'	MetaMask	eth	Injected EIP-1193 / wagmi	Browser extension or mobile in-app browser. The reference flow in Integration example uses this value.
'trust_wallet'	Trust Wallet	eth	WalletConnect or injected	Use this value (not 'wallet_connect') when the user explicitly chose Trust Wallet on the host UI, even if the transport underneath is WalletConnect.
'wallet_connect'	WalletConnect	eth	@walletconnect/* / web3modal	Generic fallback when the host cannot identify the specific wallet behind the WalletConnect session.
'hero'	Hero Wallet	eth	Hero in-app provider	Reserved for the first-party Hero wallet integration.
'phantom'	Phantom	sol	Phantom injected provider	Solana-only. Pair with network: 'sol' and a SOLPayload.
'ton_keeper'	Tonkeeper	ton	TonConnect	TON-only. Pair with network: 'ton' and a TONPayload.

note

Only the eth network has a fully validated end-to-end iframe flow in the current version (see Limitations). phantom and ton_keeper are part of the contract but exercise code paths that are not yet covered end-to-end via the iframe.

Choosing the right value

1. Read the wallet identifier from your host-side connector (e.g. connector.id in wagmi, or the user's explicit selection in your wallet-picker UI).
2. Map it to one of the literals above — never invent or pass through an arbitrary string. Unknown values are rejected by Web3Kit and surface as AUTH_FAILED_REASON.UNKNOWN_ERROR.
3. Pass it in cryptoProvider together with a network value from TWeb3Networks that matches the wallet's chain — the backend cross-checks the two.

Wallet payload (WalletPayload)

The shape of the inner payload of WEB3_KIT_AUTH_BY_WALLET depends on the network value sent alongside it. The host produces this object after the user signs the message returned in WEB3_KIT_SIGNATURE_MSG.

type WalletPayload = ETHPayload | SOLPayload | TONPayload;

The discriminator is the sibling network field on WEB3_KIT_AUTH_BY_WALLET.payload, not a tag inside WalletPayload itself — the backend selects the verifier from network and then decodes payload accordingly.

ETHPayload (network: 'eth')

export interface ETHPayload {
  address: string;    // 0x-prefixed signer address (EIP-55 or lowercase)
  signature: string;  // hex signature of `message` from WEB3_KIT_SIGNATURE_MSG
}

• address is recovered from signature on the backend and must equal the one passed here.
• signature is produced by personal_sign / eth_sign over the exact message string — do not re-hash or re-encode.

SOLPayload (network: 'sol')

export interface SOLPayload {
  address: string;    // base58-encoded Solana public key of the signer
  signature: string;  // base58-encoded ed25519 signature of `message`
}

• address is the wallet's public key as returned by Phantom (publicKey.toBase58()).
• signature is the output of wallet.signMessage(new TextEncoder().encode(message)) encoded as base58. Pair this payload with cryptoProvider: 'phantom'.

TONPayload (network: 'ton')

import type { Account, TonProofItemReplySuccess } from '@tonconnect/sdk';

export interface TONPayload {
  account: Account;                                  // from TonConnect connect event
  ton_proof: TonProofItemReplySuccess['proof'];      // from TonConnect ton_proof reply
}

• account is the full Account object returned by TonConnect (address, chain, walletStateInit, publicKey). The backend uses walletStateInit + publicKey to verify the proof against address.
• ton_proof is the inner proof object of a successful ton_proof reply — i.e. TonProofItemReplySuccess['proof'], not the whole reply. It carries timestamp, domain, payload, and signature; the payload value must equal the message delivered in WEB3_KIT_SIGNATURE_MSG. Pair this payload with cryptoProvider: 'ton_keeper'.

caution

SOLPayload and TONPayload are part of the message contract but are not yet validated end-to-end through the iframe in the current version (see Limitations). Treat the shapes as stable, but expect the eth path to be the only one with full coverage today.

Full TypeScript interfaces

interface InitMessage {
  type: 'WEB3_KIT_INIT';
  payload: { authToken: string; connectionId: string };
}

interface GetSignatureMsgMessage {
  type: 'WEB3_KIT_GET_SIGNATURE_MSG';
  payload: { connectionId: string; network: TWeb3Networks };
}

interface SignatureMsgMessage {
  type: 'WEB3_KIT_SIGNATURE_MSG';
  payload: { connectionId: string; nonce: string; message: string };
}

interface AuthByWalletMessage {
  type: 'WEB3_KIT_AUTH_BY_WALLET';
  payload: {
    connectionId: string;
    nonce: string;
    payload: WalletPayload;
    cryptoProvider: TConnectorName;
    network: TWeb3Networks;
  };
}

interface AuthDataMessage {
  type: 'WEB3_KIT_AUTH_DATA';
  payload: {
    connectionId: string;
    token: string;
    refreshToken: string;
    isNew: boolean; // true when this call registered a new user, false on returning login
  };
}

interface AuthFailedMessage {
  type: 'WEB3_KIT_AUTH_FAILED';
  payload: {
    connectionId: string;
    reason: AUTH_FAILED_REASON;
    message?: string;
  };
}

type Web3KitMessage =
  | InitMessage
  | GetSignatureMsgMessage
  | SignatureMsgMessage
  | AuthByWalletMessage
  | AuthDataMessage
  | AuthFailedMessage;