Widget Integration

Our self-hosted wallet verification widget makes it easy to add secure wallet verification to your application. The widget is responsive, customizable (colors, fonts, logo), and supports multiple languages.

You can integrate the widget as a Web Component with just a few lines of code, or use it as a stand-alone, CryptoSwift-hosted application. In the hosted flow, you create a new wallet verification and CryptoSwift generates a unique verification URL. You can share this URL with your user or redirect them to it directly.

Once the verification is completed, the user is automatically redirected back to your application and your backend services are notified of the result.

• Web Component: Embed the widget directly into your frontend with a few lines of HTML/JS for a smooth, in-app experience.
• Hosted Flow: Redirect users to a secure, CryptoSwift-hosted URL. This requires zero frontend configuration and is managed entirely on our infrastructure.

1. Initiate: Create a verification session via API.
2. Verify: CryptoSwift generates a unique URL or renders the component for the user.
3. Complete: Once verified, the user is redirected to your site, and your backend receives a webhook notification.

Before launching the flow, create a session via API to obtain a widget token.

curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/widget' \
  --header 'x-api-key: $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "satoshiFlow": {
      "depositAddress": "025ecb213e8322af685473d2e4c8b23b5c104a9e57822027380a9bf6cd68dc2bfc"
    },
    "asset": "BTC",
    "blockchain": "Bitcoin",
    "address": "02f852bec98de40721fe0c5188c7255f7bc8592c1a1bcddb7d0c8edbf47f0f503c",
    "allowedLanguages": ["en", "et"],
    "redirectUrl": "https://your.crypto-app.domain/wallet-verification",
    "origin": "https://your.crypto-app.domain:80"
  }'

Required:

• asset - e.g., BTC, ETH
• blockchain - e.g., Bitcoin, Ethereum
• address - wallet address to verify

Optional:

• satoshiFlow - in case you want to use Satoshi Test; include depositAddress and optional amount (if omitted, we generate it)
• allowedFlows - restrict which verification flows may be used; if omitted, the widget auto-selects suitable flows
• allowedLanguages - array of allowed interface languages (enum: see supported languages). If omitted, all available languages remain selectable.
• redirectUrl - required for the Hosted Standalone App; not needed for the in-app Web Component
• origin - required for the Web Component; sets the allowed host and is validated client/server for security

Refer to the API documentation for full schema and examples.

Response:

{
  "token": "97857f6c-396a-4d68-a1bf-563bfb76c5b6",
  "walletVerificationId": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
  "url": "https://wallet.cryptoswift.eu/?token=97857f6c-396a-4d68-a1bf-563bfb76c5b6"
}

Use the token to initialize the widget (either as a query param for the hosted app or as a data-token attribute for the web component).

Use the walletVerificationId as a reference to the wallet verification record. You can always re-check the verification status by ID using the API.

1. Load the component

<script type="module" src="https://wallet.cryptoswift.eu/widget/wallet-verifier.js"></script>

2. Add the element

<wallet-verifier
  id="wv"
  data-token="97857f6c-396a-4d68-a1bf-563bfb76c5b6">
</wallet-verifier>

When initializing <wallet-verifier>, you can add general attributes:

• data-is-demo="true" - loads the widget in demo mode so no data-token is required. Use this during initial development and layout work.
• data-full-size="true" - removes the component max width and makes it stretch to its parent full width, and full height (or more if content overflows).
• data-language="en" - preselects the widget language. See the up-to-date list of supported codes in the createWidget API docs. If you need a language that is missing, let the CryptoSwift team know - we are happy to add more.

By default the widget uses the theme stored via the Tenant Settings API, but you can override specific values per instance via data attributes:

• data-font-family="Inter" - overrides the tenant theme font just for this instance (defaults to the API-stored theme).
• data-font-color="#111111" - overrides the main text color.
• data-primary-color="#0047FF" - overrides the primary action color.
• data-background-color="#F4F6FB" - overrides the widget background.
• data-logo-url="https://example.com/logo.png" - uses a custom logo URL without updating tenant settings.
• data-service-name="My Company Title" - overrides the organisation name.

Dynamic token update (optional):

const verifier = document.getElementById('wv');
verifier.setAttribute('data-token', tokenFromApi);

3. Handle completion

<script>
  document.getElementById('wv')
    .addEventListener('verification-complete', (event) => {
      // event.detail contains:
      // id, status ("PENDING" | "VERIFIED" | "FAILED" | "DELETED"),
      // flow, address, asset, blockchain
      console.log('Verification result:', event.detail);
    });
</script>

4. Handle errors

The widget handles most errors gracefully by default, enabling users to retry steps or restart the verification flow. If needed, integrators can also handle errors directly at the integration layer (for example, to apply custom logic or fallback behavior). For GENERAL_API_ERROR events, we recommend reloading the widget or starting a new verification session for the user.

In case of failures, the widget emits error events that can be subscribed to:

<script>
  document.getElementById('wv')
    .addEventListener('verification-error', (event) => {
      // event.detail contains: errorCode & message
      console.log('Verification error:', event.detail);
    });
</script>

Redirect users to:

https://wallet.cryptoswift.eu/?token={{TOKEN}}

After the flow completes, the user is redirected to your redirectUrl. The verification ID is appended as a query parameter, which you can then verify server-side using the API. If a redirectUrl is not defined when initiating the verification, a success message is displayed to the user and they can close the window. Your backend still gets notified about the successfull verification via a webhook notification.

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.

Update tenant settings via:

PATCH https://api-dev.cryptoswift.eu/tenant/me/settings

Theme parameters:

• fontFamily - Google Fonts family name (see fonts.google.com)
• fontColor - hex color (e.g., #111111)
• primaryColor - hex color for primary actions
• backgroundColor - hex color for page background

See the Tenant API docs for payload details.

Upload a branding logo displayed in the widget:

POST https://api-dev.cryptoswift.eu/tenant/me/settings/logo

Refer to the Tenant Logo API docs for request format and constraints.

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 Tenant Icon API docs for request format and constraints.

For supported languages see the createWidget API docs.

Choose a pre-selected language by:

• Adding the language query parameter to the hosted URL (ISO 639-1):

  https://wallet.cryptoswift.eu/?token=...&language=et
  

  content_copy

• Setting the data-language attribute on the web component:

  <wallet-verifier data-token="..." data-language="et"></wallet-verifier>
  

  content_copy