🖤 Implement Headless Mode Support for SDK

[mijinummi]

🧭 Overview

BridgeWise provides embeddable UI components (<BridgeCompare />, <BridgeStatus />), but developers building custom UIs need headless mode support:

• Access all core SDK functionality without prebuilt UI
• Build custom interfaces while using hooks, APIs, and logic modules
• Maintain integration with fees, slippage, ranking, network switching, and analytics

Headless mode ensures maximum flexibility for dApp developers.

---

🎯 Problem

• Prebuilt UI components may not fit every dApp design
• Developers currently cannot fully leverage BridgeWise logic without using components
• Lack of headless mode reduces SDK adoption for custom integrations
• Features like fee estimation, ranking, and transaction tracking need decoupled access

Without headless mode, BridgeWise risks limiting developer flexibility and integration options.

---

💡 Proposed Solution

Implement Headless Mode Support that:

• Exposes all core hooks and functions independent of UI
• Supports:
  • useBridgeQuotes()
  • useFeeEstimate()
  • useSlippageAlert()
  • useBridgeExecution()
  • useNetworkSwitcher()
  • useTransactionHistory()
• Provides TypeScript types and API for full logic integration
• Compatible with SSR and React environments

---

🛠 Scope of Work

1️⃣ Core Hooks & Functions Exposure

• Refactor SDK to ensure all business logic is decoupled from UI
• Ensure hooks return full data, loading, error states, and event callbacks
• Maintain backward compatibility with existing components

---

2️⃣ Headless Mode Configuration

interface HeadlessConfig {
  autoRefreshQuotes?: boolean;
  slippageThreshold?: number;
  network?: string;
  account?: string;
}

• Allows developers to configure headless behavior
• Supports optional automatic updates for quotes, fees, and slippage

---

3️⃣ Integration with Existing Modules

• Fee estimation, slippage alerts, transaction history, network switching, and ranking work seamlessly in headless mode
• Developers can subscribe to events without rendering UI

---

4️⃣ SSR & Headless Compatibility

• Hooks must be SSR-safe
• Avoid reliance on DOM elements
• Works in Next.js or other server-rendered frameworks

---

5️⃣ Error Handling & Fallbacks

• Graceful error handling for missing or incomplete data
• Provide clear error messages for unsupported headless operations
• Ensure hooks do not throw unhandled exceptions

---

📊 Expected Outcome

• Developers can use BridgeWise logic without prebuilt components
• Fully customizable UI for any dApp design
• All core features (quotes, fees, slippage, ranking, network switching, transaction tracking) remain functional
• SSR-safe and production-ready SDK

---

✅ Acceptance Criteria

• All core hooks and functions usable in headless mode
• HeadlessConfig implemented and respected
• Integration with quotes, fee estimation, slippage, ranking, network switching, and transaction history
• SSR-safe for Next.js
• Unit tests for all headless operations
• Documentation updated with examples for headless integration
• Backward compatibility with prebuilt UI maintained

---

📈 Measurable Impact

• Maximizes SDK adoption by developers with custom UI needs
• Enables professional dApps to integrate BridgeWise logic without constraints
• Reduces dependency on prebuilt components while maintaining full functionality

---

🧪 Testing Requirements

• Test all hooks in headless mode without rendering any components
• Verify event callbacks work as expected
• Simulate SSR environment to confirm safety
• Test integration with custom UI components
• Validate error handling for unsupported operations

---

📚 Documentation Requirements

• Add “Headless Mode” section to README
• Provide full usage example:

const { quotes, refresh } = useBridgeQuotes({ autoRefreshQuotes: true });
const { isValid, errors } = useTokenValidation("USDC", "Ethereum", "Stellar");

• Include examples with network switching, slippage, fee estimation, and transaction tracking
• Document SSR considerations and configuration options

---

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 150 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[KingFRANKHOOD]

@KingFRANKHOOD has applied to work on this issue as part of the Stellar Wave Program's 2nd wave.

Hello, I’m a full stack developer with hands-on experience building with variety of tools including Nextjs, nodejs, nestjs, React, Typescript and more

I focus on writing clear, maintainable code and making sure features work as expected end to end, not just in isolation. I communicate progress regularly and keep things transparent as I work. I’m confident I can complete this task within an ETA of 12 HOURS

ℹ️ Repo Maintainers: To accept this application, review their application or assign @KingFRANKHOOD to this issue.