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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cyclonechain.com/develop/tutorials/cyclone-wallet-front-end-integration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.