npm package: @liquid-core/react-sdk
Description: Customizable React SDK to supercharge crypto applications with intelligence
Author: Liquid Labs
Latest version: 1.0.9

# @liquid-core/react-sdk

Add AI-powered features to your React app in minutes. Simple setup, powerful capabilities.

## 🚀 Quick Start

### 1. Install

```bash
npm install @liquid-core/react-sdk
```

### 2. Wrap your app

```tsx
import { LiquidProvider } from "@liquid-core/react-sdk";

export default function App() {
  return (
    <LiquidProvider config={{ appId: "your-app-id" }}>
      <YourApp />
    </LiquidProvider>
  );
}
```

### 3. Use anywhere in your app

```tsx
import { useLiquid } from "@liquid-core/react-sdk";

function MyComponent() {
  const { ask } = useLiquid();

  return (
    <button
      onClick={() =>
        ask({
          userWalletAddresses: ["0x1234...abcd"],
        })
      }
    >
      Ask AI
    </button>
  );
}
```

## ✨ What You Get

**Liquid SDK covers 3 main use cases:**

1. **💬 Conversation** - Full AI chat interface with beautiful UI
2. **🔍 Token Discovery** - Discover tokens with natural language queries
3. **📊 AI Summary** - Get intelligent summaries of tokens and topics

## 📖 Use Cases & Examples

### 1. Conversational AI (with UI)

Opens a beautiful chat modal where users can talk to AI about crypto, DeFi, and more.

```tsx
function ChatButton() {
  const { ask } = useLiquid();

  const openChat = () => {
    ask({
      userWalletAddresses: ["0x1234567890123456789012345678901234567890"],
      message: "What's my portfolio worth?", // Optional: pre-fill message
    });
  };

  return <button onClick={openChat}>Chat with AI</button>;
}
```

### 2. Token Discovery

Discover tokens using natural language queries without showing any UI.

```tsx
function TokenDiscovery() {
  const { discover } = useLiquid();
  const [results, setResults] = useState([]);

  const findTokens = async () => {
    try {
      const tokens = await discover("tokens under $1M market cap");
      setResults(tokens); // Use directly - no parsing needed!
      console.log("Found tokens:", tokens);
      console.log(`Found ${tokens.length} tokens`);
    } catch (error) {
      console.error("Discovery failed:", error);
    }
  };

  return <button onClick={findTokens}>Discover Tokens</button>;
}
```

### 3. AI Summary

Get AI summaries of tokens, topics, or any crypto-related content.

```tsx
function TokenSummary() {
  const { getAiSummary, isStreaming, messages } = useLiquid();

  const getSummary = async () => {
    try {
      await getAiSummary(
        "Summarize Solana token: Ey59PH7Z4BFU4HjyKnyMdWt5GGN76KazTAwQihoUXRnk"
      );
    } catch (error) {
      console.error("Summary failed:", error);
    }
  };

  return (
    <div>
      <button onClick={getSummary} disabled={isStreaming}>
        Get Summary
      </button>

      {isStreaming && <p>AI is thinking...</p>}

      {messages.map((msg, idx) => (
        <div key={idx}>{msg.content}</div>
      ))}
    </div>
  );
}
```

## ⚙️ Configuration Options

| Parameter    | Type       | Required    | Default             | Description                   |
| ------------ | ---------- | ----------- | ------------------- | ----------------------------- |
| `appId`      | `string`   | ✅ Yes      | -                   | Your unique app identifier    |
| `modalStyle` | `string`   | ❌ Optional | `"halfBottomSheet"` | How the modal appears         |
| `chains`     | `string[]` | ❌ Optional | `["solana"]`        | Supported blockchain networks |
| `mode`       | `string`   | ❌ Optional | `"light"`           | UI theme (light/dark)         |

### Modal Styles

- `"halfBottomSheet"` - Half screen on mobile, centered on desktop
- `"fullBottomSheet"` - Full screen on mobile, large on desktop
- `"modal"` - Centered modal on all devices
- `"panel"` - Side panel sliding from right

### Supported Chains

- `"solana"` - Solana blockchain
- `"base"` - Base blockchain
- `"ink"` - Ink blockchain

### Example with All Options

```tsx
<LiquidProvider
  config={{
    appId: "my-defi-app",
    modalStyle: "modal",
    chains: ["solana", "base", "ink"],
    mode: "dark",
  }}
>
  <App />
</LiquidProvider>
```

## 🎯 Complete Hook API

The `useLiquid()` hook gives you everything you need:

```tsx
const {
  // Main functions
  ask, // Open conversational AI modal
  closeAi, // Close the modal programmatically
  getAiSummary, // Get AI summary (no UI)
  discover, // Discover tokens with natural language (no UI)

  // State
  isOpen, // Whether modal is currently open
  messages, // All conversation messages
  isStreaming, // Whether AI is currently responding
} = useLiquid();
```

## 💡 Pro Tips

- **Wallet addresses**: Always provide user wallet addresses for personalized responses
- **Error handling**: Wrap API calls in try-catch blocks
- **Loading states**: Use `isStreaming` to show loading indicators
- **Pre-fill messages**: Add `message` parameter to `ask()` for auto-send

## 🔗 TypeScript Support

Full TypeScript support included. Import types:

```tsx
import type {
  LiquidConfig,
  AskLiquidParams,
  Chain,
  ModalStyle,
} from "@liquid-core/react-sdk";
```

## 📋 Requirements

- React ≥ 16.8.0
- Node.js ≥ 18

## 🆘 Need Help?

- [Documentation](https://docs.useliquid.xyz)
- [GitHub Issues](https://github.com/liquid-labs/sdks/issues)
- [Discord Community](https://discord.gg/liquid)

---

**Built by the Liquid team** • [Website](https://useliquid.xyz) • [Twitter](https://twitter.com/useliquid)