> For the complete documentation index, see [llms.txt](https://docs.cyclonechain.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cyclonechain.com/develop/tutorials/cyclone-wallet-front-end-integration-guide.md).

# Cyclone Wallet – Front-End Integration Guide

This document explains how to detect the Cyclone Wallet Chrome extension, call its API from your web page, and present results to users.\
➡ **Install the extension:** [Cyclone Wallet in Chrome Web Store](https://chromewebstore.google.com/detail/cyclone-wallet/caplndhphkmgognmgdeeelefmccbgemk)

***

### **1. Detecting the Extension**

The extension injects a global object `window.cycloneWallet`. Wait for it asynchronously to avoid blocking initial rendering:

```javascript
function waitForCycloneWallet(cb) {
  if (window.cycloneWallet) {
    cb();
  } else {
    setTimeout(() => waitForCycloneWallet(cb), 100);
  }
}

waitForCycloneWallet(() => {
  console.log('Cyclone Wallet API detected');
  // Your app initialization here
});
```

***

### **2. High-level API**

All methods reject on user denial or locked wallet, so wrap calls in `try/catch`.

| Method               | Purpose                            | Returns (Promise) |
| -------------------- | ---------------------------------- | ----------------- |
| `getWalletAddress()` | Get the active address             | string            |
| `getNativeBalance()` | Get native currency balance        | string or bigint  |
| `sign(data)`         | Sign arbitrary data/transaction    | string or object  |
| `send(data)`         | Broadcast a pre-signed transaction | string (tx hash)  |
| `signAndSend(data)`  | Sign and broadcast immediately     | string (tx hash)  |

***

### **3. Payload Templates**

#### **3.1 `sign`**

```json
{
  "token": "native",
  "to": "1Ldm39C6S7qKSuZxGLebR41HVc1uvu6YfF",
  "amount": 2,
  "message": "",
  "feeCurrency": "native"
}
```

***

#### **3.2 `send`**

```json
{
  "vm": "",
  "hash": "f8d8…fa75",
  "signature": "HKQT…mlgA=",
  "message": "{\"method\":\"execute\",\"data\":\"transfer(…)\"}",
  "currencyFee": "",
  "sender": "13WyHMuHxts2Pxcm2nECQ1BnSUEmD9SkZH",
  "nonce": "1722251674574"
}
```

***

#### **3.3 `signAndSend`**

```json
{
  "token": "native",
  "to": "1Ldm39C6S7qKSuZxGLebR41HVc1uvu6YfF",
  "amount": 1,
  "signMessage": "",
  "feeCurrency": "native"
}
```

***

### **4. Quick Integration Example**

#### `index.html`

```html
<!-- index.html -->
<button id="getAddress">Get Wallet Address</button>
<pre id="output"></pre>
<script src="./script.js"></script>
```

#### `script.js`

```javascript
// script.js
waitForCycloneWallet(() => {
  document.getElementById('getAddress').addEventListener('click', async () => {
    try {
      const addr = await window.cycloneWallet.getWalletAddress();
      document.getElementById('output').textContent = addr;
    } catch (err) {
      document.getElementById('output').textContent = err.message;
    }
  });
});
```

***

### **5. UX Guidelines**

* Disable action buttons until `window.cycloneWallet` is present.
* Show a spinner while the user confirms an action in the extension.
* Render results in a monospace `<pre class="output">` block.

***

### **6. Security Best Practices**

* Never store private keys, signatures, or sensitive data in `localStorage`.
* Validate all user input (amount ranges, address syntax) before sending to the wallet.
* Remove console logs with sensitive data in production builds.

***

### **7. Pre-Release Checklist**

* \[✔] Fallback banner with Chrome Web Store link if the extension isn’t installed.
* \[✔] `try/catch` around every API call.
* \[✔] Localized error messages.
* \[✔] Content-Security-Policy that allows `chrome-extension://<ID>` if needed.
* \[✔] Unit tests for JSON parsing and UI rendering.

***

### **8. Handy Utility Functions**

```javascript
// Toast helper
const hasWallet = Boolean(window.cycloneWallet);
showToast(hasWallet
  ? 'Cyclone Wallet detected 🎉'
  : 'Install Cyclone Wallet from Chrome Web Store');

// Transfer native tokens
export async function transferNative(to, amount) {
  const tx = {
    token: 'native',
    to,
    amount,
    message: '',
    feeCurrency: 'native'
  };
  return await window.cycloneWallet.signAndSend(tx);
}
```

***

### **Need Help?**

Reach out to the [**Cyclone** team](https://discord.gg/vCzbn3AXKv) or check the extension’s Help tab for more examples and troubleshooting tips.