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.
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
signMessageorpersonal_sign; the wallet adds the EIP-191 prefix.
Direct API Versus Widget Flow
| Integration | Message-content validation | Cryptographic validation |
|---|---|---|
| Direct API submission | You 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 widget | Additional 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>"
}'
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"token": "<widget-token>",
"url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"metadata": "customer-123",
"status": "VERIFIED",
"flow": "SIGNATURE_PROOF",
"allowedFlows": [
"SIGNATURE_PROOF",
"VISUAL_PROOF",
"SELF_DECLARED"
],
"reuse": null,
"expiresAt": "2026-11-12T09:00:00.000Z",
"createdAt": "2026-11-11T09:00:00.000Z",
"satoshiFlow": {
"amount": null,
"depositAddress": null
},
"statusReasoning": null,
"riskScore": null,
"warnings": [],
"origin": "https://app.example.com",
"redirectUrl": null,
"signature": "<0x-prefixed-signature>",
"message": "CryptoSwift wallet ownership verification | verificationId: <verification-id> | nonce: <cryptographically-random-nonce> | issuedAt: <ISO-8601-timestamp>"
}
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
| Problem | What to check |
|---|---|
| Empty message or signature | Both message and signature are required. The message must contain at least one character. |
| Invalid or non-hex EVM signature | Submit the complete signature returned by the wallet, including its 0x prefix. Use an EIP-191 message-signing method supported by the wallet. |
| Address mismatch | Confirm 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 signing | Submit the exact original string. Check capitalization, whitespace, line breaks, punctuation, and text encoding. |
| EIP-712 typed-data signature | Sign again with personal_sign, viem signMessage, or ethers signMessage. signTypedData and EIP-3009 authorization signatures are not valid ownership proofs. |
| Incorrect request format | Prefer 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 expired | Retrieve 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. |