Signature

Endpoint: /action/signature

Asks the currently logged-in WalletTwo user to sign an arbitrary text message using their wallet's private key. The resulting cryptographic signature is returned to the host page via postMessage and optionally via redirect.

Use this when you need to prove that a specific WalletTwo user controls a given wallet address, or when you need a signed payload for your own on-chain or off-chain logic.

---

Required user state

Check	Middleware	Redirects to if missing
User is logged in	LoggedMiddleware	/auth/login
Email is verified	EmailVerifiedMiddleware	/auth/email/verify
Wallet is created	WalletMiddleware	/auth/wallet/register

---

Iframe URL

https://<WALLETTWO_ORIGIN>/action/signature?iframe=true&message=<ENCODED_MESSAGE>

Parameters:

Param	Required	Type	Description
message	Yes	string	The raw text message to sign. Must be URL-encoded
redirect_uri	No	string (absolute URL)	If provided, iframe navigates here after signing
iframe	Yes (for embedding)	"true"	Activates bare rendering mode

Full example:

https://<WALLETTWO_ORIGIN>/action/signature?iframe=true&message=Please%20verify%20your%20identity&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback

If message is not supplied, the action renders the signing UI but nothing happens (no signing, no events).

---

What happens when the action runs

1. On mount, the action calls wallet.signMessage(message).

2. While signing is in progress, a spinner state (isSigning) is shown to the user.

3. On success:

   • window.parent.postMessage(...) is fired.

   • The success state (isSigned) is shown.

   • If redirect_uri is present, a 3-second countdown starts before redirecting.

4. The message preview (truncated to 100 characters) is always shown in the UI so the user knows what they are signing.

---

postMessage event

{
  event: "message_signed",
  message: "<original-message>",
  signature: "<hex-signature>",
  user: "<wallettwo-user-id>",
  wallet: "<wallet-address>"
}

Field	Description
event	Always "message_signed"
message	The original plain-text message that was signed
signature	The EIP-191 personal signature (hex string)
user	WalletTwo internal user ID
wallet	The wallet address that produced the signature

---

redirect_uri callback

After the 3-second countdown, the iframe navigates to:

<redirect_uri>?signature=<hex>&usr=<user-id>&wlt=<wallet-address>

Param	Description
signature	The hex signature
usr	WalletTwo user ID
wlt	Wallet address

---

Verifying the signature on your backend

The signature is a standard EIP-191 personal sign. Verify it with any library that supports eth_sign / personal_sign:

// Node.js example using ethers v6
import { ethers } from "ethers";

function verifySignature(message, signature, expectedWallet) {
  const recovered = ethers.verifyMessage(message, signature);
  return recovered.toLowerCase() === expectedWallet.toLowerCase();
}

The message you verify against must be the exact string you passed in the URL — no extra encoding or modification.

---

Host page integration

<iframe
  id="w2-signature"
  src="https://<WALLETTWO_ORIGIN>/action/signature?iframe=true&message=Verify%20my%20identity%20for%20example.com"
  style="width:420px;height:700px;border:0;"
></iframe>

<script>
  const WALLET_TWO_ORIGIN = "https://<WALLETTWO_ORIGIN>";

  window.addEventListener("message", (event) => {
    if (event.origin !== WALLET_TWO_ORIGIN) return;

    if (event.data?.event === "message_signed") {
      const { signature, message, wallet, user } = event.data;
      // Verify on your backend
      verifyOnBackend(message, signature, wallet, user);
    }
  });
</script>

---

UI states inside the iframe

State	What the user sees
Signing in progress	Spinning border animation + "Signing Message" heading
Signed successfully	Green checkmark + "Message Signed!" + countdown if redirect_uri present
No message param	Signing state mounts but no action is triggered

The iframe always shows a preview of the message (first 100 chars + ... if longer).

---

Security checklist

• Always verify event.origin before trusting the event.

• Always verify the signature server-side against the original message and the expected wallet address.

• Do not rely solely on the wallet field returned in the event — confirm it matches by recovering the signer from the signature itself.

• Be specific about what can be signed: restrict the message parameter to the exact challenge string your backend issues. Avoid accepting arbitrary user-controlled messages.