Skip to content

EVM Signature Proof

Sign and submit wallet ownership challenges with viem, ethers, or a browser provider

Use this guide when building a custom Signature Proof flow for Ethereum or another supported EVM blockchain. First create a wallet verification, then sign a challenge with the address being verified and submit the proof from your backend.

EVM Signature Scheme

For Ethereum and other supported EVM wallets, CryptoSwift expects an EIP-191 plain-message signature. Generate it with a compatible wallet interface, such as:

  • personal_sign
  • viem walletClient.signMessage
  • ethers signer.signMessage

CryptoSwift recovers the signer address from the submitted message and signature. The recovered address must match the wallet address associated with the wallet-verification request.

EIP-712 typed data is not supported

The SIGNATURE_PROOF flow does not accept arbitrary EIP-712 typed-data signatures. Do not submit signatures created with signTypedData. This includes EIP-3009 receiveWithAuthorization signatures: they authorize a token transfer, but cannot be used as CryptoSwift wallet-ownership proof.

The message content can be customer-defined, but the signature scheme cannot. An EVM signature must still be an EIP-191 plain-message signature.

Message Requirements

For direct API submission, CryptoSwift does not prescribe a message-content format. The minimum accepted content is a non-empty string, provided that the signature was generated over exactly that string.

For replay resistance and auditability, strongly prefer a unique challenge that contains:

  • The purpose of the signature
  • The wallet-verification ID
  • A cryptographically random nonce
  • An issued-at timestamp
  • Optionally, an expiry timestamp and the requesting service or domain

Recommended format:

CryptoSwift wallet ownership verification | verificationId: <verification-id> | nonce: <cryptographically-random-nonce> | issuedAt: <ISO-8601-timestamp>

The nonce makes each challenge unique, while the verification ID binds it to a specific CryptoSwift verification. Together, they reduce the risk that a valid signature can be replayed for another request. If your service adds an expiry timestamp, enforce it before submitting the proof.

Follow these rules:

  • Submit the exact original message that was signed.
  • Preserve capitalization, spaces, line breaks, punctuation, and every other character.
  • Submit the original plain-text message, not its hash.
  • Do not manually add the Ethereum signed-message prefix when using signMessage or personal_sign; the wallet adds the EIP-191 prefix.

Direct API Versus Widget Flow

IntegrationMessage-content validationCryptographic validation
Direct API submissionYou generate any non-empty message. No CryptoSwift-specific content format is enforced.CryptoSwift validates the chain-specific signature and checks that the recovered address matches the wallet-verification request.
CryptoSwift-hosted widgetAdditional validation applies, including the expected domain, CAIP-2 chain ID, and an issued-at timestamp within the accepted time window.CryptoSwift validates the chain-specific signature and wallet address.

Sign the Challenge with viem

This viem v2 browser example uses the wallet's injected EIP-1193 provider. Replace <verification-id> with the ID returned when you created the verification.

import { createWalletClient, custom } from 'viem';

const walletClient = createWalletClient({
  transport: custom(window.ethereum)
});

const [account] = await walletClient.requestAddresses();
const verificationId = '<verification-id>';
const nonce = crypto.randomUUID();
const issuedAt = new Date().toISOString();
const message =
  `CryptoSwift wallet ownership verification | ` +
  `verificationId: ${verificationId} | ` +
  `nonce: ${nonce} | issuedAt: ${issuedAt}`;

const signature = await walletClient.signMessage({
  account,
  message
});

// Send the original `message` and `signature` to your backend.
console.log({ account, message, signature });

Sign the Challenge with ethers

This example uses the ethers v6 BrowserProvider and its signer.signMessage method.

import { BrowserProvider } from 'ethers';

const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const account = await signer.getAddress();
const verificationId = '<verification-id>';
const nonce = crypto.randomUUID();
const issuedAt = new Date().toISOString();
const message =
  `CryptoSwift wallet ownership verification | ` +
  `verificationId: ${verificationId} | ` +
  `nonce: ${nonce} | issuedAt: ${issuedAt}`;

