> For the complete documentation index, see [llms.txt](https://eckowallet.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eckowallet.gitbook.io/docs/user-guides/walletconnect.md).

# Using WalletConnect

WalletConnect allows you to connect your eckoWALLET mobile app to desktop dApps, giving you the security of mobile wallet storage with the convenience of desktop browsing.

## What is WalletConnect?

WalletConnect is an open-source protocol that connects mobile wallets to desktop applications securely. With eckoWALLET's WalletConnect support, you can:

* 🔐 **Keep your keys on mobile** - Your private keys stay secure on your phone
* 💻 **Use desktop dApps** - Access the full dApp experience on your computer
* 🔄 **Easy switching** - Quickly approve transactions from your mobile device
* 🌐 **Universal compatibility** - Works with any WalletConnect-enabled dApp

## Prerequisites

Before you begin, ensure you have:

* ✅ eckoWALLET mobile app installed (iOS or Android)
* ✅ Your wallet created and funded on mobile
* ✅ A desktop browser accessing a WalletConnect-enabled dApp

## Connection Methods

eckoWALLET supports two ways to connect: **Connection Code** and **QR Code**. Both methods are equally secure.

***

## Method 1: Connection Code

This method is ideal when:

* You can't easily scan a QR code
* You want to copy-paste the connection
* You're on the same device (less common)

### Step 1: Initiate WalletConnect on Desktop

On your desktop dApp (e.g., eckoDEX):

1. Navigate to the wallet connection section
2. Click on **"WalletConnect"** option

![WalletConnect Button](https://github.com/RunOnFlux/ecko-wallet-docs/blob/main/user-guides/assets/images/tutorials/walletconnect1.png)

### Step 2: Select Connect

3. Click the **"Connect"** button

![Connect Button](https://github.com/RunOnFlux/ecko-wallet-docs/blob/main/user-guides/assets/images/tutorials/walletconnect2.png)

### Step 3: Copy Connection Code

4. Click **"Copy to clipboard"**
5. The connection code is now copied

![Copy Connection Code](https://github.com/RunOnFlux/ecko-wallet-docs/blob/main/user-guides/assets/images/tutorials/walletconnect3.png)

**What is the connection code?**

* It's a long string that contains encrypted connection information
* It's safe to copy - it only establishes a connection, not access to your funds
* It expires after a short time if not used

### Step 4: Open eckoWALLET Mobile

6. Open the **eckoWALLET app** on your iOS or Android device
7. Unlock your wallet if locked

### Step 5: Navigate to Connections

8. Tap on **"Connections"** or the connection icon in the app menu

**Where to find it:**

* Usually in the bottom navigation bar
* Or in the hamburger menu (☰)
* Look for a link/connection icon

### Step 6: Select WalletConnect

9. Tap the **WalletConnect icon** or **"New Connection"**

### Step 7: Paste Connection Code

10. Long-press in the **Connection Code field**
11. Select **"Paste"** to paste the code you copied
12. Alternatively, you can type it manually (not recommended - long and error-prone)

### Step 8: Connect

13. Tap **"Connect"** or **"Approve"**

### Step 9: Approve Connection

14. Review the connection request:
    * **dApp name** - The app you're connecting to
    * **dApp URL** - Verify it's the correct website
    * **Permissions requested** - What the dApp can see/do
15. Tap **"Approve"** to confirm

**Security Check:**

* ✅ Verify the dApp name matches what you expect
* ✅ Check the URL is correct (watch for phishing sites)
* ✅ Understand what permissions you're granting

### Step 10: Connected!

16. You should see a success message on both:
    * Your mobile app (connection established)
    * The desktop dApp (wallet connected)
17. Your mobile app will now show:
    * Connected dApp name
    * Connection status (Active)
    * Option to disconnect

***

## Method 2: QR Code (Recommended)

This is the fastest and most common method. Ideal when:

* You have your phone nearby
* You're on different devices (typical scenario)
* You want a quick connection

### Step 1: Initiate WalletConnect on Desktop

On your desktop dApp:

1. Navigate to wallet connection
2. Click **"WalletConnect"**

![WalletConnect Button](https://github.com/RunOnFlux/ecko-wallet-docs/blob/main/user-guides/assets/images/tutorials/walletconnect1.png)

### Step 2: Select Connect

3. Click **"Connect"**

![Connect Button](https://github.com/RunOnFlux/ecko-wallet-docs/blob/main/user-guides/assets/images/tutorials/walletconnect2.png)

### Step 3: View QR Code

4. A QR code will appear on screen
5. **Keep this tab open** - don't close it

![WalletConnect QR Code](https://github.com/RunOnFlux/ecko-wallet-docs/blob/main/user-guides/assets/images/tutorials/walletconnect4-qr.png)

**About the QR code:**

* Contains encrypted connection info
* Changes for each session
* Expires after a few minutes
* Safe to scan - just establishes connection

### Step 4: Open eckoWALLET Mobile

6. Open the **eckoWALLET app** on your mobile device
7. Unlock if needed

### Step 5: Go to Connections

8. Navigate to **"Connections"** section

### Step 6: Scan QR Code

9. Tap the **QR scanner icon**
10. Point your camera at the QR code on your desktop screen
11. The app will automatically detect and scan

**Scanning tips:**

* Ensure good lighting
* Hold phone steady
* Get the entire QR code in frame
* Not too close, not too far

### Step 7: Approve Connection

12. Review the connection details:
    * dApp name
    * dApp URL
    * Requested permissions
    * Network (Mainnet, Testnet)
13. Tap **"Approve"** to confirm

### Step 8: Connected!

14. Success! Both devices will show connection confirmation
15. You can now interact with the dApp from desktop while approving transactions on mobile

***

## Using Your Connected Wallet

Once connected via WalletConnect:

### Making Transactions

1. **On Desktop**: Initiate transaction in dApp (swap, transfer, etc.)
2. **On Mobile**: Your eckoWALLET will display a notification
3. **Review**: Check transaction details carefully
4. **Approve or Reject**: Tap your choice
5. **Confirm**: Transaction is sent to blockchain

### What You'll See on Mobile

Transaction approval requests show:

* **Transaction type** (Transfer, Contract Call, etc.)
* **Amount** (if applicable)
* **Gas fee**
* **Recipient** address
* **Network and chain**
* **Pact code** (for advanced users)

**Always review:**

* ✅ The amount is correct
* ✅ The recipient is expected
* ✅ Gas fee is reasonable
* ✅ You initiated this transaction

### Active Session

While connected:

* Session remains active even if you close the app
* Works across page refreshes on desktop
* Automatically reconnects if connection drops
* Shows as "Active" in your Connections list

***

## Managing Connections

### Viewing Active Connections

In eckoWALLET mobile:

1. Go to **"Connections"**
2. See list of all active WalletConnect sessions
3. Each shows:
   * dApp name
   * Connection time
   * Status (Active/Inactive)

### Disconnecting

To disconnect from a dApp:

**From Mobile:**

1. Go to **"Connections"**
2. Find the dApp
3. Tap on it
4. Select **"Disconnect"**
5. Confirm disconnection

**From Desktop:**

* Most dApps have a "Disconnect Wallet" button
* This will end the session on both sides

**Why disconnect?**

* Security best practice when done using dApp
* Prevents unauthorized future requests
* Cleans up your active connections list

### Session Expiry

WalletConnect sessions:

* Can last for days/weeks while active
* Automatically expire after period of inactivity
* Require re-connection after expiry
* More secure than permanent connections

***

## Troubleshooting

### QR Code Won't Scan

**Solutions:**

* Ensure camera permission is granted to eckoWALLET
* Try better lighting
* Clean your camera lens
* Refresh the QR code (reload dApp page)
* Try Connection Code method instead

### Connection Code Not Working

**Solutions:**

* Ensure you copied the complete code
* Check for extra spaces at beginning/end
* Code may have expired - generate a new one
* Make sure you're on the correct network

### Connection Drops

**Why it happens:**

* Network connectivity issues
* Session expired
* App was force-closed
* Desktop tab was closed

**Solutions:**

* Simply reconnect using QR/Code
* Check internet on both devices
* Ensure dApp supports WalletConnect v2

### Transaction Not Appearing on Mobile

**Solutions:**

* Check notifications are enabled for eckoWALLET
* Ensure app is running (may be in background)
* Verify connection is still active
* Try initiating transaction again on desktop

### Wrong Account Connected

**To switch accounts:**

1. Disconnect current session
2. Switch account in eckoWALLET mobile
3. Reconnect to dApp
4. New account will be used

### "Session Proposal Failed"

**Causes:**

* Network mismatch (Mainnet vs Testnet)
* Outdated app version
* dApp compatibility issue

**Solutions:**

* Update eckoWALLET to latest version
* Ensure correct network selected
* Try refreshing dApp page
* Contact dApp support if persistent

***

## Security Best Practices

### Before Connecting

✅ **Verify the dApp:**

* Is it the official website?
* Check the URL carefully (watch for phishing)
* Research the dApp if unfamiliar

✅ **Check your network:**

* Are you on the intended network (Mainnet/Testnet)?
* Is your account funded appropriately?

### During Connection

✅ **Review permissions:**

* What can the dApp see?
* What actions can it request?
* Are you comfortable with this?

✅ **Don't blindly approve:**

* Read what you're approving
* Understand the connection scope

### While Connected

✅ **Review every transaction:**

* Never auto-approve
* Check amounts and recipients
* Verify gas fees

✅ **Disconnect when done:**

* Don't leave connections active indefinitely
* Especially for high-value accounts

### General Security

❌ **Never:**

* Share your recovery phrase in WalletConnect flow
* Approve transactions you didn't initiate
* Connect to suspicious/unknown dApps
* Leave public WiFi connections active

✅ **Always:**

* Keep eckoWALLET updated
* Use strong device lock (PIN/biometric)
* Regularly review active connections
* Disconnect from unused dApps

***

## Advanced Features

### Multiple Sessions

eckoWALLET supports multiple active WalletConnect sessions:

* Connect to different dApps simultaneously
* Each session is independent
* Manage all from Connections page

### Cross-Network Connections

You can have sessions on different networks:

* Mainnet session for production dApps
* Testnet session for testing
* Switch networks to use appropriate session

### Transaction History

All WalletConnect transactions appear in:

* Your regular transaction history
* With "WalletConnect" indicator
* Full details preserved

***

## Supported dApps

eckoWALLET WalletConnect works with any WalletConnect v2 enabled Kadena dApp, including:

* **eckoDEX** - Decentralized exchange
* **Kaddex** - DEX and DeFi platform
* **NFT marketplaces** - Supporting Marmalade standard
* **DeFi protocols** - Lending, staking, etc.
* **Any WalletConnect v2 compatible dApp**

**Looking for compatible dApps?**

* Check the [Kadena Ecosystem](https://kadena.io/ecosystem)
* Look for the WalletConnect logo
* Join the [eckoWALLET Discord](https://discord.com/invite/runonflux) for recommendations

***

## Comparison: Connection Code vs QR Code

| Feature          | Connection Code         | QR Code               |
| ---------------- | ----------------------- | --------------------- |
| **Speed**        | Slower (copy/paste)     | Faster (instant scan) |
| **Convenience**  | Requires switching apps | Point and scan        |
| **Use Case**     | Can't scan QR           | Normal use            |
| **Security**     | Equally secure          | Equally secure        |
| **Success Rate** | May have typos          | Camera dependent      |

**Recommendation:** Use QR code for normal connections, Connection Code as backup.

***

## Frequently Asked Questions

### Do I need WalletConnect for all dApps?

No. WalletConnect is specifically for:

* Using **mobile** wallet with **desktop** dApps
* If using browser extension, dApps connect directly
* Mobile-only dApps don't need WalletConnect

### Can I use WalletConnect with the browser extension?

No. WalletConnect is for connecting mobile to desktop. The browser extension connects directly to dApps.

### Is my recovery phrase exposed through WalletConnect?

No! WalletConnect:

* Never transmits your private keys
* Never shares your recovery phrase
* Only sends signed transactions
* End-to-end encrypted connection

### Can dApps drain my wallet through WalletConnect?

No. Every transaction requires your explicit approval on mobile. dApps cannot:

* Execute transactions without your approval
* Access your private keys
* Sign transactions automatically

### Why do I need to approve each transaction?

Security. This ensures:

* You're aware of every transaction
* No unauthorized activity
* You can review details before signing
* Protection against malicious dApps

### Can I use one connection for multiple dApps?

No. Each dApp requires its own WalletConnect session. This improves:

* Security (isolated sessions)
* Management (clear connection list)
* Privacy (dApps can't see each other's activity)

### What happens if I lose my phone?

If your phone with eckoWALLET is lost:

1. Your funds are safe (secured by recovery phrase)
2. Restore wallet on new device using recovery phrase
3. Previous WalletConnect sessions will be disconnected
4. Reconnect to dApps as needed

***

## Related Documentation

* [Security Best Practices](/docs/user-guides/security-best-practices.md) - Keep your wallet secure
* [Managing Accounts](/docs/user-guides/managing-accounts.md) - Switch between accounts
* [Connected dApps](https://github.com/RunOnFlux/ecko-wallet-docs/blob/main/user-guides/connected-dapps.md) - Manage dApp connections
* [Mobile Features](https://github.com/RunOnFlux/ecko-wallet-docs/blob/main/mobile/features.md) - eckoWALLET mobile capabilities

## Need Help?

* **Discord**: <https://discord.com/invite/runonflux>
* **Twitter**: [@eckoWALLET](https://twitter.com/eckoWALLET)
* **Troubleshooting**: [Full Guide](/docs/reference/troubleshooting.md)
* **FAQ**: [General FAQ](/docs/reference/faq.md)

***

**Happy connecting! Use WalletConnect to enjoy the best of both worlds: mobile security with desktop convenience.** 🔐📱💻


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://eckowallet.gitbook.io/docs/user-guides/walletconnect.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.