Widget Integration
Embed the ready-to-use verification Widget or redirect to its hosted page
The Widget handles the customer-facing wallet verification journey. Embed it as a Web Component or redirect customers to the CryptoSwift-hosted page. Both options use the same backend create request and support your branding and verification settings.
Try the interactive wallet verification demo, or follow these steps to integrate it.
Integration Guide
1. Create a Verification Session
Create the verification on your backend. Keep the API key on the server.
curl --request POST 'https://api-dev.cryptoswift.eu/wallet-verification' \
--header "X-Api-Key: $API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"allowedFlows": ["SIGNATURE_PROOF"],
"origin": "https://app.example.com"
}'
{
"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": null,
"status": "PENDING",
"flow": null,
"allowedFlows": [
"SIGNATURE_PROOF"
],
"reuse": null,
"expiresAt": "2026-11-13T09: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
}
asset, blockchain, and address are required. Set origin to your application's origin when embedding the Web Component. Check supported blockchains and methods before choosing allowedFlows.
The response includes the verification id, a Widget token, and a hosted url. Save the ID with your customer or transaction. Pass the returned token to the Web Component, or use the returned URL for the hosted option.
2. Integrate the Widget
Option A: Web Component (embed in your app)
Load the module and add the element to your page. Replace <widget-token> with the token returned by your backend:
<script type="module" src="https://wallet-dev.cryptoswift.eu/widget/wallet-verifier.js"></script> <wallet-verifier id="wv" data-token="<widget-token>"></wallet-verifier>
Listen for completion and error events:
<script>
const verifier = document.getElementById('wv');
verifier.addEventListener('verification-complete', (event) => {
// The customer journey finished. Reconcile the ID on your backend.
console.log('Verification ID:', event.detail.id);
});
verifier.addEventListener('verification-error', (event) => {
// event.detail contains errorCode and message.
console.log('Verification error:', event.detail);
});
</script>
The completion event includes id, status, flow, address, asset, and blockchain. Use its ID to retrieve the authoritative result on your backend; the event can fire while evidence awaits review or a Satoshi Test is still pending.
The Widget lets customers retry most failures. For GENERAL_API_ERROR, reload the Widget or create a new verification session.
Option B: Hosted Standalone App (redirect)
Send the customer to the url returned by the create request. You can also share that URL so they can open it on another device.
To bring the customer back to your app, include redirectUrl when creating the verification. On return, the URL contains the verification ID as the id query parameter. Retrieve that ID's result on your backend. If you omit redirectUrl, the hosted page shows a completion screen instead.
Use the Get wallet verification endpoint (Sandbox) or verified webhook notifications for completion handling. Wallet ownership and any requested additional steps must each satisfy your policy before you proceed. Browser events and redirects can occur before manual review or transaction monitoring finishes.
3. Customize
You can configure the widget via API or through the Client Dashboard (settings screen). In the Client Dashboard, you have an instant widget preview that makes theming easy.
Theming
Update tenant settings via:
PATCH https://api-dev.cryptoswift.eu/tenant/me/settings
Theme parameters:
fontFamily- Google Fonts family name (see fonts.google.com)fontWeight- positive numeric font weight, such as400,500, or700fontSize- positive base font size in pixels; headings and related text scale from itfontColor- hex color (e.g.,#111111)primaryColor- hex color for primary actionsbackgroundColor- hex color for page backgroundbuttonBorderRadius- button corner radius as a non-negative numberbuttonShadowEnabled- whether buttons use a shadowflowsOrder- preferred order ofSATOSHI_TEST,VISUAL_PROOF,SELF_DECLARED, andSIGNATURE_PROOF
Set serviceName alongside walletVerificationTheme in the tenant settings request when the widget should display a customer-facing service name instead of the tenant name.
{
"serviceName": "Acme Wallet Verification",
"walletVerificationTheme": {
"fontFamily": "Inter",
"fontWeight": 500,
"fontSize": 16,
"fontColor": "#111111",
"primaryColor": "#315EFB",
"backgroundColor": "#FFFFFF",
"buttonBorderRadius": 8,
"buttonShadowEnabled": true,
"flowsOrder": ["SIGNATURE_PROOF", "SATOSHI_TEST", "VISUAL_PROOF", "SELF_DECLARED"]
}
}
See the Update tenant settings endpoint (Sandbox) for payload details.
Logo
Upload a branding logo displayed in the widget:
POST https://api-dev.cryptoswift.eu/tenant/me/settings/logo
Refer to the Upload tenant logo endpoint (Sandbox) for request format and constraints.
Icon
Upload a branding icon displayed in the widget (used within Signature proof flows):
POST https://api-dev.cryptoswift.eu/tenant/me/settings/icon
Refer to the Upload tenant icon endpoint (Sandbox) for request format and constraints.
Multilingual Support
For supported languages see the Create wallet verification endpoint (Sandbox).
Choose a pre-selected language by:
Adding the
languagequery parameter to the hosted URL (ISO 639-1):https://wallet-dev.cryptoswift.eu/?token=...&language=et
Setting the
data-languageattribute on the web component:<wallet-verifier data-token="..." data-language="et"></wallet-verifier>
Optional extensions
Additional steps
Request Source of Funds / Source of Wealth documents or Selfie / Liveness by adding additionalSteps to the create request. The Widget guides the customer through pending steps after the ownership interaction. Documents need manual review; Selfie can be approved automatically when backend liveness analysis passes and automatic confirmation is enabled.
Omit reuse when requesting additional steps. See Additional Steps for configuration and independent step statuses, or the additional steps workflow for the customer and reviewer walkthrough.
Reusable verification
For ownership-only requests, add reuse to check for eligible previous ownership evidence. A match returns VERIFIED without a Widget token or a new customer challenge. If no match is found, use the returned token or hosted URL to complete the normal flow.
See Reusable Wallet Verification for the owner-name hash, matching policy, and response examples.
Manual signature entry
If a wallet cannot connect or complete signing, users can select Sign manually in the signature proof flow. The widget shows the wallet address and the message to copy, accepts the resulting signature, and submits it through the existing signature verification API. Successful submission follows the same completion and additional-step flow as connected signing.
See Sign a wallet verification message manually for instructions and Bitcoin hardware-wallet guides.
Web Component options
| Attribute | Purpose |
|---|---|
data-full-size="true" | Remove the component's maximum width and let it fill its parent. |
data-language="en" | Preselect an interface language. |
data-is-demo="true" | Preview the layout without a token. Use the interactive demo for a complete simulated journey. |
Override the tenant theme for a single instance with data-font-family, data-font-color, data-primary-color, data-background-color, data-logo-url, or data-service-name.
When your backend returns a token after the element is mounted, set it dynamically:
const verifier = document.getElementById('wv');
verifier.setAttribute('data-token', tokenFromApi);
Verification request options
| Field | Purpose |
|---|---|
allowedFlows | Restrict ownership methods. If omitted, CryptoSwift selects suitable flows. |
satoshiFlow | For Satoshi Test, provide depositAddress and optionally amount; an omitted amount is generated automatically. |
expiresInHours | Set the verification lifetime from 1 to 100 hours; the default is 48. Use the returned expiresAt as the deadline. |
allowedLanguages | Restrict interface languages; otherwise all available languages remain selectable. |
redirectUrl | Optionally return hosted-page customers to your application. |
origin | Set the application's origin for an embedded Web Component. |
See the Create wallet verification endpoint (Sandbox) for the full schema and supported language codes.
Next steps
- Wallet Verification
- Custom API integration
- Additional Steps
- Reusable Wallet Verification
- Supported blockchains