const signature = await signer.signMessage(message);

// Send the original `message` and `signature` to your backend.
console.log({ account, message, signature });

Sign the Challenge with a Browser Provider

When calling personal_sign directly, encode the message as UTF-8 hexadecimal for the provider. Keep the original plain-text message for submission to CryptoSwift.

function utf8ToHex(value) {
  const bytes = new TextEncoder().encode(value);
  return `0x${Array.from(bytes, (byte) =>
    byte.toString(16).padStart(2, '0')
  ).join('')}`;
}

const [account] = await window.ethereum.request({
  method: 'eth_requestAccounts'
});
const verificationId = '<verification-id>';
const nonce = crypto.randomUUID();
const issuedAt = new Date().toISOString();
const message =
  `CryptoSwift wallet ownership verification | ` +
  `verificationId: ${verificationId} | ` +
  `nonce: ${nonce} | issuedAt: ${issuedAt}`;

const signature = await window.ethereum.request({
  method: 'personal_sign',
  params: [utf8ToHex(message), account]
});

// Submit `message`, not utf8ToHex(message), to CryptoSwift.
console.log({ account, message, signature });

Submit the Signature as JSON with curl

Send the proof from your backend as application/json. Use the exact message and signature returned by the signing step.

API_KEY='<api-key>'
VERIFICATION_ID='<verification-id>'

curl --location --request POST \
  'https://api-dev.cryptoswift.eu/wallet-verification/'"$VERIFICATION_ID"'/verification' \
  --header "X-Api-Key: $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "verificationFlow": "SIGNATURE_PROOF",
    "message": "CryptoSwift wallet ownership verification | verificationId: <verification-id> | nonce: <cryptographically-random-nonce> | issuedAt: <ISO-8601-timestamp>",
    "signature": "<0x-prefixed-signature>"
  }'
Always double-check you are using the correct environment when integrating. Using the wrong base URL or API key will result in authentication errors.

Submit the Signature as JSON with JavaScript

The following example uses the built-in fetch API available in current Node.js runtimes. Run it on your server, where the API key remains private.

const apiBaseUrl = '<api-base-url>';
const apiKey = '<api-key>';
const verificationId = '<verification-id>';
const message =
  'CryptoSwift wallet ownership verification | ' +
  'verificationId: <verification-id> | ' +
  'nonce: <cryptographically-random-nonce> | ' +
  'issuedAt: <ISO-8601-timestamp>';
const signature = '<0x-prefixed-signature>';

const response = await fetch(
  `${apiBaseUrl}/wallet-verification/${verificationId}/verification`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      verificationFlow: 'SIGNATURE_PROOF',
      message,
      signature
    })
  }
);

if (!response.ok) {
  throw new Error(
    `Signature proof failed (${response.status}): ${await response.text()}`
  );
}

const verification = await response.json();
console.log(verification);

Troubleshooting

ProblemWhat to check
Empty message or signatureBoth message and signature are required. The message must contain at least one character.
Invalid or non-hex EVM signatureSubmit the complete signature returned by the wallet, including its 0x prefix. Use an EIP-191 message-signing method supported by the wallet.
Address mismatchConfirm that the account used to sign is the same address stored on the wallet-verification request. CryptoSwift rejects a proof when the recovered signer differs.
Message changed after signingSubmit the exact original string. Check capitalization, whitespace, line breaks, punctuation, and text encoding.
EIP-712 typed-data signatureSign again with personal_sign, viem signMessage, or ethers signMessage. signTypedData and EIP-3009 authorization signatures are not valid ownership proofs.
Incorrect request formatPrefer JSON for SIGNATURE_PROOF, SELF_DECLARED, or SATOSHI_TEST; multipart is also accepted for those flows. Use multipart for VISUAL_PROOF, because JSON cannot carry the uploaded proof files.
Verification already completed or expiredRetrieve the verification by ID and check its current status. If it has expired, create a new verification and challenge instead of reusing the old proof.

Next steps