Getting started

Android quickstart

Add the provided Android wrapper to your app module and open a wallet project slug to render the took WaaS wallet surface.

Prerequisites

• Android Studio and an app targeting Android API 26 or later
• Internet permission and access to the device browser
• A wallet project slug (tenantSlug) created in Studio
• An app callback registered for login return

Installation

1. Add the wrapper source

   Include waas/sdk/android/src/main/java/kr/traverse/took/waas/TookWaasWebView.java in your internal Android module.

2. Confirm internet permission

   Your AndroidManifest.xml must declare android.permission.INTERNET.

3. Create the wallet region

   Add TookWaasWebView to the Activity or Fragment content region reserved for the wallet.

4. Attach the listener

   Map wallet readiness and blocked navigation to your app's UI and link policies.

5. Open the wallet project

   Pass the project slug issued in Studio to open().

Minimum integration

walletView = new TookWaasWebView(this);
walletView.listener = new TookWaasWebView.Listener() {
  @Override
  public void onEvent(JSONObject event) {
    String type = event.optString("type");
    // Reflect safe wallet state in the host app UI.
  }

  @Override
  public void onBlockedNavigation(Uri url) {
    // Apply the host app's external-link policy.
  }
};

walletContainer.addView(walletView);
walletView.open("partner-wallet");

partner-wallet is an example. Replace it with the tenantSlug assigned to your institution's wallet project.

Run the sample first

Open waas/sdk/android/sample in Android Studio and run it on a physical device. The Wallet and Send controls are a test harness for open() and openScreen("send"). They are not required in the institution app or in its final wallet layout.

Native container

Embed the wallet surface

The institution app owns the surrounding screen while took WaaS uses only the assigned content region. Existing headers, tab bars, menus, and navigation patterns can remain unchanged.

Recommended layout

The host app may keep navigation outside the WebView. Use bridge commands when the host needs to open a specific screen within the wallet.

Connect app lifecycle

@Override
protected void onResume() {
  super.onResume();
  walletView.onHostResume();
}

@Override
protected void onPause() {
  walletView.onHostPause();
  super.onPause();
}

@Override
protected void onDestroy() {
  walletView.destroy();
  super.onDestroy();
}

This pauses WebView timers while the app is backgrounded and releases both the bridge and WebView resources when the Activity is destroyed.

Open a wallet screen

walletView.openScreen("send");
walletView.closeWalletSurface();

Features disabled in the wallet project remain hidden. The Android wrapper rejects screen values outside its explicit allowlist.

External URL handling

The WebView renders only wallet URLs on https://tookwallet.com. Other URLs leave the WebView, are reported through onBlockedNavigation(), and follow the device's external navigation policy.

Authentication

Login and app return

Wallet login starts inside took WaaS, while Google account selection runs in the device browser. When authentication completes, the app callback returns the result to the original wallet surface.

Login flow

This lets customers use Google accounts already available in the browser instead of containing the OAuth provider inside the WebView.

Register the callback

The sample app uses took-waas-poc://auth. Configure the Activity as singleTop and register the following intent filter.

<activity
  android:name=".MainActivity"
  android:exported="true"
  android:launchMode="singleTop">
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
      android:scheme="took-waas-poc"
      android:host="auth" />
  </intent-filter>
</activity>

Handle the return

@Override
protected void onNewIntent(Intent intent) {
  super.onNewIntent(intent);
  setIntent(intent);

  Uri callback = intent.getData();
  if (callback != null) {
    walletView.resumeOAuthRedirect(callback);
  }
}

resumeOAuthRedirect() restores the callback only when the registered scheme and host match and a wallet project is open. After the wallet session and address are ready, the bridge emits took-waas:wallet-ready.

WebView bridge

Events and commands

The bridge is a minimal state and navigation channel between the institution app and wallet surface. It is not an API for wallet control or signing authority.

Wallet → institution app

Institution app → wallet

{ "type": "took-waas:open", "screen": "send" }
{ "type": "took-waas:close" }

Event handling example

@Override
public void onEvent(JSONObject event) {
  switch (event.optString("type")) {
    case "took-waas:wallet-ready":
      showWalletReady(event.optString("address"));
      break;
    case "took-waas:screen-changed":
      updateHostNavigation(event.optString("screen"));
      break;
    case "took-waas:error":
      showWalletError(event.optString("code"));
      break;
  }
}

Wallet project configuration

Wallet Configuration API

Institutions can manage the same branding, feature, and KYT settings available in Studio through a server-side API. Studio and the API operate on the same wallet project.

Wallet project defaults

Studio creates a separate wallet project for each institution and stores its initial branding and feature settings. A “default” is not inherited from the original took app; it is the initial configuration stored on that wallet project. Fields omitted from a PATCH request retain their existing values.

API authentication

