Skip to content

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"
  }'
Always double-check you are using the correct environment when integrating. Using the wrong base URL or API key will result in authentication errors.

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.

Reconcile results on your backend

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 as 400, 500, or 700
  • fontSize - positive base font size in pixels; headings and related text scale from it
  • fontColor - hex color (e.g., #111111)
  • primaryColor - hex color for primary actions
  • backgroundColor - hex color for page background
  • buttonBorderRadius - button corner radius as a non-negative number
  • buttonShadowEnabled - whether buttons use a shadow
  • flowsOrder - preferred order of SATOSHI_TEST, VISUAL_PROOF, SELF_DECLARED, and SIGNATURE_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 language query parameter to the hosted URL (ISO 639-1):

    https://wallet-dev.cryptoswift.eu/?token=...&language=et
    
  • Setting the data-language attribute 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

AttributePurpose
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

FieldPurpose
allowedFlowsRestrict ownership methods. If omitted, CryptoSwift selects suitable flows.
satoshiFlowFor Satoshi Test, provide depositAddress and optionally amount; an omitted amount is generated automatically.
expiresInHoursSet the verification lifetime from 1 to 100 hours; the default is 48. Use the returned expiresAt as the deadline.
allowedLanguagesRestrict interface languages; otherwise all available languages remain selectable.
redirectUrlOptionally return hosted-page customers to your application.
originSet 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