Skip to content

Widget Integration

Self-Hosted Wallet Verification Widget

Implementing multi-flow, self-hosted wallet verification can be complex. CryptoSwift provides an all-in-one solution that’s easy to integrate. Choose either:

  • Embed the Web Component directly in your app, or
  • Use the Hosted Standalone App: redirect users to CryptoSwift for verification, and we’ll redirect them back to your app with the result.

The widget is responsive, customisable (colors, fonts, logo) and has multilanguage support.

CryptoSwift Self-Hosted Wallet Verification Widget

To start a self-hosted verification via the widget, follow these steps.

1) Create a Verification Session

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

curl --location 'https://api.cryptoswift.eu/wallet-verification/widget' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "satoshiFlow": {
      "depositAddress": "025ecb213e8322af685473d2e4c8b23b5c104a9e57822027380a9bf6cd68dc2bfc"
    },
    "asset": "BTC",
    "blockchain": "Bitcoin",
    "address": "02f852bec98de40721fe0c5188c7255f7bc8592c1a1bcddb7d0c8edbf47f0f503c",
    "redirectUrl": "https://your.crypto-app.domain/wallet-verification",
    "origin": "https://your.crypto-app.domain:80"
  }'
Warning
Always double-check you are using the correct environment when integrating. Using the wrong base URL or API key will result in authentication errors.

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
  • 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.

2) Integrate the Widget

Option A: Web Component (embed in your app)

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>

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>

For additional security, you can always re-check the verification status by ID using the API.

Option B: Hosted Standalone App (redirect)

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.

Customization

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.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.

Logo

Upload a branding logo displayed in the widget:

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

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

Multilingual Support

Supported languages:

  • Czech
  • English
  • Estonian
  • Hungarian
  • Polish
  • Russian
  • Ukrainian

Choose a language by:

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

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

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

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

Notes & Best Practices

  • Use production or sandbox hosts consistently across your app:
    • api.cryptoswift.eu and wallet.cryptoswift.eu for production;
    • api-dev.cryptoswift.eu and wallet-dev.cryptoswift.eu for sandbox.
  • When embedding, set origin to the exact host:port that serves your app to pass client/server origin checks.
  • Always validate verification results server-side using the returned verification ID.

Next Steps