A wallet project administrator issues API keys from Studio. The raw key is displayed only once; the server retains only its hash, prefix, scopes, expiry, and revocation status.

GET /functions/v1/waas-config
x-took-waas-key: took_poc_<prefix>_<secret>

• Keys can use separate config:read and config:write scopes.
• Store keys in the institution backend or CI secret manager.
• Revoke exposed or unused keys in Studio and issue replacements.

Update configuration

PATCH /functions/v1/waas-config
content-type: application/json
x-took-waas-key: took_poc_<prefix>_<secret>

{
  "walletName": "My Wallet",
  "primaryColor": "#1769FF",
  "features": ["swap", "gasless", "kytPolicy"],
  "compliancePolicy": {
    "kyt": {
      "enabled": true,
      "blockRaCode2": ["EXAMPLE_CODE"]
    }
  }
}

After the update, the new configuration is applied to wallets opened with the same project slug. The Wallet Configuration API does not create wallets or sign transactions.

Risk policy

KYT · RA-2 policy

Each institution can enable risky-address blocking and choose its own RA-2 categories. took does not impose a mandatory category set.

How address checks work

1. The institution selects policy

   Enable kytPolicy and store selected categories in blockRaCode2 through Studio or the Config API.

2. The customer enters a destination

   took checks addresses in flows such as send and swap where a counterparty address is required.

3. Risk data is queried

   The current environment compares the address against took's server-side, Transight-derived deny_list.

4. Institution policy is applied

   If the address ra_code2 belongs to a selected category, the transaction is stopped before completion and the classification is shown.

Retrieve the RA-2 catalog

The full category catalog and its Korean and English descriptions are not hard-coded into the public page. Retrieve them from an authenticated Studio session or Config API request.

GET /functions/v1/waas-config?action=ra-code2-catalog
x-took-waas-key: took_poc_<prefix>_<secret>

The API rejects unknown RA-2 values. EXAMPLE_CODE in public examples is a placeholder and must be replaced by a value returned from the authenticated catalog.

Policy validation

• Confirm that classifications do not block transactions when KYT is disabled.
• Confirm that categories not selected by the institution are not blocked.
• Confirm that a controlled address in a selected category is blocked before completion.
• Confirm that the blocked state includes a customer-readable classification, not only a technical code.

Integration validation

Integration testing

Validate the complete customer journey—from login return through feature configuration and app lifecycle—instead of checking only that the first wallet screen renders.

Test setup

• A published wallet project with institution branding
• A wallet project feature set containing the capabilities under test
• The Android application ID and registered callback intent filter
• A test login and test assets
• Controlled blocked and non-blocked addresses with RA-2 categories
• A server-only API key when validating the Config API

Required acceptance criteria

• The wallet fits the assigned host app content region without clipping.
• took-waas:ready and auth-required arrive without duplicate error states.
• Google login completes in the system browser and returns to the original app and wallet surface.
• The public address in wallet-ready matches the active wallet after login.
• Host commands open allowlisted screens such as send and receive.
• Features disabled in the wallet project remain hidden and enabled features open normally.
• Selected RA-2 policy produces the expected result for controlled test addresses.

Edge cases to include

Security boundary

Security boundary

The institution app renders the wallet and receives limited state, but it does not own wallet keys or recovery and signing authority. Integration code must preserve that boundary.

Responsibilities by actor

Required implementation controls

• Restrict internal WebView navigation to https://tookwallet.com.
• Disable file access, content access, and mixed content.
• Parse only known bridge events beginning with took-waas:.
• Validate every requested screen against the wrapper allowlist.
• Revalidate callback scheme and host in native code.
• Never log OAuth codes, access tokens, wallet secrets, or Config API keys.

Prohibited WebView and bridge data

Production roadmap

Extend into a production integration

After validating the customer experience and technical touchpoints in the Integration Preview, the production architecture is defined around the institution's identity system, security policy, and regulatory scope.

Expected transition stages

1. Confirm the institution integration contract

   Define target apps, wallet projects, chains and features, data processing boundaries, SLA, and incident ownership.

2. Establish app and domain trust

   Register institution-owned Android App Links, callback allowlists, signing certificates, and environment-specific domains.

3. Connect customer identity

   If institution SSO is required, define issuer, audience, token exchange, expiry, and revocation rules and decide how they connect to took wallet login.

4. Finalize wallet and SAR security

   Map secure device storage, biometrics, recovery factors, SAR shares, and signer boundaries to the institution security review.

5. Connect compliance and operations

   Integrate live Transight scope, policy ownership, audit logs, monitoring, cost and relayer settlement, and customer-support procedures.

6. Expand platforms and approve release

   Add iOS integration when required, then pass penetration testing, disaster recovery, store distribution, and staged rollout gates before enabling production traffic.

Expected target architecture

The final design may vary by institution and security review. Results from the Preview become the input for the production specification, implementation scope, and delivery plan.